You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/extensions/official/warnings-deprecated.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,7 @@
7
7
8
8
---
9
9
10
-
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.
10
+
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.
Copy file name to clipboardExpand all lines: docs/guide/contributors/architecture.md
+4-4Lines changed: 4 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -22,8 +22,8 @@ descriptions = {
22
22
"scripts": "Our different scripts. See [Scripts, configuration](#scripts-configuration).",
23
23
"site": "Documentation site, built with `make run mkdocs build` (git-ignored).",
24
24
"src": "The source of our Python package(s). See [Sources](#sources) and [Program structure](#program-structure).",
25
-
"packages/griffe/src/griffe": "Our public API, exposed to users. See [Program structure](#program-structure).",
26
-
"packages/griffe/src/griffe/_internal": "Our internal API, hidden from users. See [Program structure](#program-structure).",
25
+
"src/griffe": "Our public API, exposed to users. See [Program structure](#program-structure).",
26
+
"packages/griffelib/src/griffelib/_internal": "Our internal API, hidden from users. See [Program structure](#program-structure).",
27
27
"tests": "Our test suite. See [Tests](#tests).",
28
28
".copier-answers.yml": "The answers file generated by [Copier](https://copier.readthedocs.io/en/stable/). See [Boilerplate](#boilerplate).",
29
29
"devdeps.txt": "Our development dependencies specification. See [`make setup`][command-setup] command.",
@@ -108,7 +108,7 @@ The test suite is based on [pytest](https://docs.pytest.org/en/8.2.x/). Test mod
108
108
109
109
## Program structure
110
110
111
-
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`.
111
+
The internal API is contained within the `packages/griffelib/src/griffelib/_internal` folder. The top-level `griffe/__init__.py` module exposes all the public API, by importing the internal objects from `griffelib`, which itself imports from various submodules of `griffelib._internal`.
112
112
113
113
Users then import `griffe` directly, or import objects from it.
114
114
@@ -122,7 +122,7 @@ if os.getenv("DEPLOY") == "true":
Copy file name to clipboardExpand all lines: docs/guide/users/checking.md
+50-50Lines changed: 50 additions & 50 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,38 +9,38 @@ Griffe is able to compare two snapshots of your project to detect API breakages
9
9
By default, Griffe will compare the current code to the latest tag:
10
10
11
11
```console
12
-
$ griffecli check mypackage
12
+
$ griffe check mypackage
13
13
```
14
14
15
15
To specify another Git reference to check against, use the `--against` or `-a` option:
16
16
17
17
```console
18
-
$ griffecli check mypackage -a 0.2.0
18
+
$ griffe check mypackage -a 0.2.0
19
19
```
20
20
21
21
You can specify a Git tag, commit (hash), or even a branch: Griffe will create a worktree at this reference in a temporary directory, and clean it up after finishing.
22
22
23
23
If you want to also specify the *base* reference to use (instead of the current code), use the `--base` or `-b` option. Some examples:
24
24
25
25
```console
26
-
$ griffecli check mypackage -b HEAD -a 2.0.0
27
-
$ griffecli check mypackage -b 2.0.0 -a 1.0.0
28
-
$ griffecli check mypackage -b fix-issue-90 -a 1.2.3
29
-
$ griffecli check mypackage -b 8afcfd6e
26
+
$ griffe check mypackage -b HEAD -a 2.0.0
27
+
$ griffe check mypackage -b 2.0.0 -a 1.0.0
28
+
$ griffe check mypackage -b fix-issue-90 -a 1.2.3
29
+
$ griffe check mypackage -b 8afcfd6e
30
30
```
31
31
32
32
TIP: **Important:** Remember that the base is the most recent reference, and the one we compare it against is the oldest one.
33
33
34
-
The package name you pass to `griffecli check` must be found relative to the repository root. For Griffe to find packages in subfolders, pass the parent subfolder to the `--search` or `-s` option. Example for `src`-layouts:
34
+
The package name you pass to `griffe check` must be found relative to the repository root. For Griffe to find packages in subfolders, pass the parent subfolder to the `--search` or `-s` option. Example for `src`-layouts:
$ griffecli check package_name -b project-name==2.0 -a project-name==1.0
57
+
$ griffe check package_name -b project-name==2.0 -a project-name==1.0
58
58
```
59
59
60
60
You can let Griffe guess the package name by passing an empty string:
61
61
62
62
```console
63
-
$ griffecli check "" -b project-name==2.0 -a project-name==1.0
63
+
$ griffe check "" -b project-name==2.0 -a project-name==1.0
64
64
```
65
65
66
66
[PEP 508 version specifiers](https://peps.python.org/pep-0508/) are supported (`<`, `<=`, `!=`, `==`, `>=`, `>`, `~=`). For example, to compare v2 against the version just before it:
67
67
68
68
```console
69
-
$ griffecli check "" -b project-name==2.0 -a project-name<2.0
69
+
$ griffe check "" -b project-name==2.0 -a project-name<2.0
70
70
```
71
71
72
72
Without a version specifier on the base reference, or without a base reference at all, Griffe will use the latest available version. The two following commands compare the latest version against v1:
73
73
74
74
```console
75
-
$ griffecli check "" -b project-name -a project-name==1.0
76
-
$ griffecli check "" -a project-name==1.0
75
+
$ griffe check "" -b project-name -a project-name==1.0
76
+
$ griffe check "" -a project-name==1.0
77
77
```
78
78
79
79
Griffe will actually install packages in a cache directory. It means a few things: source distributions are supported, and only packages that are compatible with your current environment can be checked.
80
80
81
81
## Python API
82
82
83
-
To programmatically check for API breaking changes, you have to load two snapshots of your code base, for example using our [`load_git()`][griffelib.load_git] utility, and then passing them both to the [`find_breaking_changes()`][griffelib.find_breaking_changes] function. This function will yield instances of [`Breakage`][griffelib.Breakage]. It's up to you how you want to use these breakage instances.
83
+
To programmatically check for API breaking changes, you have to load two snapshots of your code base, for example using our [`load_git()`][griffe.load_git] utility, and then passing them both to the [`find_breaking_changes()`][griffe.find_breaking_changes] function. This function will yield instances of [`Breakage`][griffe.Breakage]. It's up to you how you want to use these breakage instances.
84
84
85
85
```python
86
86
import griffe
87
87
88
-
my_pkg_v1 =griffelib.load_git("my_pkg", ref="v1")
89
-
my_pkg_v2 =griffelib.load_git("my_pkg", ref="v2")
88
+
my_pkg_v1 =griffe.load_git("my_pkg", ref="v1")
89
+
my_pkg_v2 =griffe.load_git("my_pkg", ref="v2")
90
90
91
91
for breaking_change in find_breaking_changes(my_pkg_v1, my_pkg_v2):
92
92
print(breaking_change.explain())
@@ -110,7 +110,7 @@ jobs:
110
110
fetch-depth: 0# We the need the full Git history.
111
111
- uses: astral-sh/setup-uv@v6
112
112
# The following command will compare current changes to latest tag.
Depending on the detected breakages, the lines might be hard to read (being too compact), so `griffecli check` also accepts a `--verbose` or `-v` option to add some space to the output:
658
+
Depending on the detected breakages, the lines might be hard to read (being too compact), so `griffe check` also accepts a `--verbose` or `-v` option to add some space to the output:
The Markdown format is adapted for changelogs. It doesn't show the file and line number, and instead prints out the complete path of your API objects. With a bit of automation, you will be able to automatically insert a summary of breaking changes in your changelog entries.
When running `griffecli check` in CI, you can enable GitHub's annotations thanks to the GitHub output style. Annotations are displayed on specific lines of code. They are visible in the Checks tab. When you create an annotation for a file that is part of the pull request, the annotations are also shown in the Files changed tab.
704
+
When running `griffe check` in CI, you can enable GitHub's annotations thanks to the GitHub output style. Annotations are displayed on specific lines of code. They are visible in the Checks tab. When you create an annotation for a file that is part of the pull request, the annotations are also shown in the Files changed tab.
0 commit comments