change: Split `griffe` to `griffe` and `griffelib` packages

[johnslavik]

We'd like to make this repository a monorepo of 2 packages (and at the same time 2 separate PyPI projects) managed with uv workspaces:

• griffelib, containing all library logic
• griffe, a thin package that can be run as script which wraps griffelib with a CLI

This originates from discussions in #406.
However, when working through this, I realized that it's a huge enough migration that quite a few things could be worth being explicitly mentioned and considered.

Our goals

• All variants of pip install griffe install a CLI application and the library. uvx griffe, pipx run griffe or pip-run griffe naturally run the griffe CLI.
• colorama is dropped from griffelib dependencies and is instead a griffe dependency, as in feature: could you make colorama an optional dependenncy #406.
• Public API imports from griffe, such as from griffe import ... imports, still work, and griffe/__init__.py is just a shim to all public members of the griffelib library.

Things to consider

• Should we make a major release after this migration?
• I'm not planning to add shims to new griffe/_internal modules that would re-export symbols from griffelib/_internal -- they're called _internal for a reason, and btw @pawamoy that's awesome we have it this way. Just noting here that no shims will break a few packages -- but few enough to just go to their repos and kindly inform them that they'll need to migrate to griffelib if they want to maintain their unstable imports. Perhaps they don't even have to use internal imports? I haven't inspected that deeply.
• Needs decision: Should we add a warning to all from griffe ... import library imports, and recommend to import library things from griffelib instead? I'd say no, because maintaining a from griffe import * is low-cost, so I wouldn't care but perhaps you'd like to drop support for that. Do most people use griffe as an app, not a library? @pawamoy

Migration plan

• Introduce uv workspaces
• Introduce uv dynamic versioning for syncing griffe and griffelib releases to be exact same version. As discussed privately, we'd like the two packages to be released with 1:1 versioning, even if one of them doesn't change, as we find a 1:1 relationship easier to reason about
• Migrate tests and CI to new monorepo layout
• Migrate documentation
  • Present griffelib and griffe separately in our documentation
  • Migrate griffe.* crossrefs to griffelib.* in the docstrings -- thankfully we have this nice tool called griffe that will help validate that we did it correctly
  • Important: make sure the old crossref links redirect to the new crossref targets
• Release a new version griffelib and griffe

Not sure yet how to partition that into PRs. I'll come up with whatever makes sense.

[pawamoy]

Thanks for laying out the plan 🚀

Regarding imports from internal API: obviously this API is internal and not public, so I expect users to not import from it. If they do, that's unsupported. Any change of symbol location under _internal is considered non-breaking. Don't worry, I've checked already when moving from _griffe to griffe._internal, and found very few imports on GitHub, and reported those. We can safely move everything under griffelib._internal.

Regarding importing from griffe vs griffelib, I want us to support both. We shouldn't warn if users import from griffe.

[johnslavik]

Awesome, thanks! How about the next release? If we make a major, I'll drop some deprecated things with yore. Won't have to be bothered by stacklevels in warnings :P skip_file_prefixes= is 3.12+, so we'd need to pass stacklevel=3 to griffelib.__getattr__.

[pawamoy]

No need for a major bump yet. What warnings/stacklevels are you talking about? Oh, in griffelib, right. Yeah I was going to suggest we drop deprecated imports in griffelib, but we'd have to sync in griffe too. Then sure why not a major bump.

[johnslavik]

As part of this issue, we've changed the build system from pdm to hatch for the sole purpose of using uv dynamic versioning with uv workspaces; see #430.

[pawamoy]

"uv-dynamic-versioning"

[tool.hatch.metadata.hooks.uv-dynamic-versioning]
dependencies = ["foo=={{ version }}"]

So it's a Hatch plugin. Quite a confusing project name. I guess it's capitalizing on uv's popularity?