Project architecture¤

This document describes how the project is architectured, both regarding boilerplate and actual code. We start by giving an overview of the project's contents:

.git/
.github/ # (1)!
.venv/ # (2)!
.venvs/ # (3)!
.vscode/ # (4)!
.zed/ # (5)!
config/ # (6)!
docs/ # (7)!
htmlcov/ # (8)!
packages/ # (9)!
scripts/ # (10)!
site/ # (11)!
.copier-answers.yml # (12)!
.envrc # (13)!
.gitignore
AI_POLICY.md
CHANGELOG.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE
Makefile # (14)!
README.md
duties.py # (15)!
logo.svg
pyproject.toml # (16)!
uv.lock
zensical.toml

1. GitHub workflows, issue templates and other configuration.

   ISSUE_TEMPLATE/ # (1)!
   workflows/ # (2)!
   FUNDING.yml
   pull_request_template.md
   

   1. 1-bug.md
      2-feature.md
      3-docs.md
      4-change.md
      config.yml
      

   2. ci.yml
      release.yml
      security.yml
      sponsors.yml
      

2. The default virtual environment (git-ignored). See make setup command.

3. The virtual environments for all supported Python versions (git-ignored). See make setup command.

4. The configuration for VSCode (git-ignored). See make vscode command.

   configurationCache.log
   dryrun.log
   launch.json
   settings.json
   targets.log
   tasks.json
   

5. debug.json
   settings.json
   tasks.json
   

6. Contains our tooling configuration. See Scripts, configuration.

   vscode/ # (1)!
   zed/ # (2)!
   coverage.ini
   git-changelog.toml
   pytest.ini
   ruff.toml
   ty.toml
   

   1. launch.json
      settings.json
      tasks.json
      

   2. debug.json
      settings.json
      tasks.json
      

7. Documentation sources (Markdown pages). See make docs task.

   .overrides/ # (1)!
   community/ # (2)!
   css/ # (3)!
   extensions/ # (4)!
   getting-started/ # (5)!
   guide/ # (6)!
   img/ # (7)!
   js/ # (8)!
   reference/ # (9)!
   alternatives.md
   changelog.md
   code-of-conduct.md
   contributing.md
   credits.md
   downstream-projects.md
   getting-help.md
   griffe.json
   index.md
   installation.md
   introduction.md
   license.md
   logo.svg
   playground.md
   schema-docstrings-options.json
   schema.json
   

   1. Customization of Material for MkDocs' templates.

      partials/ # (1)!
      main.html
      

      1. comments.html
         

   2. index.md
      

   3. ansi.css
      apidocs.css
      custom.css
      pyodide.css
      

   4. built-in/ # (1)!
      official/ # (2)!
      third-party/ # (3)!
      index.md
      

      1. dataclasses.md
         index.md
         unpack-typeddict.md
         

      2. autodocstringstyle.md
         index.md
         inherited-docstrings.md
         public-redundant-aliases.md
         public-wildcard-imports.md
         pydantic.md
         runtime-objects.md
         sphinx.md
         typingdoc.md
         warnings-deprecated.md
         

      3. docstring-inheritance.md
         fastapi.md
         fieldz.md
         generics.md
         index.md
         inherited-method-crossrefs.md
         modernized-annotations.md
         

   5. index.md
      

   6. contributors/ # (1)!
      users/ # (2)!
      index.md
      

      1. architecture.md
         commands.md
         index.md
         setup.md
         workflow.md
         

      2. how-to/ # (1)!
         recommendations/ # (2)!
         checking.md
         extending.md
         index.md
         loading.md
         navigating.md
         serializing.md
         

         1. parse-docstrings.md
            selectively-inspect.md
            set-docstring-styles.md
            set-git-info.md
            support-decorators.md
            

         2. docstrings.md
            public-apis.md
            python-code.md
            

   7. favicon.ico
      gha_annotations_1.png
      gha_annotations_2.png
      

   8. feedback.js
      pyodide.js
      

   9. api/ # (1)!
      cli.md
      docstrings.md
      index.md
      

      1. Python API reference, injected with mkdocstrings.

         docstrings/ # (1)!
         models/ # (2)!
         agents.md
         checks.md
         cli.md
         exceptions.md
         expressions.md
         extensions.md
         finder.md
         helpers.md
         index.md
         loaders.md
         loggers.md
         serializers.md
         

         1. index.md
            models.md
            parsers.md
            

         2. alias.md
            attribute.md
            class.md
            function.md
            index.md
            module.md
            type_alias.md
            

8. HTML report for Python code coverage (git-ignored), integrated in the Coverage report page. See make coverage task.

