sphinx-github-changelog 2.1.1__tar.gz → 2.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/.github/renovate.json5 +1 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/.github/workflows/ci.yml +9 -1
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/.pre-commit-config.yaml +1 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/CONTRIBUTING.rst +29 -2
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/PKG-INFO +39 -20
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/README.rst +37 -19
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/pyproject.toml +4 -1
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/sphinx_github_changelog/changelog.py +26 -13
- sphinx_github_changelog-2.3.0/sphinx_github_changelog/config.py +64 -0
- sphinx_github_changelog-2.3.0/sphinx_github_changelog/github_releases.py +144 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/sphinx_github_changelog/setup.py +2 -4
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/sphinx_github_changelog/urls.py +8 -4
- sphinx_github_changelog-2.3.0/tests/acceptance/cassettes/test_all/test_build.yaml +176 -0
- sphinx_github_changelog-2.3.0/tests/acceptance/cassettes/test_all/test_build_404.yaml +69 -0
- sphinx_github_changelog-2.3.0/tests/acceptance/changelog.html +272 -0
- sphinx_github_changelog-2.3.0/tests/acceptance/test_all.py +61 -0
- sphinx_github_changelog-2.3.0/tests/conftest.py +103 -0
- {sphinx_github_changelog-2.1.1/tests/roots/test-error → sphinx_github_changelog-2.3.0/tests/roots/test-404}/conf.py +0 -2
- sphinx_github_changelog-2.3.0/tests/roots/test-404/index.rst +4 -0
- sphinx_github_changelog-2.3.0/tests/roots/test-all/conf.py +5 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/tests/roots/test-all/index.rst +1 -1
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/tests/unit/test_changelog.py +48 -4
- sphinx_github_changelog-2.3.0/tests/unit/test_config.py +40 -0
- sphinx_github_changelog-2.3.0/tests/unit/test_github_releases.py +236 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/tests/unit/test_urls.py +9 -4
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/uv.lock +171 -0
- sphinx_github_changelog-2.1.1/sphinx_github_changelog/config.py +0 -40
- sphinx_github_changelog-2.1.1/sphinx_github_changelog/github_releases.py +0 -88
- sphinx_github_changelog-2.1.1/tests/acceptance/changelog.html +0 -71
- sphinx_github_changelog-2.1.1/tests/acceptance/test_all.py +0 -108
- sphinx_github_changelog-2.1.1/tests/conftest.py +0 -53
- sphinx_github_changelog-2.1.1/tests/unit/test_github_releases.py +0 -115
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/.editorconfig +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/.github/CODEOWNERS +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/.github/PULL_REQUEST_TEMPLATE.md +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/.github/release.yml +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/.github/workflows/autofix.yml +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/.github/workflows/coverage-comment.yml +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/.gitignore +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/.readthedocs.yml +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/CHANGELOG.rst +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/CODE_OF_CONDUCT.rst +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/LICENSE +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/docs/Makefile +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/docs/conduct.rst +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/docs/conf.py +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/docs/contributing.rst +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/docs/index.rst +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/scripts/README.md +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/scripts/docs +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/scripts/lint +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/scripts/tests +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/sphinx_github_changelog/__init__.py +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/sphinx_github_changelog/credentials.py +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/sphinx_github_changelog/exceptions.py +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/tests/__init__.py +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/tests/acceptance/__init__.py +0 -0
- {sphinx_github_changelog-2.1.1/tests/roots/test-all → sphinx_github_changelog-2.3.0/tests/roots/test-error}/conf.py +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/tests/roots/test-error/index.rst +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/tests/unit/__init__.py +0 -0
- {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/tests/unit/test_git.py +0 -0
|
@@ -31,6 +31,8 @@ jobs:
|
|
|
31
31
|
|
|
32
32
|
- name: Run prek
|
|
33
33
|
uses: j178/prek-action@bdca6f102f98e2b4c7029491a53dfd366469e33d # v2.0.4
|
|
34
|
+
env:
|
|
35
|
+
PREK_SKIP: no-commit-to-branch
|
|
34
36
|
|
|
35
37
|
tests:
|
|
36
38
|
strategy:
|
|
@@ -81,10 +83,13 @@ jobs:
|
|
|
81
83
|
pattern: coverage-*
|
|
82
84
|
merge-multiple: true
|
|
83
85
|
|
|
86
|
+
- name: Prepare merged coverage data
|
|
87
|
+
run: |
|
|
88
|
+
pipx run coverage combine
|
|
89
|
+
|
|
84
90
|
- name: Display coverage
|
|
85
91
|
uses: ewjoachim/python-coverage-comment-action@63f52f4fbbffada6e8dee8ec432de7e01df9ba79 # v3.41
|
|
86
92
|
with:
|
|
87
|
-
MERGE_COVERAGE_FILES: true
|
|
88
93
|
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
|
89
94
|
|
|
90
95
|
- name: Store Pull Request comment to be posted
|
|
@@ -93,6 +98,9 @@ jobs:
|
|
|
93
98
|
name: python-coverage-comment-action
|
|
94
99
|
path: python-coverage-comment-action.txt
|
|
95
100
|
|
|
101
|
+
- name: Enforce coverage >= 100%
|
|
102
|
+
run: pipx run coverage report --fail-under=100
|
|
103
|
+
|
|
96
104
|
publish:
|
|
97
105
|
name: Publish package to PyPI
|
|
98
106
|
if: github.event_name == 'push' && github.ref_type == 'tag'
|
|
@@ -29,7 +29,10 @@ I want a venv to play locally
|
|
|
29
29
|
|
|
30
30
|
$ uv sync
|
|
31
31
|
|
|
32
|
-
Use
|
|
32
|
+
Use ``uv sync --python=3.x`` if you want to work on a specific Python version.
|
|
33
|
+
|
|
34
|
+
There is no need to activate ``.venv`` manually. Run project commands through
|
|
35
|
+
``uv run`` instead.
|
|
33
36
|
|
|
34
37
|
I want to run the tests
|
|
35
38
|
---------------------------
|
|
@@ -40,6 +43,30 @@ The easiest way to run the tests on a single python version is:
|
|
|
40
43
|
|
|
41
44
|
$ uv run pytest
|
|
42
45
|
|
|
46
|
+
Coverage is enforced at 100% on merged matrix coverage in CI. Branches gated by
|
|
47
|
+
Python-version checks do not need to be covered in every local test run, as long as
|
|
48
|
+
they are covered by at least one CI matrix job. When you run pytest locally, you'll get
|
|
49
|
+
a terminal report at the bottom as well as a more detailed HTML report in
|
|
50
|
+
``htmlcov/index.html``. In PRs, a summary of the coverage report is posted as a comment
|
|
51
|
+
by the CI.
|
|
52
|
+
|
|
53
|
+
Acceptance tests and fixtures
|
|
54
|
+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
55
|
+
|
|
56
|
+
Acceptance tests in ``tests/acceptance/`` are snapshot-like tests of
|
|
57
|
+
the built HTML.
|
|
58
|
+
|
|
59
|
+
If the normalized HTML output changes, ``tests/acceptance/changelog.html`` is
|
|
60
|
+
rewritten by the test before it fails. Review the updated fixture, then run the
|
|
61
|
+
test again and commit the fixture change if it is expected.
|
|
62
|
+
|
|
63
|
+
Those tests also use VCR cassettes from ``tests/acceptance/cassettes``.
|
|
64
|
+
If the GitHub API fixture data needs to be refreshed, use:
|
|
65
|
+
|
|
66
|
+
.. code-block:: console
|
|
67
|
+
|
|
68
|
+
# Re-record interactions in the selected test run
|
|
69
|
+
$ uv run pytest --record-mode=rewrite
|
|
43
70
|
|
|
44
71
|
I want to build the documentation
|
|
45
72
|
---------------------------------
|
|
@@ -49,7 +76,7 @@ Build with:
|
|
|
49
76
|
.. code-block:: console
|
|
50
77
|
|
|
51
78
|
$ scripts/docs
|
|
52
|
-
$ python -m webbrowser docs/_build/html/index.html
|
|
79
|
+
$ uv run python -m webbrowser docs/_build/html/index.html
|
|
53
80
|
|
|
54
81
|
If Sphinx's console output is localized, and you would rather have it in English,
|
|
55
82
|
use the environment variable ``export LC_ALL=C.utf-8``.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: sphinx-github-changelog
|
|
3
|
-
Version: 2.
|
|
3
|
+
Version: 2.3.0
|
|
4
4
|
Summary: Build a sphinx changelog from GitHub Releases
|
|
5
5
|
Project-URL: Homepage, https://sphinx-github-changelog.readthedocs.io/en/latest/
|
|
6
6
|
Project-URL: Repository, https://github.com/ewjoachim/sphinx-github-changelog
|
|
@@ -23,6 +23,7 @@ Requires-Dist: docutils
|
|
|
23
23
|
Requires-Dist: httpx
|
|
24
24
|
Requires-Dist: myst-parser>=5.1.0
|
|
25
25
|
Requires-Dist: sphinx
|
|
26
|
+
Requires-Dist: tenacity
|
|
26
27
|
Description-Content-Type: text/x-rst
|
|
27
28
|
|
|
28
29
|
Sphinx Github Changelog: Build a sphinx changelog from GitHub Releases
|
|
@@ -154,7 +155,7 @@ git remotes in this order:
|
|
|
154
155
|
1. ``upstream`` remote
|
|
155
156
|
2. ``origin`` remote
|
|
156
157
|
|
|
157
|
-
The
|
|
158
|
+
The GitHub API base URL and GitHub root URL are derived from this URL.
|
|
158
159
|
|
|
159
160
|
If for any reason, you'd rather provide the repository explicitly (e.g. the doc
|
|
160
161
|
repo doesn't match the repo you're releasing from, or anything else), you can
|
|
@@ -165,8 +166,13 @@ details.
|
|
|
165
166
|
Authentication
|
|
166
167
|
--------------
|
|
167
168
|
|
|
168
|
-
The extension uses the GitHub
|
|
169
|
-
|
|
169
|
+
The extension uses the GitHub Releases REST API to retrieve the changelog.
|
|
170
|
+
|
|
171
|
+
For public repositories, this can usually work without authentication, though it's not
|
|
172
|
+
recommended as GitHub applies IP-based rate limits, so this may make your builds flaky.
|
|
173
|
+
Note that there will be automatic retries after HTTP 429 responses, controlled by the
|
|
174
|
+
``sphinx_github_changelog_retries`` option (see below). For private repositories (or
|
|
175
|
+
when unauthenticated requests are rate limited), you need a GitHub API token.
|
|
170
176
|
|
|
171
177
|
Tokens can be read from (in this order):
|
|
172
178
|
|
|
@@ -189,13 +195,12 @@ variable:
|
|
|
189
195
|
env:
|
|
190
196
|
SPHINX_GITHUB_CHANGELOG_TOKEN: ${{ github.token }}
|
|
191
197
|
|
|
192
|
-
If you're not in one of the cases above
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
.. __: https://github.com/readthedocs/readthedocs.org/issues/13053
|
|
198
|
+
If you're not in one of the cases above and your build environment cannot use
|
|
199
|
+
anonymous API access reliably (e.g. rate limits), you'll need a personal access
|
|
200
|
+
token. If the repository is public, the token doesn't need any special access
|
|
201
|
+
(you can uncheck everything). For private and internal repositories, the token
|
|
202
|
+
must have ``repo`` scope (classic tokens) or ``contents: read`` access
|
|
203
|
+
(fine-grained tokens).
|
|
199
204
|
|
|
200
205
|
Pass the token as the ``SPHINX_GITHUB_CHANGELOG_TOKEN`` (or ``GITHUB_TOKEN``)
|
|
201
206
|
environment variable. You can also set the token as ``sphinx_github_changelog_token`` in
|
|
@@ -205,15 +210,29 @@ environment variable. You can also set the token as ``sphinx_github_changelog_to
|
|
|
205
210
|
Extension options (``conf.py``)
|
|
206
211
|
-------------------------------
|
|
207
212
|
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
-
|
|
216
|
-
-
|
|
213
|
+
All options can also be set via environment variables of the same name in uppercase
|
|
214
|
+
(e.g. ``SPHINX_GITHUB_CHANGELOG_TOKEN``).
|
|
215
|
+
|
|
216
|
+
.. list-table::
|
|
217
|
+
:header-rows: 1
|
|
218
|
+
:widths: 30 10 60
|
|
219
|
+
|
|
220
|
+
* - Option
|
|
221
|
+
- Default
|
|
222
|
+
- Description
|
|
223
|
+
* - ``sphinx_github_changelog_token``
|
|
224
|
+
- ``None``
|
|
225
|
+
- GitHub API token. See above (please do **NOT** commit your secrets).
|
|
226
|
+
* - ``sphinx_github_changelog_root_repo``
|
|
227
|
+
- ``None``
|
|
228
|
+
- Root URL to the repository. Usually detected automatically.
|
|
229
|
+
* - ``sphinx_github_changelog_include_prereleases``
|
|
230
|
+
- ``True``
|
|
231
|
+
- Whether to include pre-releases in the changelog. Set to ``False``
|
|
232
|
+
to exclude them (env var accepts ``0``, ``false``, ``no``).
|
|
233
|
+
* - ``sphinx_github_changelog_retries``
|
|
234
|
+
- ``3``
|
|
235
|
+
- Number of retries after HTTP 429 responses from GitHub API. Will wait exponentially longer between each retry, starting at 5 second.
|
|
217
236
|
|
|
218
237
|
.. _ReadTheDocs: https://readthedocs.org/
|
|
219
238
|
|
|
@@ -127,7 +127,7 @@ git remotes in this order:
|
|
|
127
127
|
1. ``upstream`` remote
|
|
128
128
|
2. ``origin`` remote
|
|
129
129
|
|
|
130
|
-
The
|
|
130
|
+
The GitHub API base URL and GitHub root URL are derived from this URL.
|
|
131
131
|
|
|
132
132
|
If for any reason, you'd rather provide the repository explicitly (e.g. the doc
|
|
133
133
|
repo doesn't match the repo you're releasing from, or anything else), you can
|
|
@@ -138,8 +138,13 @@ details.
|
|
|
138
138
|
Authentication
|
|
139
139
|
--------------
|
|
140
140
|
|
|
141
|
-
The extension uses the GitHub
|
|
142
|
-
|
|
141
|
+
The extension uses the GitHub Releases REST API to retrieve the changelog.
|
|
142
|
+
|
|
143
|
+
For public repositories, this can usually work without authentication, though it's not
|
|
144
|
+
recommended as GitHub applies IP-based rate limits, so this may make your builds flaky.
|
|
145
|
+
Note that there will be automatic retries after HTTP 429 responses, controlled by the
|
|
146
|
+
``sphinx_github_changelog_retries`` option (see below). For private repositories (or
|
|
147
|
+
when unauthenticated requests are rate limited), you need a GitHub API token.
|
|
143
148
|
|
|
144
149
|
Tokens can be read from (in this order):
|
|
145
150
|
|
|
@@ -162,13 +167,12 @@ variable:
|
|
|
162
167
|
env:
|
|
163
168
|
SPHINX_GITHUB_CHANGELOG_TOKEN: ${{ github.token }}
|
|
164
169
|
|
|
165
|
-
If you're not in one of the cases above
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
.. __: https://github.com/readthedocs/readthedocs.org/issues/13053
|
|
170
|
+
If you're not in one of the cases above and your build environment cannot use
|
|
171
|
+
anonymous API access reliably (e.g. rate limits), you'll need a personal access
|
|
172
|
+
token. If the repository is public, the token doesn't need any special access
|
|
173
|
+
(you can uncheck everything). For private and internal repositories, the token
|
|
174
|
+
must have ``repo`` scope (classic tokens) or ``contents: read`` access
|
|
175
|
+
(fine-grained tokens).
|
|
172
176
|
|
|
173
177
|
Pass the token as the ``SPHINX_GITHUB_CHANGELOG_TOKEN`` (or ``GITHUB_TOKEN``)
|
|
174
178
|
environment variable. You can also set the token as ``sphinx_github_changelog_token`` in
|
|
@@ -178,15 +182,29 @@ environment variable. You can also set the token as ``sphinx_github_changelog_to
|
|
|
178
182
|
Extension options (``conf.py``)
|
|
179
183
|
-------------------------------
|
|
180
184
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
-
|
|
189
|
-
-
|
|
185
|
+
All options can also be set via environment variables of the same name in uppercase
|
|
186
|
+
(e.g. ``SPHINX_GITHUB_CHANGELOG_TOKEN``).
|
|
187
|
+
|
|
188
|
+
.. list-table::
|
|
189
|
+
:header-rows: 1
|
|
190
|
+
:widths: 30 10 60
|
|
191
|
+
|
|
192
|
+
* - Option
|
|
193
|
+
- Default
|
|
194
|
+
- Description
|
|
195
|
+
* - ``sphinx_github_changelog_token``
|
|
196
|
+
- ``None``
|
|
197
|
+
- GitHub API token. See above (please do **NOT** commit your secrets).
|
|
198
|
+
* - ``sphinx_github_changelog_root_repo``
|
|
199
|
+
- ``None``
|
|
200
|
+
- Root URL to the repository. Usually detected automatically.
|
|
201
|
+
* - ``sphinx_github_changelog_include_prereleases``
|
|
202
|
+
- ``True``
|
|
203
|
+
- Whether to include pre-releases in the changelog. Set to ``False``
|
|
204
|
+
to exclude them (env var accepts ``0``, ``false``, ``no``).
|
|
205
|
+
* - ``sphinx_github_changelog_retries``
|
|
206
|
+
- ``3``
|
|
207
|
+
- Number of retries after HTTP 429 responses from GitHub API. Will wait exponentially longer between each retry, starting at 5 second.
|
|
190
208
|
|
|
191
209
|
.. _ReadTheDocs: https://readthedocs.org/
|
|
192
210
|
|
|
@@ -29,7 +29,7 @@ classifiers = [
|
|
|
29
29
|
"Programming Language :: Python :: 3.13",
|
|
30
30
|
"Programming Language :: Python :: 3.14",
|
|
31
31
|
]
|
|
32
|
-
dependencies = ["docutils", "myst-parser>=5.1.0", "httpx", "Sphinx"]
|
|
32
|
+
dependencies = ["docutils", "myst-parser>=5.1.0", "httpx", "Sphinx", "tenacity"]
|
|
33
33
|
|
|
34
34
|
[project.urls]
|
|
35
35
|
Homepage = "https://sphinx-github-changelog.readthedocs.io/en/latest/"
|
|
@@ -44,8 +44,11 @@ dev = [
|
|
|
44
44
|
"pytest-cov",
|
|
45
45
|
"pytest-mock",
|
|
46
46
|
"pytest-httpx",
|
|
47
|
+
"pytest-recording",
|
|
47
48
|
"basedpyright",
|
|
48
49
|
"pytest-subprocess>=1.6.0",
|
|
50
|
+
"beautifulsoup4>=4.14.3",
|
|
51
|
+
"html5lib>=1.1",
|
|
49
52
|
]
|
|
50
53
|
docs = ["sphinx-rtd-theme"]
|
|
51
54
|
types = ["types-requests", "types-docutils"]
|
{sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/sphinx_github_changelog/changelog.py
RENAMED
|
@@ -48,22 +48,32 @@ def compute_changelog(
|
|
|
48
48
|
"(https://github.com/:owner/:repo/releases)"
|
|
49
49
|
) from exc
|
|
50
50
|
|
|
51
|
-
# If token is not provided, try to get it from helpers
|
|
51
|
+
# If token is not provided, try to get it from helpers.
|
|
52
|
+
# Missing credentials are tolerated: public repositories can still be
|
|
53
|
+
# queried anonymously via the GitHub REST API.
|
|
52
54
|
token = config.token
|
|
53
55
|
if not token:
|
|
54
56
|
try:
|
|
55
57
|
token = credentials.get_github_token(host=github_params.hostname)
|
|
56
58
|
except exceptions.CouldNotExtract:
|
|
57
|
-
|
|
59
|
+
token = None
|
|
58
60
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
61
|
+
try:
|
|
62
|
+
releases = github_releases.extract_releases(
|
|
63
|
+
github_params=github_params,
|
|
64
|
+
token=token,
|
|
65
|
+
retries=config.retries,
|
|
66
|
+
)
|
|
67
|
+
except exceptions.GitHubAPIError:
|
|
68
|
+
if token is None:
|
|
69
|
+
return no_token(changelog_url=options.changelog_url)
|
|
70
|
+
raise
|
|
64
71
|
|
|
65
72
|
pypi_name = extract_pypi_package_name(url=options.pypi)
|
|
66
73
|
|
|
74
|
+
if not config.include_prereleases:
|
|
75
|
+
releases = [r for r in releases if not r.is_prerelease]
|
|
76
|
+
|
|
67
77
|
result_nodes = (
|
|
68
78
|
node_for_release(release=release, pypi_name=pypi_name) for release in releases
|
|
69
79
|
)
|
|
@@ -74,8 +84,9 @@ def compute_changelog(
|
|
|
74
84
|
def no_token(changelog_url: str | None) -> list[nodes.Node]:
|
|
75
85
|
par = nodes.paragraph()
|
|
76
86
|
par += nodes.Text(
|
|
77
|
-
"Changelog was not built because
|
|
78
|
-
"An access token can be provided
|
|
87
|
+
"Changelog was not built because unauthenticated GitHub API access failed and "
|
|
88
|
+
"no GitHub authentication token was found. An access token can be provided "
|
|
89
|
+
"using the "
|
|
79
90
|
)
|
|
80
91
|
par += nodes.literal("", "SPHINX_GITHUB_CHANGELOG_TOKEN")
|
|
81
92
|
par += nodes.Text(" environment variable or the ")
|
|
@@ -113,9 +124,10 @@ def extract_pypi_package_name(url: str | None) -> str | None:
|
|
|
113
124
|
|
|
114
125
|
|
|
115
126
|
def get_release_title(title: str | None, tag: str):
|
|
127
|
+
version = tag.removeprefix("v")
|
|
116
128
|
if not title:
|
|
117
|
-
return
|
|
118
|
-
return title if
|
|
129
|
+
return version
|
|
130
|
+
return title if version in title else f"{version}: {title}"
|
|
119
131
|
|
|
120
132
|
|
|
121
133
|
def node_for_release(
|
|
@@ -126,12 +138,13 @@ def node_for_release(
|
|
|
126
138
|
return None # For now, draft releases are excluded
|
|
127
139
|
|
|
128
140
|
tag = release.tag_name
|
|
141
|
+
version = tag.removeprefix("v")
|
|
129
142
|
title = release.name
|
|
130
143
|
date = release.published_at.isoformat()
|
|
131
144
|
title = get_release_title(title=title, tag=tag)
|
|
132
145
|
|
|
133
146
|
# Section
|
|
134
|
-
id_section = nodes.make_id("release-" +
|
|
147
|
+
id_section = nodes.make_id("release-" + version)
|
|
135
148
|
section = nodes.section(ids=[id_section])
|
|
136
149
|
|
|
137
150
|
section += nodes.title(text=title)
|
|
@@ -143,7 +156,7 @@ def node_for_release(
|
|
|
143
156
|
subtitle += nodes.reference("", "GitHub", refuri=release.url)
|
|
144
157
|
if pypi_name:
|
|
145
158
|
subtitle += nodes.Text(" - ")
|
|
146
|
-
url = f"https://pypi.org/project/{pypi_name}/{
|
|
159
|
+
url = f"https://pypi.org/project/{pypi_name}/{version}/"
|
|
147
160
|
subtitle += nodes.reference("", "PyPI", refuri=url)
|
|
148
161
|
|
|
149
162
|
subtitle_paragraph = nodes.paragraph()
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import dataclasses
|
|
4
|
+
import os
|
|
5
|
+
from collections.abc import Iterator
|
|
6
|
+
from typing import Any, ClassVar
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
@dataclasses.dataclass
|
|
10
|
+
class ChangelogDirectiveOptions:
|
|
11
|
+
changelog_url: str | None = None
|
|
12
|
+
github: str | None = None
|
|
13
|
+
pypi: str | None = None
|
|
14
|
+
|
|
15
|
+
@classmethod
|
|
16
|
+
def from_options(cls, options: dict[str, str]):
|
|
17
|
+
return cls(
|
|
18
|
+
changelog_url=options.get("changelog-url"),
|
|
19
|
+
github=options.get("github"),
|
|
20
|
+
pypi=options.get("pypi"),
|
|
21
|
+
)
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
@dataclasses.dataclass
|
|
25
|
+
class ChangelogConfig:
|
|
26
|
+
token: str | None = None
|
|
27
|
+
root_repo: str | None = None
|
|
28
|
+
include_prereleases: bool = True
|
|
29
|
+
retries: int = 3
|
|
30
|
+
|
|
31
|
+
prefix: ClassVar[str] = "sphinx_github_changelog"
|
|
32
|
+
|
|
33
|
+
@classmethod
|
|
34
|
+
def get_config_defaults(cls) -> Iterator[tuple[str, str | bool | int | None]]:
|
|
35
|
+
for field in dataclasses.fields(cls):
|
|
36
|
+
option_name = f"{cls.prefix}_{field.name}"
|
|
37
|
+
env_value = os.environ.get(option_name.upper())
|
|
38
|
+
if field.type == "bool":
|
|
39
|
+
default: str | bool | int | None = (
|
|
40
|
+
env_value.lower() not in ("0", "false", "no")
|
|
41
|
+
if env_value
|
|
42
|
+
else bool(field.default)
|
|
43
|
+
)
|
|
44
|
+
elif field.type == "int":
|
|
45
|
+
if env_value is not None:
|
|
46
|
+
default = int(env_value)
|
|
47
|
+
elif isinstance(field.default, int):
|
|
48
|
+
default = field.default
|
|
49
|
+
else:
|
|
50
|
+
raise TypeError(
|
|
51
|
+
f"Unexpected default type for {field.name}: {field.default!r}"
|
|
52
|
+
)
|
|
53
|
+
else:
|
|
54
|
+
default = env_value
|
|
55
|
+
yield option_name, default
|
|
56
|
+
|
|
57
|
+
@classmethod
|
|
58
|
+
def from_sphinx_env_config(cls, sphinx_config: Any):
|
|
59
|
+
return cls(
|
|
60
|
+
token=sphinx_config.sphinx_github_changelog_token,
|
|
61
|
+
root_repo=sphinx_config.sphinx_github_changelog_root_repo,
|
|
62
|
+
include_prereleases=sphinx_config.sphinx_github_changelog_include_prereleases,
|
|
63
|
+
retries=sphinx_config.sphinx_github_changelog_retries,
|
|
64
|
+
)
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import dataclasses
|
|
4
|
+
import datetime
|
|
5
|
+
from collections.abc import Callable, Sequence
|
|
6
|
+
|
|
7
|
+
import httpx
|
|
8
|
+
from tenacity import (
|
|
9
|
+
Retrying,
|
|
10
|
+
nap,
|
|
11
|
+
retry_if_exception_type,
|
|
12
|
+
stop_after_attempt,
|
|
13
|
+
wait_exponential,
|
|
14
|
+
)
|
|
15
|
+
|
|
16
|
+
from . import exceptions, urls
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
class GitHubRateLimitError(Exception):
|
|
20
|
+
"""Raised internally to trigger retry logic on HTTP 429."""
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
@dataclasses.dataclass
|
|
24
|
+
class Release:
|
|
25
|
+
name: str | None
|
|
26
|
+
description: str | None
|
|
27
|
+
url: str
|
|
28
|
+
tag_name: str
|
|
29
|
+
published_at: datetime.date
|
|
30
|
+
is_draft: bool
|
|
31
|
+
is_prerelease: bool
|
|
32
|
+
|
|
33
|
+
@classmethod
|
|
34
|
+
def from_rest(cls, data: dict) -> Release:
|
|
35
|
+
published_or_created = data.get("published_at") or data.get("created_at")
|
|
36
|
+
if not published_or_created:
|
|
37
|
+
raise exceptions.GitHubAPIError(
|
|
38
|
+
f"GitHub API error release has no publication date:\n{data!r}"
|
|
39
|
+
)
|
|
40
|
+
return cls(
|
|
41
|
+
name=data["name"],
|
|
42
|
+
description=data["body"],
|
|
43
|
+
url=data["html_url"],
|
|
44
|
+
tag_name=data["tag_name"],
|
|
45
|
+
published_at=datetime.date.fromisoformat(published_or_created[:10]),
|
|
46
|
+
is_draft=data["draft"],
|
|
47
|
+
is_prerelease=data["prerelease"],
|
|
48
|
+
)
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def extract_releases(
|
|
52
|
+
github_params: urls.GitHubParams,
|
|
53
|
+
token: str | None,
|
|
54
|
+
retries: int,
|
|
55
|
+
) -> Sequence[Release]:
|
|
56
|
+
page = 1
|
|
57
|
+
releases: list[Release] = []
|
|
58
|
+
while True:
|
|
59
|
+
result = github_call(
|
|
60
|
+
url=github_params.releases_api_url,
|
|
61
|
+
token=token,
|
|
62
|
+
params={"per_page": 100, "page": page},
|
|
63
|
+
retries=retries,
|
|
64
|
+
)
|
|
65
|
+
if not result:
|
|
66
|
+
break
|
|
67
|
+
try:
|
|
68
|
+
releases.extend(Release.from_rest(r) for r in result)
|
|
69
|
+
except (KeyError, TypeError) as exc:
|
|
70
|
+
raise exceptions.GitHubAPIError(
|
|
71
|
+
f"GitHub API error unexpected format:\n{result!r}"
|
|
72
|
+
) from exc
|
|
73
|
+
page += 1
|
|
74
|
+
|
|
75
|
+
# Sort by publication date descending
|
|
76
|
+
return sorted(
|
|
77
|
+
releases,
|
|
78
|
+
key=lambda r: r.published_at,
|
|
79
|
+
reverse=True,
|
|
80
|
+
)
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def github_call(
|
|
84
|
+
url: str,
|
|
85
|
+
token: str | None,
|
|
86
|
+
params: dict[str, int],
|
|
87
|
+
retries: int,
|
|
88
|
+
sleep: Callable[[float], None] = nap.sleep,
|
|
89
|
+
) -> list[dict]:
|
|
90
|
+
headers = {
|
|
91
|
+
"Accept": "application/vnd.github+json",
|
|
92
|
+
}
|
|
93
|
+
if token:
|
|
94
|
+
headers["Authorization"] = f"token {token}"
|
|
95
|
+
|
|
96
|
+
response: httpx.Response | None = None
|
|
97
|
+
total_attempts = max(1, retries + 1)
|
|
98
|
+
try:
|
|
99
|
+
for attempt in Retrying(
|
|
100
|
+
stop=stop_after_attempt(total_attempts),
|
|
101
|
+
retry=retry_if_exception_type(GitHubRateLimitError),
|
|
102
|
+
wait=wait_exponential(multiplier=5, min=5),
|
|
103
|
+
sleep=sleep,
|
|
104
|
+
reraise=True,
|
|
105
|
+
):
|
|
106
|
+
with attempt:
|
|
107
|
+
try:
|
|
108
|
+
response = httpx.get(
|
|
109
|
+
url,
|
|
110
|
+
params=params,
|
|
111
|
+
headers=headers,
|
|
112
|
+
).raise_for_status()
|
|
113
|
+
except httpx.HTTPStatusError as exc:
|
|
114
|
+
if exc.response.status_code == 429:
|
|
115
|
+
raise GitHubRateLimitError(exc.response.text) from exc
|
|
116
|
+
raise
|
|
117
|
+
|
|
118
|
+
except httpx.HTTPStatusError as exc:
|
|
119
|
+
if exc.response.status_code == 401:
|
|
120
|
+
raise exceptions.GitHubAPIError(
|
|
121
|
+
"GitHub API authentication failed (401 Unauthorized)."
|
|
122
|
+
) from exc
|
|
123
|
+
raise exceptions.GitHubAPIError(
|
|
124
|
+
f"Unexpected GitHub API error status code: {exc.response.status_code}\n"
|
|
125
|
+
f"{exc.response.text}"
|
|
126
|
+
) from exc
|
|
127
|
+
except GitHubRateLimitError as exc:
|
|
128
|
+
raise exceptions.GitHubAPIError(
|
|
129
|
+
f"GitHub API rate limited (429) after {retries} retries."
|
|
130
|
+
) from exc
|
|
131
|
+
except httpx.HTTPError as exc:
|
|
132
|
+
raise exceptions.GitHubAPIError(
|
|
133
|
+
"Could not retrieve changelog from github: " + str(exc)
|
|
134
|
+
) from exc
|
|
135
|
+
|
|
136
|
+
if response is None:
|
|
137
|
+
raise NotImplementedError("Unreachable: retry loop completed without response")
|
|
138
|
+
|
|
139
|
+
response_payload = response.json()
|
|
140
|
+
if not isinstance(response_payload, list):
|
|
141
|
+
raise exceptions.GitHubAPIError(
|
|
142
|
+
f"GitHub API error unexpected format:\n{response_payload!r}"
|
|
143
|
+
)
|
|
144
|
+
return response_payload
|
{sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/sphinx_github_changelog/setup.py
RENAMED
|
@@ -1,7 +1,6 @@
|
|
|
1
1
|
from __future__ import annotations
|
|
2
2
|
|
|
3
3
|
import importlib.metadata
|
|
4
|
-
import os
|
|
5
4
|
|
|
6
5
|
from . import changelog, config
|
|
7
6
|
|
|
@@ -11,11 +10,10 @@ def version() -> str:
|
|
|
11
10
|
|
|
12
11
|
|
|
13
12
|
def setup(app):
|
|
14
|
-
for
|
|
15
|
-
option_name = f"{config.ChangelogConfig.prefix}_{name}"
|
|
13
|
+
for option_name, default in config.ChangelogConfig.get_config_defaults():
|
|
16
14
|
app.add_config_value(
|
|
17
15
|
name=option_name,
|
|
18
|
-
default=
|
|
16
|
+
default=default,
|
|
19
17
|
rebuild="html",
|
|
20
18
|
)
|
|
21
19
|
|
{sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/sphinx_github_changelog/urls.py
RENAMED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
"""
|
|
2
2
|
Utilities for working with git remotes and GitHub URLs.
|
|
3
3
|
|
|
4
|
-
Includes functions to parse remote URLs and derive
|
|
4
|
+
Includes functions to parse remote URLs and derive API endpoints.
|
|
5
5
|
"""
|
|
6
6
|
|
|
7
7
|
from __future__ import annotations
|
|
@@ -78,10 +78,14 @@ class GitHubParams:
|
|
|
78
78
|
return f"https://{self.hostname}/{self.owner}/{self.repo}"
|
|
79
79
|
|
|
80
80
|
@property
|
|
81
|
-
def
|
|
81
|
+
def rest_api_url(self) -> str:
|
|
82
82
|
if self.is_github_com:
|
|
83
|
-
return "https://api.github.com
|
|
84
|
-
return f"https://{self.hostname}/api/
|
|
83
|
+
return "https://api.github.com"
|
|
84
|
+
return f"https://{self.hostname}/api/v3"
|
|
85
|
+
|
|
86
|
+
@property
|
|
87
|
+
def releases_api_url(self) -> str:
|
|
88
|
+
return f"{self.rest_api_url}/repos/{self.owner}/{self.repo}/releases"
|
|
85
89
|
|
|
86
90
|
|
|
87
91
|
def extract_github_params(
|