change: Reorganize as `griffe` and `griffelib` packages with uv workspaces #434

johnslavik · 2025-11-30T19:31:07Z

Continuation of #431, based on #433, closes #408
Migration script: https://gist.github.com/johnslavik/76d556a427033c4de2d236d67aa05b8f

johnslavik · 2025-11-30T20:20:24Z

Let's try Copilot here

johnslavik · 2025-11-30T20:26:57Z

@copilot We've migrated griffe to 3 packages exposed by griffe package in a backward-compatible way, all bound by uv dynamic versioning that ensures compatibility. griffecli is supposed to only implement and expose CLI (which needs proper configuration in pyproject.toml) and depend on griffelib=={{version}}. griffelib is supposed depend on nothing and implement the necessary logic. griffe is supposed to be a backward-compatible package depending on both griffelib and griffecli, with all the previous packaging and runtime behaviors in regular use as before the migration.

Fix any instances of name errors (import griffe, but then griffelib is used, etc.), inconsistencies caused by the migration, and any references broken by the migration script. Make sure that the griffecli's init module is correct. Do complete whatever the migration script missed, making sure the migration is fully complete and backward-compatible. Update the documentation to reflect new changes, if necessary. Document all changes that you've made.

Copilot · 2025-11-30T20:27:05Z

@johnslavik I've opened a new pull request, #435, to work on those changes. Once the pull request is ready, I'll request review from you.

johnslavik · 2025-11-30T21:14:55Z

@copilot Add missing configuration from pyproject.toml (check CI failures) and make sure that we promote the old way of running things (griffe check, not griffecli check; python -m griffe, not python -m griffecli) -- but document that it is possible to use python -m griffecli instead of python -m griffe where it makes sense.

Copilot · 2025-11-30T21:15:04Z

@johnslavik I've opened a new pull request, #436, to work on those changes. Once the pull request is ready, I'll request review from you.

johnslavik · 2025-12-01T00:00:17Z

@copilot Look at https://github.com/mkdocstrings/griffe/actions/runs/19806731977/job/56741990187?pr=434. Fix all incorrect refs

Copilot · 2025-12-01T00:00:27Z

@johnslavik I've opened a new pull request, #437, to work on those changes. Once the pull request is ready, I'll request review from you.

Co-authored-by: johnslavik <[email protected]>

…[pypi] Co-authored-by: johnslavik <[email protected]>

Co-authored-by: johnslavik <[email protected]>

pawamoy · 2025-12-02T14:51:54Z

packages/griffecli/src/griffecli/__init__.py

+- [`griffecli.main`][]: Run the main program.
+- [`griffecli.check`][]: Check for API breaking changes in two versions of the same package.
+- [`griffecli.dump`][]: Load packages data and dump it as JSON.
+- [`griffecli.get_parser`][]: Get the argument parser for the CLI.


I see a mix of cross-ref, some using griffe.*, some using griffecli.* or griffelib.*, we should make them consistent.

Yes -- I'd opt for griffe where possible, as in #434 (comment)

pawamoy · 2025-12-02T14:55:00Z

packages/griffelib/src/griffelib/_internal/diff.py

        # Absolute file path probably means temporary worktree.
        # We use our worktree prefix to remove some components
-        # of the path on the left (`/tmp/griffe-worktree-*/griffe_*/repo`).
+        # of the path on the left (`/tmp/griffelib-worktree-*/griffe_*/repo`).


I think we could keep these foders named "griffe" rather than "griffelib", as the distinction is not important in this case.

pawamoy · 2025-12-02T14:56:50Z

packages/griffelib/src/griffelib/_internal/finder.py

    if _match_pattern(path.name, (*_editable_editables_patterns, *_editable_scikit_build_core_patterns)):
        # Support for how 'editables' write these files:
-        # example line: `F.map_module('griffe', '/media/data/dev/griffe/src/griffe/__init__.py')`.
+        # example line: `F.map_module('griffelib', '/media/data/dev/griffelib/packages/griffelib/src/griffelib/__init__.py')`.


I think it's fine if we keep the previous version of these comments as they're just examples (and still valid I believe even after the migration).

pawamoy · 2025-12-02T14:57:09Z

packages/griffelib/src/griffelib/_internal/git.py

    with TemporaryDirectory(prefix=f"{_WORKTREE_PREFIX}{repo_name}-{normref}-") as tmp_dir:
        location = os.path.join(tmp_dir, normref)  # noqa: PTH118