9. griffecli/ # (1)!
   griffelib/ # (2)!
   

   1. src/ # (1)!
      tests/ # (2)!
      pyproject.toml
      

      1. griffecli/ # (1)!
         

         1. _internal/ # (1)!
            __init__.py
            __main__.py
            py.typed
            

            1. __init__.py
               cli.py
               

      2. Our test suite. See Tests.

         __init__.py
         test_cli.py
         

   2. src/ # (1)!
      tests/ # (2)!
      pyproject.toml
      

      1. griffe/ # (1)!
         

         1. _internal/ # (1)!
            __init__.py
            __main__.py
            py.typed
            

            1. Our internal API, hidden from users. See Program structure.

               agents/ # (1)!
               docstrings/ # (2)!
               extensions/ # (3)!
               __init__.py
               c3linear.py
               collections.py
               debug.py
               diff.py
               encoders.py
               enumerations.py
               exceptions.py
               expressions.py
               finder.py
               git.py
               helpers.py
               importer.py
               loader.py
               logger.py
               merger.py
               mixins.py
               models.py
               stats.py
               

               1. nodes/ # (1)!
                  __init__.py
                  inspector.py
                  parser.py
                  visitor.py
                  

                  1. __init__.py
                     assignments.py
                     ast.py
                     docstrings.py
                     exports.py
                     imports.py
                     parameters.py
                     runtime.py
                     values.py
                     

               2. __init__.py
                  auto.py
                  google.py
                  models.py
                  numpy.py
                  parsers.py
                  sphinx.py
                  utils.py
                  

               3. __init__.py
                  base.py
                  dataclasses.py
                  unpack_typeddict.py
                  

      2. Our test suite. See Tests.

         fixtures/
         test_docstrings/ # (1)!
         test_extensions/ # (2)!
         __init__.py
         conftest.py
         helpers.py
         test_api.py
         test_diff.py
         test_encoders.py
         test_expressions.py
         test_finder.py
         test_functions.py
         test_git.py
         test_inheritance.py
         test_inspector.py
         test_loader.py
         test_merger.py
         test_mixins.py
         test_models.py
         test_nodes.py
         test_parser.py
         test_public_api.py
         test_stdlib.py
         test_visitor.py
         

         1. __init__.py
            conftest.py
            helpers.py
            test_auto.py
            test_google.py
            test_numpy.py
            test_sphinx.py
            test_warnings.py
            

         2. __init__.py
            test_base.py
            test_dataclasses.py
            test_unpack_typeddict.py
            

10. Our different scripts. See Scripts, configuration.

    gen_credits.py
    gen_griffe_json.py
    gen_structure_docs.py
    get_version.py
    make
    make.py
    

11. Documentation site, built with make run mkdocs build (git-ignored).

12. The answers file generated by Copier. See Boilerplate.

13. The environment configuration, automatically sourced by direnv. See commands.

14. A dummy makefile, only there for auto-completion. See commands.

15. Our project tasks, written with duty. See Tasks.

16. The project metadata and production dependencies.

Boilerplate¤

This project's skeleton (the file-tree shown above) is actually generated from a Copier template called copier-uv. When generating the project, Copier asks a series of questions (configured by the template itself), and the answers are used to render the file and directory names, as well as the file contents. Copier also records answers in the .copier-answers.yml file, allowing to update the project with latest changes from the template while reusing previous answers.

To update the project (in order to apply latest changes from the template), we use the following command:

copier update --trust --skip-answered

Scripts, configuration¤

We have a few scripts that let us manage the various maintenance aspects for this project. The entry-point is the make script located in the scripts folder. It doesn't need any dependency to be installed to run. See Management commands for more information.

The make script can also invoke what we call "tasks". Tasks need our development dependencies to be installed to run. These tasks are written in the duties.py file, and the development dependencies are listed in devdeps.txt.

The tools used in tasks have their configuration files stored in the config folder, to unclutter the root of the repository. The tasks take care of calling the tools with the right options to locate their respective configuration files.

Sources¤

Sources are located in the packages/ subfolders, following the src-layout. We use Hatch to build source and wheel distributions, and configure it in pyproject.toml.

Tests¤

Our test suite is located in the tests folder. It is located outside of the sources as to not pollute distributions (it would be very wrong to publish a tests package as part of our distributions, since this name is extremely common), or worse, the public API. The tests folder is however included in our source distributions (.tar.gz), alongside most of our metadata and configuration files. Check out our pyproject.toml files to get the full list of files included in our source distributions for every individual package within the packages/ folder.

The test suite is based on pytest. Test modules reflect our internal API structure, and except for a few test modules that test specific aspects of our API, each test module tests the logic from the corresponding module in the internal API. For example, test_finder.py tests code of the griffe._internal.finder internal module, while test_functions tests our ability to extract correct information from function signatures, statically. The general rule of thumb when writing new tests is to mirror the internal API. If a test touches to many aspects of the loading process, it can be added to the test_loader test module.

