griffe 2.0.2__tar.gz → 2.2.0__tar.gz

{griffe-2.0.2 → griffe-2.2.0}/CHANGELOG.md

@@ -5,6 +5,41 @@ 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.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>
+
+### Build
+
+- Add tests to source distributions for `griffecli` and `griffelib` packages. [Issue-452](https://github.com/mkdocstrings/griffe/issues/452)
+
+### Features
+
+- Add logging format for Azure Devops ([82526e4](https://github.com/mkdocstrings/griffe/commit/82526e487946f838c2521e531ef8716dd12d4eea) by Carsten Igel). [PR-457](https://github.com/mkdocstrings/griffe/pull/457), Co-authored-by: Timothée Mazzucotelli <dev@pawamoy.fr>
+
+### Bug Fixes
+
+- Rename tests module to avoid exclusion by packagers ([5b3e392](https://github.com/mkdocstrings/griffe/commit/5b3e392006da98d5f23ba0e808393038be6014d8) by Timothée Mazzucotelli). [Issue-461](https://github.com/mkdocstrings/griffe/issues/461)
+- Don't try merging overload annotations into non-function objects ([1b6b053](https://github.com/mkdocstrings/griffe/commit/1b6b053dc4cfdc4381a9dc4b0676b7946e55951e) by Timothée Mazzucotelli). [Issue-451](https://github.com/mkdocstrings/griffe/discussions/451)
+
 ## [2.0.2](https://github.com/mkdocstrings/griffe/releases/tag/2.0.2) - 2026-03-27
 
 <small>[Compare with 2.0.1](https://github.com/mkdocstrings/griffe/compare/2.0.1...2.0.2)</small>

{griffe-2.0.2 → griffe-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: griffe
-Version: 2.0.2
+Version: 2.2.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.
 Project-URL: Homepage, https://mkdocstrings.github.io/griffe
 Project-URL: Documentation, https://mkdocstrings.github.io/griffe
@@ -30,10 +30,10 @@ Classifier: Topic :: Software Development :: Documentation
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
-Requires-Dist: griffecli==2.0.2
-Requires-Dist: griffelib==2.0.2
+Requires-Dist: griffecli==2.2.0
+Requires-Dist: griffelib==2.2.0
 Provides-Extra: pypi
-Requires-Dist: griffelib[pypi]==2.0.2; extra == 'pypi'
+Requires-Dist: griffelib[pypi]==2.2.0; extra == 'pypi'
 Description-Content-Type: text/markdown
 
 # Griffe
@@ -181,7 +181,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>
@@ -193,17 +193,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 -->

{griffe-2.0.2 → griffe-2.2.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 -->

{griffe-2.0.2 → griffe-2.2.0}/config/coverage.ini

@@ -4,7 +4,8 @@ parallel = true
 source =
   packages/griffelib/src/griffe
   packages/griffecli/src/griffecli
-  tests/
+  packages/griffecli/tests/
+  packages/griffelib/tests/
 
 [coverage:paths]
 equivalent =
@@ -17,8 +18,8 @@ precision = 2
 omit =
   src/*/__init__.py
   src/*/__main__.py
-  tests/__init__.py
-  tests/tmp/*
+  packages/*/tests/__init__.py
+  packages/*/tests/tmp/*
 exclude_lines =
   pragma: no cover
   if TYPE_CHECKING

{griffe-2.0.2 → griffe-2.2.0}/config/pytest.ini

@@ -1,11 +1,10 @@
 [pytest]
-python_files =
-  test_*.py
 addopts =
   --cov
   --cov-config config/coverage.ini
+  --import-mode=importlib
 testpaths =
-  tests
+  packages/*/tests
 
 # action:message_regex:warning_class:module_regex:line
 filterwarnings =

{griffe-2.0.2 → griffe-2.2.0}/config/ruff.toml

@@ -4,7 +4,7 @@ output-format = "concise"
 
 [lint]
 exclude = [
-    "tests/fixtures/*.py",
+    "packages/*/tests/fixtures/*.py",
 ]
 select = ["ALL"]
 ignore = [
@@ -65,12 +65,14 @@ logger-objects = ["griffe.logger"]
     "INP001",  # File is part of an implicit namespace package
     "T201",  # Print statement
 ]
-"tests/test_git.py" = [
+"packages/griffelib/tests/test_git.py" = [
     "S603",  # `subprocess` call: check for execution of untrusted input
     "S607",  # Starting a process with a partial executable path
 ]
-"tests/**.py" = [
+"packages/*/tests/**.py" = [
     "ARG005",  # Unused lambda argument
+    "D100",  # Missing module docstring
+    "D104",  # Missing package docstring
     "FBT001",  # Boolean positional arg in function definition
     "PLC1901",  # a == "" can be simplified to not a
     "PLR2004",  # Magic value used in comparison
@@ -91,7 +93,7 @@ convention = "google"
 
 [format]
 exclude = [
-    "tests/fixtures/*.py",
+    "packages/*/tests/fixtures/*.py",
 ]
 docstring-code-format = true
 docstring-code-line-length = 80

griffe-2.2.0/config/ty.toml

@@ -0,0 +1,9 @@
+[src]
+exclude = ["packages/*/tests/fixtures"]
+
+[terminal]
+error-on-warning = true
+output-format = "concise"
+
+[environment]
+root = [".", "packages/griffelib/src", "packages/griffecli/src"]

{griffe-2.0.2 → griffe-2.2.0}/config/vscode/launch.json

@@ -41,7 +41,6 @@
                 "-vvv",
                 "--no-cov",
                 "--dist=no",
-                "tests",
                 "-k=${input:tests_selection}"
             ]
         }
@@ -54,4 +53,4 @@
             "default": ""
         }
     ]
-}
+}

{griffe-2.0.2 → griffe-2.2.0}/docs/extensions/built-in/dataclasses.md

@@ -25,7 +25,7 @@ def __init__(self, uid: int, name: str, capacity: int = 10, available: bool = Tr
 
 Additional metadata like `ClassVar`, the `init` and `kw_only` parameters, or the `KW_ONLY` sentinel are also recognized and will update the `__init__` method signature accordingly.
 
-**This extension is enabled by default.** It is always added last. If you need to give it a higher priority, you can explictly enable it to change its position in the list of extensions (it will run only once):
+**This extension is enabled by default.** It is always added last. If you need to give it a higher priority, you can explicitly enable it to change its position in the list of extensions (it will run only once):
 
 === "CLI"
     ```console

{griffe-2.0.2 → griffe-2.2.0}/docs/extensions/official.md

@@ -5,11 +5,11 @@ Official extensions are developed and maintained within the mkdocstrings organiz
 Extension | Description
 --------- | -----------
 [`autodocstringstyle`](official/autodocstringstyle.md) | Set docstring style to `auto` for external packages.
- [`inherited-docstrings`](official/inherited-docstrings.md) | Inherit docstrings from parent classes.
+[`inherited-docstrings`](official/inherited-docstrings.md) | Inherit docstrings from parent classes.
 [`public-redundant-aliases`](official/public-redundant-aliases.md) | Mark objects imported with redundant aliases as public.
 [`public-wildcard-imports`](official/public-wildcard-imports.md) | Mark wildcard imported objects as public.
- [`pydantic`](official/pydantic.md) | Support for [Pydantic](https://docs.pydantic.dev/latest/) models.
+[`pydantic`](official/pydantic.md) | Support for [Pydantic](https://docs.pydantic.dev/latest/) models.
 [`runtime-objects`](official/runtime-objects.md) | Access runtime objects corresponding to each loaded Griffe object through their `extra` attribute.
 [`sphinx`](official/sphinx.md) | Parse [Sphinx](https://www.sphinx-doc.org/)-comments above attributes (`#:`) as docstrings.
- [`typing-doc`](official/typingdoc.md) | Support for [PEP 727](https://peps.python.org/pep-0727/)'s [`typing.Doc`][typing_extensions.Doc], "Documentation in Annotated Metadata".
- [`warnings-deprecated`](official/warnings-deprecated.md) | Support for [PEP 702](https://peps.python.org/pep-0702/)'s [`warnings.deprecated`][], "Marking deprecations using the type system".
+[`typing-doc`](official/typingdoc.md) | Support for [PEP 727](https://peps.python.org/pep-0727/)'s [`typing.Doc`][typing_extensions.Doc], "Documentation in Annotated Metadata".
+[`warnings-deprecated`](official/warnings-deprecated.md) | Support for [PEP 702](https://peps.python.org/pep-0702/)'s [`warnings.deprecated`][], "Marking deprecations using the type system".

{griffe-2.0.2 → griffe-2.2.0}/docs/guide/contributors/architecture.md

@@ -24,7 +24,8 @@ descriptions = {
     "src": "The source of our Python package(s). See [Sources](#sources) and [Program structure](#program-structure).",
     "src/griffe": "Our public API, exposed to users. See [Program structure](#program-structure).",
     "packages/griffelib/src/griffe/_internal": "Our internal API, hidden from users. See [Program structure](#program-structure).",
-    "tests": "Our test suite. See [Tests](#tests).",
+    "packages/griffecli/tests": "Our test suite. See [Tests](#tests).",
+    "packages/griffelib/tests": "Our test suite. See [Tests](#tests).",
     ".copier-answers.yml": "The answers file generated by [Copier](https://copier.readthedocs.io/en/stable/). See [Boilerplate](#boilerplate).",
     "devdeps.txt": "Our development dependencies specification. See [`make setup`][command-setup] command.",
     "duties.py": "Our project tasks, written with [duty](https://pawamoy.github.io/duty). See [Tasks][tasks].",

{griffe-2.0.2 → griffe-2.2.0}/docs/guide/users/checking.md

@@ -115,6 +115,30 @@ jobs:
 
 The last step will fail the workflow if any breaking change is found.
 
+### Azure Pipelines {#ci-azdo}
+
+Here is a quick example on how to use Griffe in an Azure Pipeline. Griffe can format its output using Azure DevOps [task logging commands](https://learn.microsoft.com/en-us/azure/devops/pipelines/scripts/logging-commands?view=azure-devops&tabs=bash#task-commands), similar to GitHub Actions messages:
+
+```yaml
+jobs:
+- name: check-api
+  pool:
+    vmImage: 'ubuntu-latest'
+  steps:
+  - checkout: self
+    fetchDepth: 0  # We the need the full Git history.
+  - task: CmdLine@2
+    inputs:
+      script: pip install --user griffe
+  - task: CmdLine@2
+    inputs:
+      # The following command will compare current changes to latest tag.
+      script: |
+        griffe check --search src --format azdo your_package_name
+```
+
+The last step will fail the workflow if any breaking change is found.
+
 ## Detected breakages
 
 In this section, we will describe the breakages that Griffe detects, giving some code examples and hints on how to properly communicate breakages with deprecation messages before actually releasing them.
@@ -720,6 +744,17 @@ When running `griffe check` in CI, you can enable GitHub's annotations thanks to
 ::warning file=src/griffe/finder.py,line=77,title=NamespacePackage.path::Attribute value was changed: `path` -> unset
 ```
 
+[](){#format-azdo}
+
+### Azure DevOps / Azure Pipelines
+
+- **CLI**: `-f azdo`
+- **API**: `check(..., style="azdo")` / `check(..., style=ExplanationStyle.AZURE_DEVOPS)`
+
+Similarly to the GitHub workflow syntax, Griffe is capable of using the task logging command syntax used by Azure Pipelines as part of the Azure DevOps Services.
+
+When running `griffe check` in CI, warnings are displayed in the warnings panel of your pipeline.
+
 ## Next steps
 
 If you are using a third-party library to mark objects as public, or if you follow conventions different than the one Griffe understands, you might get false-positives, or breaking changes could go undetected. In that case, you might be interested in [extending](extending.md) how Griffe loads API data to support these third-party libraries or other conventions.

{griffe-2.0.2 → griffe-2.2.0}/docs/guide/users/how-to/set-docstring-styles.md

@@ -1,6 +1,6 @@
 # Setting the right docstring style for every docstring
 
-Griffe attaches the specified docstring style and parsing options to each object in the tree of the package(s) you load. If your package(s) use several docstring styles, some of these objects will have the wrong style attached to them. This is problematic because other Griffe extensions rely on this attached style to parse docstrings and modify them. We plan to alleviate this limitation in the future (see [issue-340](https://github.com/mkdocstrings/griffe/issues/340)), but the most robust thing you can do is to make sure each object has the *right style* attached, as easly as possible, so that other extensions can work without issue.
+Griffe attaches the specified docstring style and parsing options to each object in the tree of the package(s) you load. If your package(s) use several docstring styles, some of these objects will have the wrong style attached to them. This is problematic because other Griffe extensions rely on this attached style to parse docstrings and modify them. We plan to alleviate this limitation in the future (see [issue-340](https://github.com/mkdocstrings/griffe/issues/340)), but the most robust thing you can do is to make sure each object has the *right style* attached, as easily as possible, so that other extensions can work without issue.
 
 There are currently two ways to make sure objects have the right docstring style attached as early as possible:
 

{griffe-2.0.2 → griffe-2.2.0}/docs/guide/users/how-to/support-decorators.md

@@ -25,7 +25,7 @@ import griffe
 
 
 class MyDecorator(griffe.Extension):
-    """An extension to suport my decorator."""
+    """An extension to support my decorator."""
 ```
 
 Now we can declare the [`on_instance`][griffe.Extension.on_instance] hook, which receives any kind of Griffe object ([`Module`][griffe.Module], [`Class`][griffe.Class], [`Function`][griffe.Function], [`Attribute`][griffe.Attribute], [`TypeAlias`][griffe.TypeAlias]), or we could use a kind-specific hook such as [`on_module_instance`][griffe.Extension.on_module_instance], [`on_class_instance`][griffe.Extension.on_class_instance], [`on_function_instance`][griffe.Extension.on_function_instance], [`on_attribute_instance`][griffe.Extension.on_attribute_instance] and [`on_type_alias_instance`][griffe.Extension.on_type_alias_instance]. For example, if you know your decorator is only ever used on class declarations, it would make sense to use `on_class_instance`.
@@ -37,7 +37,7 @@ import griffe
 
 
 class MyDecorator(griffe.Extension):
-    """An extension to suport my decorator."""
+    """An extension to support my decorator."""
 
     def on_function_instance(self, *, func: griffe.Function, **kwargs) -> None:
         ...
@@ -50,7 +50,7 @@ import griffe
 
 
 class MyDecorator(griffe.Extension):
-    """An extension to suport my decorator."""
+    """An extension to support my decorator."""
 
     def on_function_instance(self, *, func: griffe.Function, **kwargs) -> None:
         for decorator in func.decorators:

{griffe-2.0.2 → griffe-2.2.0}/docs/guide/users/navigating.md

@@ -89,13 +89,13 @@ To access an object's members, there are a few options:
 
 The same way members are accessed, they can also be set:
 
-- Dictionary-like item assignment: `markdown["thing"] = ...`, also supporting dotted-paths and string tuples. This will (re)assign only regular members: inherited members (classes only) are re-computed everytime they are accessed.
+- Dictionary-like item assignment: `markdown["thing"] = ...`, also supporting dotted-paths and string tuples. This will (re)assign only regular members: inherited members (classes only) are re-computed every time they are accessed.
 - Safer method for extensions: `markdown.set_member("thing", ...)`, also supporting dotted-paths and string tuples.
 - Regular member assignment: `markdown.members["thing"] = ...`. **This is not recommended, as the assigned member's `parent` attribute will not be automatically updated.**
 
 ...and deleted:
 
-- Dictionary-like item deletion: `del markdown["thing"]`, also supporting dotted-paths and string tuples. This will delete only regular members: inherited members (classes only) are re-computed everytime they are accessed.
+- Dictionary-like item deletion: `del markdown["thing"]`, also supporting dotted-paths and string tuples. This will delete only regular members: inherited members (classes only) are re-computed every time they are accessed.
 - Safer method for extensions: `markdown.del_member("thing")`, also supporting dotted-paths and string tuples.
 - Regular member deletion: `del markdown.members["thing"]`. **This is not recommended, as the [`aliases`][griffe.Object.aliases] attribute of other objects in the tree will not be automatically updated.**
 
@@ -103,7 +103,7 @@ The same way members are accessed, they can also be set:
 
 Griffe supports class inheritance, both when visiting and inspecting modules.
 
-To access members of a class that are inherited from base classes, use the [`inherited_members`][griffe.Object.inherited_members] attribute. Everytime you access inherited members, the base classes of the given class will be resolved, then the MRO (Method Resolution Order) will be computed for these base classes, and a dictionary of inherited members will be built. Make sure to store the result in a variable to avoid re-computing it everytime (you are responsible for the caching part). Also make sure to only access `inherited_members` once everything is loaded by Griffe, to avoid computing things too early. Don't try to access inherited members in extensions, while visiting or inspecting modules.
+To access members of a class that are inherited from base classes, use the [`inherited_members`][griffe.Object.inherited_members] attribute. Every time you access inherited members, the base classes of the given class will be resolved, then the MRO (Method Resolution Order) will be computed for these base classes, and a dictionary of inherited members will be built. Make sure to store the result in a variable to avoid re-computing it every time (you are responsible for the caching part). Also make sure to only access `inherited_members` once everything is loaded by Griffe, to avoid computing things too early. Don't try to access inherited members in extensions, while visiting or inspecting modules.
 
 Inherited members are aliases that point at the corresponding members in parent classes. These aliases will have their [`inherited`][griffe.Alias.inherited] attribute set to true.
 

{griffe-2.0.2 → griffe-2.2.0}/docs/guide/users/recommendations/public-apis.md

@@ -39,7 +39,7 @@ Besides, logging and exception messages simply cannot allow deprecation periods
 
 ## Conventions
 
-Python does not provide any standard way to declare public APIs. However we do have official recommendations and a few conventions.
+Python does not provide any way to *enforce* public APIs: users can always import and use internal objects if they really want to. However, Python *does* specify a standard way to *declare* public APIs: the `__all__` attribute (see below), which is complemented by official recommendations and a few conventions.
 
 ### Underscore prefix
 
@@ -61,12 +61,18 @@ from elsewhere import something
 
 Even though `something` doesn't start with an underscore, it was imported so it is not considered public.
 
+Note that this exception comes from [PEP 8](https://peps.python.org/pep-0008/#public-and-internal-interfaces) ("imported names should always be considered an implementation detail") and from the conventions used by type checkers, not from the language reference: the latter states that when `__all__` is not defined, the set of public names includes *all* names found in the module's namespace which do not begin with an underscore, imported ones included.
+
 ### `__all__` list
 
-There is another convention that lets you do the opposite: explicitly mark objects as public. This convention uses the `__all__` module-level attribute, which is a list of strings containing the names of the public objects.
+Python also provides a mechanism that lets you do the opposite: explicitly mark objects as public. This mechanism uses the `__all__` module-level attribute, which is a list of strings containing the names of the public objects.
+
+Contrary to popular belief, `__all__` is not merely a convention, nor just a way to control wildcard imports: it is actually specified in [the Python language reference](https://docs.python.org/3/reference/simple_stmts.html#the-import-statement) as *the* mechanism that determines the public names of a module:
+
+> The public names defined by a module are determined by checking the module's namespace for a variable named `__all__`; if defined, it must be a sequence of strings which are names defined or imported by that module. [...] The names given in `__all__` are all considered public and are required to exist. If `__all__` is not defined, the set of public names includes all names found in the module's namespace which do not begin with an underscore character (`'_'`). `__all__` should contain the entire public API. It is intended to avoid accidentally exporting items that are not part of the API (such as library modules which were imported and used within the module).
 
 ```python title="package/module.py"
-__all__ [
+__all__ = [
     "this_function",
     "ThisClass",
 ]
@@ -86,7 +92,7 @@ class ThisOtherClass:
 
 Here, even though `this_other_function` and `ThisOtherClass` are *not* prefixed with underscores, they are not considered public, because we explicitly and only marked `this_function` and `ThisClass` as public.
 
-Declaring `__all__` has another beneficial effect: it affects wildcard imports. When your users use wildcard imports to import things from one of your modules, Python will only import the objects that are listed in `__all__`. Without `__all__`, it would import all objects that are not prefixed with an underscore, *including objects already imported from elsewhere*. This can cause serious namespace pollution, and even slow down Python code when wildcard imports are chained. [We actually recommend avoiding wildcard imports](python-code.md#avoid-wildcard-imports).
+Declaring `__all__` has a beneficial side-effect, which is often mistaken for its primary purpose: it affects wildcard imports. When your users use wildcard imports to import things from one of your modules, Python will only import the objects that are listed in `__all__`. Without `__all__`, it would import all objects that are not prefixed with an underscore, *including objects already imported from elsewhere*. This can cause serious namespace pollution, and even slow down Python code when wildcard imports are chained. [We actually recommend avoiding wildcard imports](python-code.md#avoid-wildcard-imports).
 
 By declaring `__all__`, your public API becomes explicit, and explicit is better than implicit. But `__all__` only works for module-level objects. Within classes, you will still have to rely on the underscore prefix convention to mark methods or attributes as internal/private.
 
@@ -126,7 +132,7 @@ Note that the wildcard imports logic stays the same, and imports either all obje
 > GRIFFE: **Our recommendation — Use the underscore prefix and `__all__` conventions.**
 > Use both the underscore prefix convention for consistent naming at module and class levels, and the `__all__` convention for declaring your public API. We do not recommend using the redundant aliases convention, because it doesn't provide any information at runtime. We do not recommend the wildcard import convention either, for the same reason and [for additional reasons mentioned here](python-code.md#avoid-wildcard-imports). We still provide the [`griffe-public-redundant-aliases`](https://mkdocstrings.github.io/griffe-public-redundant-aliases/) and [`griffe-public-wildcard-imports`](https://mkdocstrings.github.io/griffe-public-wildcard-imports/) extensions for those who would still like to rely on these conventions.
 >
-> Our recommendation matches [PEP 8](https://peps.python.org/pep-0008/#public-and-internal-interfaces):
+> Our recommendation matches the language reference (quoted above) as well as [PEP 8](https://peps.python.org/pep-0008/#public-and-internal-interfaces):
 >
 > > To better support introspection, modules should explicitly declare the names in their public API using the `__all__` attribute. Setting `__all__` to an empty list indicates that the module has no public API.
 >
@@ -202,7 +208,7 @@ Such changes sometimes go unnoticed before the breaking change is released, beca
 
 What if we could make this easier?
 
-By hiding your module layout from your public API, you're removing all these pain points at once. Any object can freely move around without ever impacting users. Maintainers do not need to set deprecation periods where old and new uses are supported, or bump the major part of their semantic version when they stop supporting the old use. Hiding the module layout also removes the ambiguity of whether a submodule is considered public or not: [PEP 8](https://peps.python.org/pep-0008/#public-and-internal-interfaces) doesn't mention anything about it, and it doesn't look like the `__all__` convention expects developers to list their submodules too. In the end it looks like submodules are only subject to the underscore prefix convention.
+By hiding your module layout from your public API, you're removing all these pain points at once. Any object can freely move around without ever impacting users. Maintainers do not need to set deprecation periods where old and new uses are supported, or bump the major part of their semantic version when they stop supporting the old use. Hiding the module layout also removes the ambiguity of whether a submodule is considered public or not: [PEP 8](https://peps.python.org/pep-0008/#public-and-internal-interfaces) doesn't mention anything about it, and it doesn't look like the `__all__` mechanism expects developers to list their submodules too. In the end it looks like submodules are only subject to the underscore prefix convention.
 
 So, how do we hide the module layout from the public API?
 
@@ -223,7 +229,7 @@ from my_package._combat import Combat
 from my_package._exploration import navigate
 from my_package._sorcery import cast_spell
 
-__all__ [
+__all__ = [
     "Combat",
     "navigate",
     "cast_spell",
@@ -303,7 +309,7 @@ my_package/
     Here the `Hello` class is exposed in both `my_package.module` and `my_package`.
 
     ```python title="my_package/module.py"
-    __all__ ["Hello"]
+    __all__ = ["Hello"]
 
     class Hello:
         ...
@@ -319,7 +325,7 @@ my_package/
     Here the `Hello` class is only exposed in `my_package.module`.
 
     ```python title="my_package/module.py"
-    __all__ ["Hello"]
+    __all__ = ["Hello"]
 
     class Hello:
         ...
@@ -444,7 +450,7 @@ In this script, we find our entrypoint, `griffe.main`, used programmatically.
 
 The second user of your CLI as API is... you again. When you write tests for your CLI, you import your entrypoints and call them by passing CLI options and arguments, maybe asserting the exit code raised with a `SystemExit` or the standard output/error thanks to [pytest's capture fixtures](https://docs.pytest.org/en/6.2.x/capture.html). Some simplified examples from our own test suite:
 
-```python title="tests/test_cli.py"
+```python
 import pytest
 import griffe
 

{griffe-2.0.2 → griffe-2.2.0}/docs/reference/docstrings.md

@@ -737,7 +737,7 @@ See previous tips for types in docstrings.
 
 ## Numpydoc-style
 
-Numpydoc docstrings, see [Numpydoc's documentation][numpydoc]
+Numpydoc docstrings, see [Numpydoc's documentation][numpydoc].
 
 ### Syntax {#numpydoc-syntax}
 

{griffe-2.0.2 → griffe-2.2.0}/duties.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.
+
 """Development tasks."""
 
 from __future__ import annotations
@@ -20,7 +36,7 @@ if TYPE_CHECKING:
     from duty.context import Context
 
 
-PY_SRC_PATHS = (Path(_) for _ in ("packages/griffecli/src", "packages/griffelib/src", "tests", "duties.py", "scripts"))
+PY_SRC_PATHS = (Path(_) for _ in ("packages", "duties.py", "scripts"))
 PY_SRC_LIST = tuple(str(_) for _ in PY_SRC_PATHS)
 PY_SRC = " ".join(PY_SRC_LIST)
 CI = os.environ.get("CI", "0") in {"1", "true", "yes", ""}
@@ -41,7 +57,7 @@ def _pyprefix(title: str) -> str:
 def _get_changelog_version() -> str:
     changelog_version_re = re.compile(r"^## \[(\d+\.\d+\.\d+)\].*$")
     with Path(__file__).parent.joinpath("CHANGELOG.md").open("r", encoding="utf8") as file:
-        return next(filter(bool, map(changelog_version_re.match, file))).group(1)  # ty:ignore[invalid-argument-type]
+        return next(filter(bool, map(changelog_version_re.match, file))).group(1)  # ty:ignore[unresolved-attribute]
 
 
 @duty
@@ -243,7 +259,6 @@ def check_types(ctx: Context) -> None:
         ✓ Checking types
         ```
     """
-    """Check that the code is correctly typed."""
     py = f"{sys.version_info.major}.{sys.version_info.minor}"
     ctx.run(
         tools.ty.check(
@@ -460,7 +475,7 @@ def test(ctx: Context, *cli_args: str) -> None:
     os.environ["PYTHONWARNDEFAULTENCODING"] = "1"
     ctx.run(
         tools.pytest(
-            "tests",
+            rootdir=".",
             config_file="config/pytest.ini",
             color="yes",
         ).add_args("-n", "auto", *cli_args),

{griffe-2.0.2 → griffe-2.2.0}/pyproject.toml

@@ -102,7 +102,7 @@ maintain = [
 ci = [
     "duty>=1.6",
     "griffe-inherited-docstrings>=1.1.2",
-    "jsonschema>=4.17",
+    "jsonschema>=4.18",
     "pysource-codegen>=0.7",
     "pysource-minimize>=0.10",
     "pytest>=8.2",

{griffe-2.0.2 → griffe-2.2.0}/scripts/gen_credits.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.
+
 # Script to generate the project's credits.
 
 from __future__ import annotations

griffe-2.2.0/scripts/gen_griffe_json.py

@@ -0,0 +1,25 @@
+# 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.
+
+# Generate the JSON API data file.
+
+import mkdocs_gen_files
+
+python_handler = mkdocs_gen_files.config.plugins["mkdocstrings"].get_handler("python")
+data = python_handler.collect("griffe", options=python_handler.get_options({}))
+
+with mkdocs_gen_files.open("griffe.json", "w") as fd:
+    print(data.as_json(full=True), file=fd)