griffecli 2.2.0__tar.gz → 2.3.1__tar.gz

{griffecli-2.2.0 → griffecli-2.3.1}/.gitignore

@@ -1,6 +1,10 @@
 # editors
 .idea/
 .vscode/
+.zed
+
+# environment
+.env
 
 # python
 *.egg-info/
@@ -13,6 +17,7 @@ dist/
 # tools
 .coverage*
 /.pdm-build/
+/docs/griffe.json
 /htmlcov/
 /site/
 uv.lock

{griffecli-2.2.0 → griffecli-2.3.1}/CHANGELOG.md

@@ -5,6 +5,52 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 <!-- insertion marker -->
+## [2.3.1](https://github.com/mkdocstrings/griffe/releases/tag/2.3.1) - 2026-10-06
+
+<small>[Compare with 2.3.0](https://github.com/mkdocstrings/griffe/compare/2.3.0...2.3.1)</small>
+
+### Build
+
+- Drop support for Python 3.10 ([686993d](https://github.com/mkdocstrings/griffe/commit/686993d4970d9fabbbd33334f88f48e1daed0565) by Timothée Mazzucotelli).
+
+### Bug Fixes
+
+- Exit gracefully when checking API and no tags are found ([7c898a9](https://github.com/mkdocstrings/griffe/commit/7c898a9685c8ac29e1a4fd7767e85bf830b75a58) by Timothée Mazzucotelli).
+
+## [2.3.0](https://github.com/mkdocstrings/griffe/releases/tag/2.3.0) - 2026-09-04
+
+<small>[Compare with 2.2.0](https://github.com/mkdocstrings/griffe/compare/2.2.0...2.3.0)</small>
+
+### Features
+
+- Add option to give precedence to docstrings in stubs vs. source ([09a2a13](https://github.com/mkdocstrings/griffe/commit/09a2a1323d1b4d022a4ce76a9f2839287b9c100e) by Timothée Mazzucotelli). [Issue-447](https://github.com/mkdocstrings/griffe/issues/447), [PR-481](https://github.com/mkdocstrings/griffe/pull/481)
+
+### Bug Fixes
+
+- Preserve nested tuple parentheses ([e095a7c](https://github.com/mkdocstrings/griffe/commit/e095a7cd4c239abd961f7899d7ddb17ea27caead) by Alperen). [PR-487](https://github.com/mkdocstrings/griffe/pull/487), Co-authored-by: Timothée Mazzucotelli <dev@pawamoy.fr>
+- Preserve nested f-string format specs ([38921b7](https://github.com/mkdocstrings/griffe/commit/38921b70e3dbba9a493aa5117f11a3a7883634cf) by Alperen). [PR-486](https://github.com/mkdocstrings/griffe/pull/486)
+- Disable all docstring warnings when passing `warnings=False` ([5cb0ae2](https://github.com/mkdocstrings/griffe/commit/5cb0ae2f00748288c4009c1d4b6ee19f6aca6b76) by Timothée Mazzucotelli).
+
+### Performance Improvements
+
+- Reuse computed parent in `is_imported` ([092ac31](https://github.com/mkdocstrings/griffe/commit/092ac3162e1477a4b62eb875365996998adbd77d) by Timothée Mazzucotelli).
+- Only build debug messages at debug level ([8f05a4a](https://github.com/mkdocstrings/griffe/commit/8f05a4ae5587d685bea1b0c98294a047b56c8df0) by Timothée Mazzucotelli).
+- Avoid creating new sets when handling labels ([06cd02e](https://github.com/mkdocstrings/griffe/commit/06cd02e63c240286d11450887cc01b0ef76d8908) by Timothée Mazzucotelli).
+- Maintain map of AST node type to visitor function ([e21851e](https://github.com/mkdocstrings/griffe/commit/e21851e732782823006223a7f5f8111b4200a257) by Timothée Mazzucotelli).
+- Avoid cyclic refs in ASTs to allow garbage-collecting them ([b968de0](https://github.com/mkdocstrings/griffe/commit/b968de091afc1a4fd241f457538433ce3ada7520) by Timothée Mazzucotelli).
+- Cache per-module path-related properties during serialization ([8bd6cc4](https://github.com/mkdocstrings/griffe/commit/8bd6cc4b34e96fc8235271cfa93a1a6a77091707) by Timothée Mazzucotelli).
+- Do not fire load events when no extension has hooked them ([0e2ae7c](https://github.com/mkdocstrings/griffe/commit/0e2ae7c8cd1563d6dcca7a6c37fb8f2ec072cb24) by Timothée Mazzucotelli).
+- Compute costly message lazily in alias resolution errors ([1e391b8](https://github.com/mkdocstrings/griffe/commit/1e391b8239747bb62908819e55468a961ffbaa99) by Timothée Mazzucotelli).
+- Avoid iterating many times over function parameters when merging stubs ([03cae74](https://github.com/mkdocstrings/griffe/commit/03cae743e02c56af7375ffbfa70d6acf02e5491d) by Timothée Mazzucotelli).
+- Avoid iterating many times over function parameters when diff'ing ([d3cf2c4](https://github.com/mkdocstrings/griffe/commit/d3cf2c41bb5f734e57b612b42d178e87af605ae8) by Timothée Mazzucotelli).
+- Improve efficiency of AST parameter extraction ([1e37cd4](https://github.com/mkdocstrings/griffe/commit/1e37cd488d6adf55065b3ce4e7932faf1ff7d186) by Timothée Mazzucotelli).
+- Cache serializable expression fields ([f9e48c1](https://github.com/mkdocstrings/griffe/commit/f9e48c16ebaeb719d5768cb921637aebe377a639) by Timothée Mazzucotelli).
+- Use maps to make JSON encoder faster ([b7de96f](https://github.com/mkdocstrings/griffe/commit/b7de96fb516218ae3bf6a8e6d014a223df67f4a3) by Timothée Mazzucotelli).
+- Avoid recomputing inherited members when diff'ing ([a29e028](https://github.com/mkdocstrings/griffe/commit/a29e028ff034752ff747dda17f3f875f22c2a192) by Timothée Mazzucotelli).
+- Make Google, Numpy and Sphinx docstring parsers faster ([7f39373](https://github.com/mkdocstrings/griffe/commit/7f39373f8da779fb104dd2b6c11a02d95da628c4) by Timothée Mazzucotelli).
+- Pre-compile patterns for docstring style detection ([ad58ad5](https://github.com/mkdocstrings/griffe/commit/ad58ad5b86390a8a02311189315dd4f59e0300a4) by Timothée Mazzucotelli).
+- LRU-cache parsing of type annotations in docstrings ([1671e59](https://github.com/mkdocstrings/griffe/commit/1671e59fb675e9b45338956ce8aa5f5e56692690) by Timothée Mazzucotelli).
+
 ## [2.2.0](https://github.com/mkdocstrings/griffe/releases/tag/2.2.0) - 2026-08-16
 
 <small>[Compare with 2.1.0](https://github.com/mkdocstrings/griffe/compare/2.1.0...2.2.0)</small>

{griffecli-2.2.0 → griffecli-2.3.1}/LICENSE

@@ -1,6 +1,6 @@
 ISC License
 
-Copyright (c) 2021, Timothée Mazzucotelli
+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

{griffecli-2.2.0 → griffecli-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: griffecli
-Version: 2.2.0
+Version: 2.3.1
 Summary: 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.
 Author-email: Timothée Mazzucotelli <dev@pawamoy.fr>
 License-Expression: ISC
@@ -10,7 +10,6 @@ Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
@@ -22,4 +21,4 @@ Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: colorama>=0.4
-Requires-Dist: griffelib==2.2.0
+Requires-Dist: griffelib==2.3.1

{griffecli-2.2.0 → griffecli-2.3.1}/README.md

@@ -1,7 +1,7 @@
 # Griffe
 
 [![ci](https://github.com/mkdocstrings/griffe/workflows/ci/badge.svg)](https://github.com/mkdocstrings/griffe/actions?query=workflow%3Aci)
-[![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)](https://mkdocstrings.github.io/griffe/)
+[![documentation](https://img.shields.io/badge/docs-zensical-FF9100.svg?style=flat)](https://mkdocstrings.github.io/griffe/)
 [![pypi version](https://img.shields.io/pypi/v/griffe.svg)](https://pypi.org/project/griffe/)
 [![gitter](https://img.shields.io/badge/matrix-chat-4db798.svg?style=flat)](https://app.gitter.im/#/room/#mkdocstrings_griffe:gitter.im)
 [![radicle](https://img.shields.io/badge/rad-clone-6666FF.svg?style=flat)](https://app.radicle.at/nodes/seed.radicle.at/rad:z4M5XTPDD4Wh1sm8iPCenF85J3z8Z)

{griffecli-2.2.0 → griffecli-2.3.1}/pyproject.toml

@@ -19,8 +19,6 @@ classifiers = [
     "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.

{griffecli-2.2.0 → griffecli-2.3.1}/src/griffecli/_internal/cli.py

@@ -34,7 +34,7 @@ import logging
 import os
 import re
 import sys
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from pathlib import Path
 from typing import IO, TYPE_CHECKING, Any
 
@@ -91,6 +91,7 @@ def _load_packages(
     force_inspection: bool = False,
     store_source: bool = True,
     find_stubs_package: bool = False,
+    prefer_stubs_docs: bool = False,
 ) -> GriffeLoader:
     from griffe._internal.loader import GriffeLoader  # noqa: PLC0415
     from griffe._internal.logger import logger  # noqa: PLC0415
@@ -104,6 +105,7 @@ def _load_packages(
         allow_inspection=allow_inspection,
         force_inspection=force_inspection,
         store_source=store_source,
+        prefer_stubs_docs=prefer_stubs_docs,
     )
 
     # Load each package.
@@ -192,6 +194,14 @@ def get_parser() -> argparse.ArgumentParser:
             default=False,
             help="Whether to look for stubs-only packages and merge them with concrete ones.",
         )
+        loading_options.add_argument(
+            "-P",
+            "--prefer-stubs-docstrings",
+            dest="prefer_stubs_docs",
+            action="store_true",
+            default=False,
+            help="Whether to prefer docstrings from stubs over those from sources.",
+        )
         loading_options.add_argument(
             "-e",
             "--extensions",
@@ -358,6 +368,7 @@ def dump(
     resolve_external: bool | None = None,
     search_paths: Sequence[str | Path] | None = None,
     find_stubs_package: bool = False,
+    prefer_stubs_docs: bool = False,
     append_sys_path: bool = False,
     allow_inspection: bool = True,
     force_inspection: bool = False,
@@ -380,6 +391,7 @@ def dump(
         find_stubs_package: Whether to search for stubs-only packages.
             If both the package and its stubs are found, they'll be merged together.
             If only the stubs are found, they'll be used as the package itself.
+        prefer_stubs_docs: Whether to give precedence to docstrings from stubs over those from sources.
         append_sys_path: Whether to append the contents of `sys.path` to the search paths.
         allow_inspection: Whether to allow inspecting modules when visiting them is not possible.
         force_inspection: Whether to force using dynamic analysis when loading data.
@@ -422,11 +434,12 @@ def dump(
         force_inspection=force_inspection,
         store_source=False,
         find_stubs_package=find_stubs_package,
+        prefer_stubs_docs=prefer_stubs_docs,
     )
     data_packages = loader.modules_collection.members
 
     # Serialize and dump packages.
-    started = datetime.now(tz=timezone.utc)
+    started = datetime.now(tz=UTC)
     if per_package_output:
         for package_name, data in data_packages.items():
             serialized = data.as_json(indent=2, full=full, sort_keys=True)
@@ -434,7 +447,7 @@ def dump(
     else:
         serialized = json.dumps(data_packages, cls=JSONEncoder, indent=2, full=full, sort_keys=True)
         _print_data(serialized, output)
-    elapsed = datetime.now(tz=timezone.utc) - started
+    elapsed = datetime.now(tz=UTC) - started
 
     if stats:
         loader_stats = loader.stats()
@@ -454,6 +467,7 @@ def check(
     search_paths: Sequence[str | Path] | None = None,
     append_sys_path: bool = False,
     find_stubs_package: bool = False,
+    prefer_stubs_docs: bool = False,
     allow_inspection: bool = True,
     force_inspection: bool = False,
     verbose: bool = False,
@@ -470,6 +484,8 @@ def check(
         extensions: The extensions to use.
         search_paths: The paths to search into.
         append_sys_path: Whether to append the contents of `sys.path` to the search paths.
+        find_stubs_package: Whether to search for stubs-only packages.
+        prefer_stubs_docs: Whether to give precedence to docstrings from stubs over those from sources.
         allow_inspection: Whether to allow inspecting modules when visiting them is not possible.
         force_inspection: Whether to force using dynamic analysis when loading data.
         verbose: Use a verbose output.
@@ -509,6 +525,7 @@ def check(
             allow_inspection=allow_inspection,
             force_inspection=force_inspection,
             find_stubs_package=find_stubs_package,
+            prefer_stubs_docs=prefer_stubs_docs,
             resolve_aliases=True,
             resolve_external=None,
         )
@@ -530,6 +547,7 @@ def check(
             allow_inspection=allow_inspection,
             force_inspection=force_inspection,
             find_stubs_package=find_stubs_package,
+            prefer_stubs_docs=prefer_stubs_docs,
             resolve_aliases=True,
             resolve_external=None,
         )
@@ -543,6 +561,10 @@ def check(
             print(f"griffe: error: {error}", file=sys.stderr)
             return 2
 
+        if not against:
+            print("griffe: info: 'against' ref not specified and no tags found", file=sys.stderr)
+            return 0
+
         # Load old and new version of the package.
         old_package = load_git(
             against_path,
@@ -553,6 +575,7 @@ def check(
             allow_inspection=allow_inspection,
             force_inspection=force_inspection,
             find_stubs_package=find_stubs_package,
+            prefer_stubs_docs=prefer_stubs_docs,
             resolve_aliases=True,
             resolve_external=None,
         )
@@ -567,6 +590,7 @@ def check(
                 allow_inspection=allow_inspection,
                 force_inspection=force_inspection,
                 find_stubs_package=find_stubs_package,
+                prefer_stubs_docs=prefer_stubs_docs,
                 resolve_aliases=True,
                 resolve_external=None,
             )
@@ -579,6 +603,7 @@ def check(
                 allow_inspection=allow_inspection,
                 force_inspection=force_inspection,
                 find_stubs_package=find_stubs_package,
+                prefer_stubs_docs=prefer_stubs_docs,
                 resolve_aliases=True,
                 resolve_external=None,
             )

{griffecli-2.2.0 → griffecli-2.3.1}/tests/test_cli.py

@@ -18,13 +18,18 @@
 
 from __future__ import annotations
 
+import json
 import sys
+from typing import TYPE_CHECKING
 
 import pytest
 
 from griffe._internal import debug
 from griffecli._internal import cli
 
+if TYPE_CHECKING:
+    from pathlib import Path
+
 
 def test_main() -> None:
     """Basic CLI test."""
@@ -34,6 +39,26 @@ def test_main() -> None:
         assert cli.main(["dump", "griffe", "-s", "src", "-o/dev/null"]) == 0
 
 
+@pytest.mark.parametrize("flag", ["-P", "--prefer-stubs-docstrings"])
+def test_prefer_stubs_docstrings(tmp_path: Path, flag: str) -> None:
+    """Prefer docstrings from stubs when requested.
+
+    Parameters:
+        tmp_path: Pytest fixture providing a temporary directory.
+        flag: Short or long spelling of the CLI flag.
+    """
+    package_path = tmp_path / "package"
+    package_path.mkdir()
+    package_path.joinpath("__init__.py").write_text('"""Source."""', encoding="utf8")
+    package_path.joinpath("__init__.pyi").write_text('"""Stubs."""', encoding="utf8")
+    output_path = tmp_path / "output.json"
+
+    assert cli.main(["dump", str(package_path), flag, "-o", str(output_path)]) == 0
+
+    output = json.loads(output_path.read_text(encoding="utf8"))
+    assert output["package"]["docstring"]["value"] == "Stubs."
+
+
 def test_show_help(capsys: pytest.CaptureFixture) -> None:
     """Show help.