griffecli 2.1.0__tar.gz → 2.3.0__tar.gz

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

@@ -5,6 +5,58 @@ 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>
+
+### Features
+
+- Support `await` expressions ([6b3caab](https://github.com/mkdocstrings/griffe/commit/6b3caab7ce4fdcb1c9386937dad17510d35a3321) by Vincent Gao). [PR-479](https://github.com/mkdocstrings/griffe/pull/479)
+- Support unpacking in dict comprehensions ([2d39391](https://github.com/mkdocstrings/griffe/commit/2d39391cb135febadf339bdea91c1113b74da145) by mushitoriami). [PR-475](https://github.com/mkdocstrings/griffe/pull/475)
+
+### Bug Fixes
+
+- Forward `warn_missing_types` to Sphinx return section reader ([a15e782](https://github.com/mkdocstrings/griffe/commit/a15e782ed0793e06d22105beb016c10cfe0ed4b0) by Timothée Mazzucotelli). [Issue-mkdocstrings-python-337](https://github.com/mkdocstrings/python/issues/337)
+- Make stringified expressions valid and faithful Python ([eb85f0d](https://github.com/mkdocstrings/griffe/commit/eb85f0dd8bf49f4a2400bf03face646d8f533a7c) by Vincent Gao). [PR-478](https://github.com/mkdocstrings/griffe/pull/478)
+- Empty tuples can never be implicit ([82e728d](https://github.com/mkdocstrings/griffe/commit/82e728dc758f9635d2e500c13caa795b48e36d8a) by Vincent Gao). [PR-474](https://github.com/mkdocstrings/griffe/pull/474), Co-authored-by: Timothée Mazzucotelli <dev@pawamoy.fr>
+- Render f-strings and t-strings with correct quote delimiters ([90e28d4](https://github.com/mkdocstrings/griffe/commit/90e28d45ffc998434895c0f73af608cb12f0d6dd) by Bartosz Sławecki). [Issue-444](https://github.com/mkdocstrings/griffe/issues/444), [PR-455](https://github.com/mkdocstrings/griffe/pull/455)
+- Detect basic admonitions 'example', 'note' and 'warning' in Google/Numpy docstrings when inferring style ([f30306f](https://github.com/mkdocstrings/griffe/commit/f30306fa703741f976fc49576ddf95cf29ba998b) by Timothée Mazzucotelli).
+- Render dict `**`-unpacking as `**value` instead of `None: value` ([74ddbbf](https://github.com/mkdocstrings/griffe/commit/74ddbbf22f49e1fb789ac754e3fff41a0ac2f152) by Vincent Gao). [PR-467](https://github.com/mkdocstrings/griffe/pull/467)
+
 ## [2.1.0](https://github.com/mkdocstrings/griffe/releases/tag/2.1.0) - 2026-06-19
 
 <small>[Compare with 2.0.2](https://github.com/mkdocstrings/griffe/compare/2.0.2...2.1.0)</small>

{griffecli-2.1.0 → griffecli-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: griffecli
-Version: 2.1.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.1.0
+Requires-Dist: griffelib==2.3.0

{griffecli-2.1.0 → griffecli-2.3.0}/README.md

@@ -143,7 +143,7 @@ See the [Loading chapter](https://mkdocstrings.github.io/griffe/guide/users/load
 <a href="https://github.com/BenHammersley"><img alt="BenHammersley" src="https://avatars.githubusercontent.com/u/99436?u=4499a7b507541045222ee28ae122dbe3c8d08ab5&v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/trevorWieland"><img alt="trevorWieland" src="https://avatars.githubusercontent.com/u/28811461?u=74cc0e3756c1d4e3d66b5c396e1d131ea8a10472&v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/MarcoGorelli"><img alt="MarcoGorelli" src="https://avatars.githubusercontent.com/u/33491632?u=7de3a749cac76a60baca9777baf71d043a4f884d&v=4" style="height: 32px; border-radius: 100%;"></a>
-<a href="https://github.com/analog-cbarber"><img alt="analog-cbarber" src="https://avatars.githubusercontent.com/u/7408243?u=642fc2bdcc9904089c62fe5aec4e03ace32da67d&v=4" style="height: 32px; border-radius: 100%;"></a>
+<a href="https://github.com/analog-cbarber"><img alt="analog-cbarber" src="https://avatars.githubusercontent.com/u/7408243?u=fe0e7bf2882d1c9c901a341c2502e1518466527a&v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/OdinManiac"><img alt="OdinManiac" src="https://avatars.githubusercontent.com/u/22727172?u=36ab20970f7f52ae8e7eb67b7fcf491fee01ac22&v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/rstudio-sponsorship"><img alt="rstudio-sponsorship" src="https://avatars.githubusercontent.com/u/58949051?u=0c471515dd18111be30dfb7669ed5e778970959b&v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/schlich"><img alt="schlich" src="https://avatars.githubusercontent.com/u/21191435?u=6f1240adb68f21614d809ae52d66509f46b1e877&v=4" style="height: 32px; border-radius: 100%;"></a>
@@ -155,17 +155,15 @@ See the [Loading chapter](https://mkdocstrings.github.io/griffe/guide/users/load
 <a href="https://github.com/activeloopai"><img alt="activeloopai" src="https://avatars.githubusercontent.com/u/34816118?v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/roboflow"><img alt="roboflow" src="https://avatars.githubusercontent.com/u/53104118?v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/cmclaughlin"><img alt="cmclaughlin" src="https://avatars.githubusercontent.com/u/1061109?u=ddf6eec0edd2d11c980f8c3aa96e3d044d4e0468&v=4" style="height: 32px; border-radius: 100%;"></a>
-<a href="https://github.com/blaisep"><img alt="blaisep" src="https://avatars.githubusercontent.com/u/254456?u=97d584b7c0a6faf583aa59975df4f993f671d121&v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/RapidataAI"><img alt="RapidataAI" src="https://avatars.githubusercontent.com/u/104209891?v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/rodolphebarbanneau"><img alt="rodolphebarbanneau" src="https://avatars.githubusercontent.com/u/46493454?u=6c405452a40c231cdf0b68e97544e07ee956a733&v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/theSymbolSyndicate"><img alt="theSymbolSyndicate" src="https://avatars.githubusercontent.com/u/111542255?v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/blakeNaccarato"><img alt="blakeNaccarato" src="https://avatars.githubusercontent.com/u/20692450?u=bb919218be30cfa994514f4cf39bb2f7cf952df4&v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/ChargeStorm"><img alt="ChargeStorm" src="https://avatars.githubusercontent.com/u/26000165?v=4" style="height: 32px; border-radius: 100%;"></a>
-<a href="https://github.com/Alphadelta14"><img alt="Alphadelta14" src="https://avatars.githubusercontent.com/u/480845?v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/Cusp-AI"><img alt="Cusp-AI" src="https://avatars.githubusercontent.com/u/178170649?v=4" style="height: 32px; border-radius: 100%;"></a>
 </p></div>
 
 
-*And 7 more private sponsor(s).*
+*And 4 more private sponsor(s).*
 
 <!-- sponsors-end -->

griffecli-2.3.0/src/griffecli/__init__.py

@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: ISC
+
+# 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
+# copyright notice and this permission notice appear in all copies.
+
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+# This top-level module imports all public names from the CLI package,
+# and exposes them as public objects.
+
+"""Griffe CLI package.
+
+The CLI (Command Line Interface) for the griffe library.
+This package provides command-line tools for interacting with griffe.
+
+## CLI entrypoints
+
+- [`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.
+"""
+
+from __future__ import annotations
+
+from griffecli._internal.cli import DEFAULT_LOG_LEVEL, check, dump, get_parser, main
+
+__all__ = [
+    "DEFAULT_LOG_LEVEL",
+    "check",
+    "dump",
+    "get_parser",
+    "main",
+]

griffecli-2.3.0/src/griffecli/__main__.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: ISC
+
+# 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
+# copyright notice and this permission notice appear in all copies.
+
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+# Entry-point module, in case you use `python -m griffecli`.
+#
+# Why does this file exist, and why `__main__`? For more info, read:
+#
+# - https://www.python.org/dev/peps/pep-0338/
+# - https://docs.python.org/3/using/cmdline.html#cmdoption-m
+
+import sys
+
+from griffecli._internal.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

griffecli-2.3.0/src/griffecli/_internal/__init__.py

@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: ISC
+
+# 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
+# copyright notice and this permission notice appear in all copies.
+
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+# Internal modules for the griffecli package.

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

@@ -1,3 +1,19 @@
+# SPDX-License-Identifier: ISC
+
+# 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
+# copyright notice and this permission notice appear in all copies.
+
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
 # This module contains all CLI-related things.
 # Why does this file exist, and why not put this in `__main__`?
 #
@@ -75,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
@@ -88,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.
@@ -176,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",
@@ -342,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,
@@ -364,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.
@@ -406,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
 
@@ -438,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,
@@ -454,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.
@@ -493,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,
         )
@@ -514,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,
         )
@@ -537,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,
         )
@@ -551,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,
             )
@@ -563,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.3.0/tests/__init__.py

@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: ISC
+
+# 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
+# copyright notice and this permission notice appear in all copies.
+
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+"""Tests suite for `griffecli`."""

griffecli-2.3.0/tests/test_cli.py

@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: ISC
+
+# 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
+# copyright notice and this permission notice appear in all copies.
+
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+"""Tests for the CLI."""
+
+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."""
+    if sys.platform == "win32":
+        assert cli.main(["dump", "griffe", "-s", "src", "-oNUL"]) == 0
+    else:
+        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.
+
+    Parameters:
+        capsys: Pytest fixture to capture output.
+    """
+    with pytest.raises(SystemExit):
+        cli.main(["-h"])
+    captured = capsys.readouterr()
+    assert "griffe" in captured.out
+
+
+def test_show_version(capsys: pytest.CaptureFixture) -> None:
+    """Show version.
+
+    Parameters:
+        capsys: Pytest fixture to capture output.
+    """
+    with pytest.raises(SystemExit):
+        cli.main(["-V"])
+    captured = capsys.readouterr()
+    assert debug._get_version() in captured.out
+
+
+def test_show_debug_info(capsys: pytest.CaptureFixture) -> None:
+    """Show debug information.
+
+    Parameters:
+        capsys: Pytest fixture to capture output.
+    """
+    with pytest.raises(SystemExit):
+        cli.main(["--debug-info"])
+    captured = capsys.readouterr().out.lower()
+    assert "python" in captured
+    assert "system" in captured
+    assert "environment" in captured
+    assert "packages" in captured

griffecli-2.1.0/src/griffecli/__init__.py

@@ -1,27 +0,0 @@
-# This top-level module imports all public names from the CLI package,
-# and exposes them as public objects.
-
-"""Griffe CLI package.
-
-The CLI (Command Line Interface) for the griffe library.
-This package provides command-line tools for interacting with griffe.
-
-## CLI entrypoints
-
-- [`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.
-"""
-
-from __future__ import annotations
-
-from griffecli._internal.cli import DEFAULT_LOG_LEVEL, check, dump, get_parser, main
-
-__all__ = [
-    "DEFAULT_LOG_LEVEL",
-    "check",
-    "dump",
-    "get_parser",
-    "main",
-]

griffecli-2.1.0/src/griffecli/__main__.py

@@ -1,13 +0,0 @@
-# Entry-point module, in case you use `python -m griffecli`.
-#
-# Why does this file exist, and why `__main__`? For more info, read:
-#
-# - https://www.python.org/dev/peps/pep-0338/
-# - https://docs.python.org/3/using/cmdline.html#cmdoption-m
-
-import sys
-
-from griffecli._internal.cli import main
-
-if __name__ == "__main__":
-    sys.exit(main(sys.argv[1:]))

griffecli-2.1.0/src/griffecli/_internal/__init__.py

@@ -1 +0,0 @@
-# Internal modules for the griffecli package.

griffecli-2.1.0/tests/__init__.py

@@ -1 +0,0 @@
-"""Tests suite for `griffecli`."""

griffecli-2.1.0/tests/test_cli.py

@@ -1,57 +0,0 @@
-"""Tests for the CLI."""
-
-from __future__ import annotations
-
-import sys
-
-import pytest
-
-from griffe._internal import debug
-from griffecli._internal import cli
-
-
-def test_main() -> None:
-    """Basic CLI test."""
-    if sys.platform == "win32":
-        assert cli.main(["dump", "griffe", "-s", "src", "-oNUL"]) == 0
-    else:
-        assert cli.main(["dump", "griffe", "-s", "src", "-o/dev/null"]) == 0
-
-
-def test_show_help(capsys: pytest.CaptureFixture) -> None:
-    """Show help.
-
-    Parameters:
-        capsys: Pytest fixture to capture output.
-    """
-    with pytest.raises(SystemExit):
-        cli.main(["-h"])
-    captured = capsys.readouterr()
-    assert "griffe" in captured.out
-
-
-def test_show_version(capsys: pytest.CaptureFixture) -> None:
-    """Show version.
-
-    Parameters:
-        capsys: Pytest fixture to capture output.
-    """
-    with pytest.raises(SystemExit):
-        cli.main(["-V"])
-    captured = capsys.readouterr()
-    assert debug._get_version() in captured.out
-
-
-def test_show_debug_info(capsys: pytest.CaptureFixture) -> None:
-    """Show debug information.
-
-    Parameters:
-        capsys: Pytest fixture to capture output.
-    """
-    with pytest.raises(SystemExit):
-        cli.main(["--debug-info"])
-    captured = capsys.readouterr().out.lower()
-    assert "python" in captured
-    assert "system" in captured
-    assert "environment" in captured
-    assert "packages" in captured