griffecli 2.2.0__tar.gz → 2.3.0__tar.gz

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

@@ -5,6 +5,40 @@ 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.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.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: griffecli
-Version: 2.2.0
+Version: 2.3.0
 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
@@ -22,4 +22,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.0

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

@@ -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,6 +434,7 @@ 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
 
@@ -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,
         )
@@ -553,6 +571,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 +586,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 +599,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.0}/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.