-        tmp_branch = f"griffe-{normref}"  # Temporary branch name must not already exist.
+        tmp_branch = f"griffelib-{normref}"  # Temporary branch name must not already exist.


We could keep using griffe, see previous comment.

pawamoy · 2025-12-02T14:57:32Z

packages/griffelib/src/griffelib/_internal/loader.py

    import platformdirs  # noqa: PLC0415

-    pypi_cache_dir = Path(platformdirs.user_cache_dir("griffe"))
+    pypi_cache_dir = Path(platformdirs.user_cache_dir("griffelib"))


Same here, we could keep using griffe.

pawamoy · 2025-12-02T14:59:37Z

scripts/gen_griffe_json.py

 data = python_handler.collect("griffe", options=python_handler.get_options({}))

-with mkdocs_gen_files.open("griffe.json", "w") as fd:
+with mkdocs_gen_files.open("griffelib.json", "w") as fd:


We'll have to update this somehow, to contain griffe, griffecli and griffelib.

pawamoy · 2025-12-02T15:00:07Z

scripts/gen_structure_docs.py

    src = root / "src"
    public_api = src / "griffe"
-    print(f"{'#' * heading_level} `griffe.__main__`\n")
+    print(f"{'#' * heading_level} `griffelib.__main__`\n")


Should probably be griffe or griffecli rather than grifflib here.

johnslavik force-pushed the b/migrate branch from cc4c9c5 to e9221d0 Compare November 30, 2025 19:53

Copilot AI mentioned this pull request Nov 30, 2025

change: Reorganize as griffe and griffelib packages with uv workspaces #435

Merged

2 tasks

Copilot AI mentioned this pull request Nov 30, 2025

Fix pyproject.toml workspace config and restore griffe CLI branding #436

Merged

2 tasks

Copilot AI mentioned this pull request Dec 1, 2025

[WIP] Change: Reorganize as griffe and griffelib packages with uv workspaces #437

Closed

10 tasks

johnslavik and others added 12 commits December 2, 2025 15:35

Fix NameError & reformat everything

5835e69

Apply suggestions from code review

adb5807

Run migration script

8721cf5

Initial plan

5ab0e55

Fix griffelib/griffecli separation and add proper exports

91ebbb6

Co-authored-by: johnslavik <[email protected]>

Fix test imports and paths for new package structure

c9fe781

Co-authored-by: johnslavik <[email protected]>

Address code review feedback on comments and documentation

a85b87d

Co-authored-by: johnslavik <[email protected]>

Add version locking for griffe's dependencies on griffelib and griffecli

6b60e22

Co-authored-by: johnslavik <[email protected]>

Use double brackets for version interpolation and re-export griffelib…

20e7d97

…[pypi] Co-authored-by: johnslavik <[email protected]>

Initial plan

e26db96

Fix missing pyproject.toml config and CLI program name

879be4e

Co-authored-by: johnslavik <[email protected]>

Fix griffe._internal references to griffelib._internal in docs

1c3b869

Co-authored-by: johnslavik <[email protected]>

pawamoy force-pushed the b/migrate branch from e254389 to 1c3b869 Compare December 2, 2025 14:40

pawamoy added 2 commits December 2, 2025 15:42

reapply yore fix -b2

3baa382

access members from griffe in tests

b301b91

pawamoy reviewed Dec 2, 2025

View reviewed changes

casing and order in pyproject.toml

d8b049c

Uh oh!

change: Reorganize as griffe and griffelib packages with uv workspaces #434

Are you sure you want to change the base?

change: Reorganize as griffe and griffelib packages with uv workspaces #434

Uh oh!

Conversation

johnslavik commented Nov 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

johnslavik commented Nov 30, 2025

Uh oh!

johnslavik commented Nov 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI commented Nov 30, 2025

Uh oh!

johnslavik commented Nov 30, 2025

Uh oh!

Copilot AI commented Nov 30, 2025

Uh oh!

johnslavik commented Dec 1, 2025

Uh oh!

Copilot AI commented Dec 1, 2025

Uh oh!

pawamoy Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

change: Reorganize as `griffe` and `griffelib` packages with uv workspaces #434

change: Reorganize as `griffe` and `griffelib` packages with uv workspaces #434

johnslavik commented Nov 30, 2025 •

edited

Loading

johnslavik commented Nov 30, 2025 •

edited

Loading

pawamoy Dec 2, 2025 •

edited

Loading