refactor: Split to griffe, griffecli and griffelib uv workspaces

Issue-408: #408
PR-434: #434
Co-authored-by: Timothée Mazzucotelli <dev@pawamoy.fr>

Author: johnslavik

config/coverage.ini

@@ -2,7 +2,8 @@
 branch = true
 parallel = true
 source =
-  src/griffe
+  packages/griffelib/src/griffe
+  packages/griffecli/src/griffecli
   tests/
 
 [coverage:paths]

config/ruff.toml

@@ -33,29 +33,30 @@ ignore = [
     "TD002",  # Missing author in TODO
     "TD003",  # Missing issue link on the line following this TODO
     "TRY003",  # Avoid specifying long messages outside the exception class
+    "UP007",  # Use `X | Y` for type annotations
 ]
 
 logger-objects = ["griffe.logger"]
 
 [lint.per-file-ignores]
-"src/griffe/__main__.py" = [
+"packages/griffecli/src/griffecli/__main__.py" = [
     "D100",  # Missing module docstring
 ]
-"src/griffe/_internal/cli.py" = [
+"packages/griffecli/src/griffecli/_internal/cli.py" = [
     "T201",  # Print statement
 ]
-"src/griffe/_internal/git.py" = [
+"packages/griffelib/src/griffe/_internal/git.py" = [
     "S603",  # `subprocess` call: check for execution of untrusted input
     "S607",  # Starting a process with a partial executable path
 ]
-"src/griffe/_internal/agents/nodes/*.py" = [
+"packages/griffelib/src/griffe/_internal/agents/nodes/*.py" = [
     "ARG001",  # Unused function argument
     "N812",  # Lowercase `keyword` imported as non-lowercase `NodeKeyword`
 ]
-"src/griffe/_internal/debug.py" = [
+"packages/griffelib/src/griffe/_internal/debug.py" = [
     "T201",  # Print statement
 ]
-"src/griffe/_internal/**.py" = [
+"packages/griffelib/src/griffe/_internal/**.py" = [
     "D100",  # Missing docstring in public module
 ]
 "scripts/*.py" = [
@@ -84,7 +85,7 @@ docstring-quotes = "double"
 ban-relative-imports = "all"
 
 [lint.isort]
-known-first-party = ["griffe"]
+known-first-party = ["griffe", "griffecli"]
 
 [lint.pydocstyle]
 convention = "google"

docs/guide/contributors/architecture.md

@@ -23,7 +23,7 @@ descriptions = {
     "site": "Documentation site, built with `make run mkdocs build` (git-ignored).",
     "src": "The source of our Python package(s). See [Sources](#sources) and [Program structure](#program-structure).",
     "src/griffe": "Our public API, exposed to users. See [Program structure](#program-structure).",
-    "src/griffe/_internal": "Our internal API, hidden from users. See [Program structure](#program-structure).",
+    "packages/griffelib/src/griffe/_internal": "Our internal API, hidden from users. See [Program structure](#program-structure).",
     "tests": "Our test suite. See [Tests](#tests).",
     ".copier-answers.yml": "The answers file generated by [Copier](https://copier.readthedocs.io/en/stable/). See [Boilerplate](#boilerplate).",
     "devdeps.txt": "Our development dependencies specification. See [`make setup`][command-setup] command.",
@@ -98,19 +98,31 @@ The tools used in tasks have their configuration files stored in the `config` fo
 
 ## Sources
 
-Sources are located in the `src` folder, following the [src-layout](https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/). We use [PDM-Backend](https://backend.pdm-project.org/) to build source and wheel distributions, and configure it in `pyproject.toml` to search for packages in the `src` folder.
+Sources are located in the `packages/` subfolders, following the [src-layout](https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/).
+We use [Hatch](https://hatch.pypa.io/latest/) 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 `pyproject.toml` to get the full list of files included in our source distributions.
+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](https://docs.pytest.org/en/8.2.x/). 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
 
-The internal API is contained within the `src/griffe/_internal` folder. The top-level `griffe/__init__.py` module exposes all the public API, by importing the internal objects from various submodules of `griffe._internal`.
+Griffe is split into two pieces: the library and the CLI.
 
-Users then import `griffe` directly, or import objects from it.
+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 :shrug: 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.
 
@@ -122,7 +134,7 @@ if os.getenv("DEPLOY") == "true":
     from pydeps.target import Target
 
     cli.verbose = cli._not_verbose
-    options = cli.parse_args(["src/griffe", "--noshow", "--reverse"])
+    options = cli.parse_args(["packages/griffelib/src/griffe", "--noshow", "--reverse"])
     colors.START_COLOR = 128
     target = Target(options["fname"])
     with target.chdir_work():

docs/guide/contributors/workflow.md

@@ -56,7 +56,11 @@ Deprecated code should also be marked as legacy code. We use [Yore](https://pawa
 
 Examples:
 
-```python title="Remove function when we bump to 2.0"
+```python title="Remove function when we bump to 5.0"
+# YORE: Bump 5: Remove block.
+def deprecated_function():
+    ...
+```
 
 ```python title="Simplify imports when Python 3.15 is EOL"
 # YORE: EOL 3.15: Replace block with line 4.

docs/installation.md

@@ -59,6 +59,67 @@ Griffe is a Python package, so you can install it with your favorite Python pack
 
     </div>
 
+## Install as a library only
+
+If you only need the library for API introspection and analysis without the CLI tool, you can install `griffelib`:
+
+=== ":simple-python: pip"
+     ```bash
+     pip install griffelib
+     ```
+
+     <div class="result" markdown>
+
+     [pip](https://pip.pypa.io/en/stable/) is the main package installer for Python.
+
+     </div>
+
+=== ":simple-pdm: pdm"
+     ```bash
+     pdm add griffelib
+     ```
+
+     <div class="result" markdown>
+
+     [PDM](https://pdm-project.org/en/latest/) is an all-in-one solution for Python project management.
+
+     </div>
+
+=== ":simple-poetry: poetry"
+     ```bash
+     poetry add griffelib
+     ```
+
+     <div class="result" markdown>
+
+     [Poetry](https://python-poetry.org/) is an all-in-one solution for Python project management.
+
+     </div>
+
+=== ":simple-rye: rye"
+     ```bash
+     rye add griffelib
+     ```
+
+     <div class="result" markdown>
+
+     [Rye](https://rye.astral.sh/) is an all-in-one solution for Python project management, written in Rust.
+
+     </div>
+
+=== ":simple-astral: uv"
+     ```bash
+     uv add griffelib
+     ```
+
+     <div class="result" markdown>
+
+     [uv](https://docs.astral.sh/uv/) is an extremely fast Python package and project manager, written in Rust.
+
+     </div>
+
+This installs the `griffe` package as usual, but without the CLI program and its dependencies.
+
 ## Install as a tool only
 
 === ":simple-python: pip"
@@ -104,3 +165,17 @@ Griffe is a Python package, so you can install it with your favorite Python pack
     [uv](https://docs.astral.sh/uv/) is an extremely fast Python package and project manager, written in Rust.
 
     </div>
+
+## Running Griffe
+
+Once installed, you can run Griffe using the `griffe` command:
+
+```console
+$ griffe check mypackage
+```
+
+Or as a Python module:
+
+```console
+$ python -m griffe check mypackage
+```

docs/reference/api/cli.md

@@ -2,12 +2,12 @@
 
 ## **Main API**
 
-::: griffe.main
+::: griffecli.main
 
-::: griffe.check
+::: griffecli.check
 
-::: griffe.dump
+::: griffecli.dump
 
 ## **Advanced API**
 
-::: griffe.get_parser
+::: griffecli.get_parser

docs/reference/api/loggers.md

@@ -10,7 +10,7 @@
 
 ::: griffe.LogLevel
 
-::: griffe.DEFAULT_LOG_LEVEL
+::: griffecli.DEFAULT_LOG_LEVEL
     options:
         annotations_path: full
 

duties.py

@@ -24,7 +24,7 @@
     from duty.context import Context
 
 
-PY_SRC_PATHS = (Path(_) for _ in ("src", "tests", "duties.py", "scripts"))
+PY_SRC_PATHS = (Path(_) for _ in ("packages/griffecli/src", "packages/griffelib/src", "tests", "duties.py", "scripts"))
 PY_SRC_LIST = tuple(str(_) for _ in PY_SRC_PATHS)
 PY_SRC = " ".join(PY_SRC_LIST)
 CI = os.environ.get("CI", "0") in {"1", "true", "yes", ""}
@@ -287,14 +287,27 @@ def check_api(ctx: Context, *cli_args: str) -> None:
     ctx.run(
         tools.griffe.check(
             "griffe",
-            search=["src"],
+            search=["packages/griffelib/src"],
             color=True,
             extensions=[
                 "griffe_inherited_docstrings",
                 "unpack_typeddict",
             ],
         ).add_args(*cli_args),
-        title="Checking for API breaking changes",
+        title="Checking for API breaking changes in Griffe library",
+        nofail=True,
+    )
+    ctx.run(
+        tools.griffe.check(
+            "griffecli",
+            search=["packages/griffecli/src"],
+            color=True,
+            extensions=[
+                "griffe_inherited_docstrings",
+                "unpack_typeddict",
+            ],
+        ).add_args(*cli_args),
+        title="Checking for API breaking changes in Griffe CLI",
         nofail=True,
     )
 

mkdocs.yml

@@ -4,7 +4,7 @@ site_url: "https://mkdocstrings.github.io/griffe"
 repo_url: "https://github.com/mkdocstrings/griffe"
 repo_name: "mkdocstrings/griffe"
 site_dir: "site"
-watch: [mkdocs.yml, README.md, CONTRIBUTING.md, CHANGELOG.md, src]
+watch: [mkdocs.yml, README.md, CONTRIBUTING.md, CHANGELOG.md, packages]
 copyright: Copyright © 2021 Timothée Mazzucotelli
 edit_uri: edit/main/docs/
 
@@ -218,7 +218,7 @@ plugins:
         - url: https://docs.python.org/3/objects.inv
           domains: [std, py]
         - https://typing-extensions.readthedocs.io/en/latest/objects.inv
-        paths: [src, scripts, .]
+        paths: [packages/griffelib/src, packages/griffecli/src, scripts, .]
         options:
           backlinks: tree
           docstring_options:

packages/griffecli/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+# pdm-backend is left here as a dependency of the version discovery script currently in use.
+# It may be removed in the future. See mkdocstrings/griffe#430
+requires = ["hatchling", "pdm-backend", "uv-dynamic-versioning>=0.7.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "griffecli"
+description = "Signatures for entire Python programs. Extract the structure, the frame, the skeleton of your project, to generate API documentation or find breaking changes in your API."
+authors = [{name = "Timothée Mazzucotelli", email = "dev@pawamoy.fr"}]
+license = "ISC"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+keywords = ["api", "signature", "breaking-changes", "static-analysis", "dynamic-analysis"]
+dynamic = ["version", "dependencies"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    # YORE: EOL 3.10: Remove line.
+    "Programming Language :: Python :: 3.10",
+    # YORE: EOL 3.11: Remove line.
+    "Programming Language :: Python :: 3.11",
+    # YORE: EOL 3.12: Remove line.
+    "Programming Language :: Python :: 3.12",
+    # YORE: EOL 3.13: Remove line.
+    "Programming Language :: Python :: 3.13",
+    # YORE: EOL 3.14: Remove line.
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Documentation",
+    "Topic :: Software Development",
+    "Topic :: Software Development :: Documentation",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+
+[project.scripts]
+griffecli = "griffecli:main"
+
+[tool.hatch.version]
+source = "code"
+path = "../../scripts/get_version.py"
+expression = "get_version()"
+
+[tool.hatch.build.targets.sdist.force-include]
+"../../CHANGELOG.md" = "CHANGELOG.md"
+"../../LICENSE" = "LICENSE"
+"../../README.md" = "README.md"
+
+[tool.hatch.metadata.hooks.uv-dynamic-versioning]
+# Dependencies are dynamically versioned; {{version}} is substituted at build time.
+dependencies = ["griffelib=={{version}}", "colorama>=0.4"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/griffecli"]
+
+[tool.uv.sources]
+griffelib = { workspace = true }