Program structure¤

Griffe is split into two pieces: the library and the CLI.

Each of them has an internal API contained within an _internal folder:

• packages/griffelib/src/griffe/_internal for the library,
• packages/griffecli/src/griffecli/_internal for the CLI.

Griffe can be installed in library-only mode, which means that the CLI package from packages/griffecli is not present. Library-only mode can be preferred if the user does not utilize the CLI functionality of Griffe and does not want to incorporate its dependencies.

The top-level packages/griffelib/src/griffe/__init__.py module exposes all the public API available: it always re-exports internal objects from various submodules of griffe._internal and, if the CLI is installed, it re-exports the public API of griffecli as well.

Users then import griffe directly, or import objects from it. If they don't have griffecli installed, they cannot import the CLI-related functionality, such as griffecli.check.

We'll be honest: our code organization is not the most elegant, but it works Have a look at the following module dependency graph, which will basically tell you nothing except that we have a lot of inter-module dependencies. Arrows read as "imports from". The code base is generally pleasant to work with though.

You can zoom and pan all diagrams on this page with mouse inputs.

The following sections are generated automatically by iterating on the modules of our public and internal APIs respectively, and extracting the comment blocks at the top of each module. The comment blocks are addressed to readers of the code (maintainers, contributors), while module docstrings are addressed to users of the API. Module docstrings in our internal API are never written, because our module layout is hidden, and therefore modules aren't part of the public API, so it doesn't make much sense to write "user documentation" in them.

CLI entrypoint¤

griffe.__main__¤

SPDX-License-Identifier: ISC

Public API¤

griffe¤

SPDX-License-Identifier: ISC

Internal API¤

SPDX-License-Identifier: ISC

agents¤

SPDX-License-Identifier: ISC

inspector.py¤

SPDX-License-Identifier: ISC

nodes¤

SPDX-License-Identifier: ISC

assignments.py¤

SPDX-License-Identifier: ISC

ast.py¤

SPDX-License-Identifier: ISC

docstrings.py¤

SPDX-License-Identifier: ISC

exports.py¤

SPDX-License-Identifier: ISC

imports.py¤

SPDX-License-Identifier: ISC

parameters.py¤

SPDX-License-Identifier: ISC

runtime.py¤

SPDX-License-Identifier: ISC

values.py¤

SPDX-License-Identifier: ISC

parser.py¤

SPDX-License-Identifier: ISC

Copyright (c) 2021, Timothée Mazzucotelli and contributors

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

visitor.py¤

SPDX-License-Identifier: ISC

c3linear.py¤

This module contains a single function, c3linear_merge. The function is generic enough to be in its own module.

• Copyright (c) 2019 Vitaly R. Samigullin
• Adapted from https://github.com/pilosus/c3linear
• Adapted from https://github.com/tristanlatr/pydocspec

collections.py¤

SPDX-License-Identifier: ISC

debug.py¤

SPDX-License-Identifier: ISC

diff.py¤

SPDX-License-Identifier: ISC

docstrings¤

SPDX-License-Identifier: ISC

auto.py¤

SPDX-License-Identifier: ISC

google.py¤

SPDX-License-Identifier: ISC

models.py¤

SPDX-License-Identifier: ISC

numpy.py¤

SPDX-License-Identifier: ISC

parsers.py¤

SPDX-License-Identifier: ISC

sphinx.py¤

SPDX-License-Identifier: ISC

utils.py¤

SPDX-License-Identifier: ISC

encoders.py¤

SPDX-License-Identifier: ISC

enumerations.py¤

SPDX-License-Identifier: ISC

exceptions.py¤

SPDX-License-Identifier: ISC

expressions.py¤

SPDX-License-Identifier: ISC

extensions¤

SPDX-License-Identifier: ISC

base.py¤

SPDX-License-Identifier: ISC

dataclasses.py¤

SPDX-License-Identifier: ISC

unpack_typeddict.py¤

SPDX-License-Identifier: ISC

finder.py¤

SPDX-License-Identifier: ISC

git.py¤

SPDX-License-Identifier: ISC

helpers.py¤

SPDX-License-Identifier: ISC

importer.py¤

SPDX-License-Identifier: ISC

loader.py¤

SPDX-License-Identifier: ISC

logger.py¤

SPDX-License-Identifier: ISC

merger.py¤

SPDX-License-Identifier: ISC

mixins.py¤

SPDX-License-Identifier: ISC

models.py¤

SPDX-License-Identifier: ISC

stats.py¤

SPDX-License-Identifier: ISC