Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/extensions/built-in/dataclasses.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,14 +29,14 @@ Additional metadata like `ClassVar`, the `init` and `kw_only` parameters, or the

=== "CLI"
```console
$ griffecli dump -e dataclasses,other my_package
$ griffe dump -e dataclasses,other my_package
```

=== "Python"
```python
import griffe

my_package = griffelib.load("my_package", extensions=griffelib.load_extensions("dataclasses", "other"))
my_package = griffe.load("my_package", extensions=griffe.load_extensions("dataclasses", "other"))
```

=== "mkdocstrings"
Expand Down
4 changes: 2 additions & 2 deletions docs/extensions/built-in/unpack-typeddict.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,14 +65,14 @@ To enable the extension:

=== "CLI"
```console
$ griffecli dump -e unpack_typeddict my_package
$ griffe dump -e unpack_typeddict my_package
```

=== "Python"
```python
import griffe

my_package = griffelib.load("my_package", extensions=griffelib.load_extensions("unpack_typeddict"))
my_package = griffe.load("my_package", extensions=griffe.load_extensions("unpack_typeddict"))
```

=== "mkdocstrings"
Expand Down
4 changes: 2 additions & 2 deletions docs/extensions/official/runtime-objects.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,11 @@ This extension stores runtime objects corresponding to each loaded Griffe object

```pycon
>>> import griffe
>>> griffe_data = griffelib.load("griffe", extensions=griffelib.load_extensions("griffe_runtime_objects"), resolve_aliases=True)
>>> griffe_data = griffe.load("griffe", extensions=griffe.load_extensions("griffe_runtime_objects"), resolve_aliases=True)
>>> griffe_data["parse"].extra
defaultdict(<class 'dict'>, {'runtime-objects': {'object': <function parse at 0x78685c951260>}})
>>> griffe_data["Module"].extra
defaultdict(<class 'dict'>, {'runtime-objects': {'object': <class 'griffelib._internal.models.Module'>}})
defaultdict(<class 'dict'>, {'runtime-objects': {'object': <class 'griffe._internal.models.Module'>}})
```

It can be useful in combination with mkdocstrings-python and custom templates, to iterate over object values or their attributes that couldn't be loaded by Griffe itself (for example, objects built dynamically and loaded as attributes won't have "members" to iterate over).
2 changes: 1 addition & 1 deletion docs/extensions/official/warnings-deprecated.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@

---

This extension adds support for functions and classes decorated with [`@warnings.deprecated(...)`][warnings.deprecated], as implemented thanks to [PEP 702](https://peps.python.org/pep-0702/). The message provided in the decorator call will be stored in the corresponding Griffe object's [`deprecated`][griffelib.Object.deprecated] attribute (usable by downstream rendering templates), and will also add an admonition to the object's docstring with the provided message as text.
This extension adds support for functions and classes decorated with [`@warnings.deprecated(...)`][warnings.deprecated], as implemented thanks to [PEP 702](https://peps.python.org/pep-0702/). The message provided in the decorator call will be stored in the corresponding Griffe object's [`deprecated`][griffe.Object.deprecated] attribute (usable by downstream rendering templates), and will also add an admonition to the object's docstring with the provided message as text.

```python
from warnings import deprecated
Expand Down
10 changes: 5 additions & 5 deletions docs/guide/contributors/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,8 @@ descriptions = {
"scripts": "Our different scripts. See [Scripts, configuration](#scripts-configuration).",
"site": "Documentation site, built with `make run mkdocs build` (git-ignored).",
"src": "The source of our Python package(s). See [Sources](#sources) and [Program structure](#program-structure).",
"packages/griffe/src/griffe": "Our public API, exposed to users. See [Program structure](#program-structure).",
"packages/griffe/src/griffe/_internal": "Our internal API, hidden from users. See [Program structure](#program-structure).",
"src/griffe": "Our public API, exposed to users. See [Program structure](#program-structure).",
"src/griffe/_internal": "Our internal API, hidden from users. See [Program structure](#program-structure).",
"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.",
Expand Down Expand Up @@ -104,11 +104,11 @@ Sources are located in the `src` folder, following the [src-layout](https://pack

Our test suite is located in the `tests` folder. It is located outside of the sources as to not pollute distributions (it would be very wrong to publish a `tests` package as part of our distributions, since this name is extremely common), or worse, the public API. The `tests` folder is however included in our source distributions (`.tar.gz`), alongside most of our metadata and configuration files. Check out `pyproject.toml` to get the full list of files included in our source distributions.

The test suite is based on [pytest](https://docs.pytest.org/en/8.2.x/). Test modules reflect our internal API structure, and except for a few test modules that test specific aspects of our API, each test module tests the logic from the corresponding module in the internal API. For example, `test_finder.py` tests code of the `griffelib._internal.finder` internal module, while `test_functions` tests our ability to extract correct information from function signatures, statically. The general rule of thumb when writing new tests is to mirror the internal API. If a test touches to many aspects of the loading process, it can be added to the `test_loader` test module.
The test suite is based on [pytest](https://docs.pytest.org/en/8.2.x/). Test modules reflect our internal API structure, and except for a few test modules that test specific aspects of our API, each test module tests the logic from the corresponding module in the internal API. For example, `test_finder.py` tests code of the `griffe._internal.finder` internal module, while `test_functions` tests our ability to extract correct information from function signatures, statically. The general rule of thumb when writing new tests is to mirror the internal API. If a test touches to many aspects of the loading process, it can be added to the `test_loader` test module.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

griffe._internal.finder -- this and similar are wrong

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 8ecd876. Updated all griffe._internal references to griffelib._internal in architecture.md, loading.md, navigating.md, expressions.md, and runtime-objects.md to reflect the new package structure.


## Program structure

The internal API is contained within the `packages/griffe/src/griffe/_internal` folder. The top-level `griffe/__init__.py` module exposes all the public API, by importing the internal objects from various submodules of `griffelib._internal`.
The internal API is contained within the `src/griffe/_internal` folder. The top-level `griffe/__init__.py` module exposes all the public API, by importing the internal objects from various submodules of `griffe._internal`.

Users then import `griffe` directly, or import objects from it.

Expand All @@ -122,7 +122,7 @@ if os.getenv("DEPLOY") == "true":
from pydeps.target import Target

cli.verbose = cli._not_verbose
options = cli.parse_args(["packages/griffe/src/griffe", "--noshow", "--reverse"])
options = cli.parse_args(["src/griffe", "--noshow", "--reverse"])
colors.START_COLOR = 128
target = Target(options["fname"])
with target.chdir_work():
Expand Down
4 changes: 4 additions & 0 deletions docs/guide/contributors/workflow.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,10 @@ Deprecated code should also be marked as legacy code. We use [Yore](https://pawa
Examples:

```python title="Remove function when we bump to 2.0"
# YORE: Bump 2: Remove block.
def deprecated_function():
...
```

```python title="Simplify imports when Python 3.15 is EOL"
# YORE: EOL 3.15: Replace block with line 4.
Expand Down
Loading