sphinx-github-changelog 2.2.0__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.
Files changed (60) hide show
  1. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/.github/renovate.json5 +1 -0
  2. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/.github/workflows/ci.yml +9 -1
  3. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/.pre-commit-config.yaml +1 -0
  4. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/CONTRIBUTING.rst +29 -2
  5. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/PKG-INFO +19 -14
  6. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/README.rst +17 -13
  7. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/pyproject.toml +4 -1
  8. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/sphinx_github_changelog/changelog.py +17 -9
  9. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/sphinx_github_changelog/config.py +13 -4
  10. sphinx_github_changelog-2.3.0/sphinx_github_changelog/github_releases.py +144 -0
  11. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/sphinx_github_changelog/urls.py +8 -4
  12. sphinx_github_changelog-2.3.0/tests/acceptance/cassettes/test_all/test_build.yaml +176 -0
  13. sphinx_github_changelog-2.3.0/tests/acceptance/cassettes/test_all/test_build_404.yaml +69 -0
  14. sphinx_github_changelog-2.3.0/tests/acceptance/changelog.html +272 -0
  15. sphinx_github_changelog-2.3.0/tests/acceptance/test_all.py +61 -0
  16. sphinx_github_changelog-2.3.0/tests/conftest.py +103 -0
  17. {sphinx_github_changelog-2.2.0/tests/roots/test-error → sphinx_github_changelog-2.3.0/tests/roots/test-404}/conf.py +0 -2
  18. sphinx_github_changelog-2.3.0/tests/roots/test-404/index.rst +4 -0
  19. sphinx_github_changelog-2.3.0/tests/roots/test-all/conf.py +5 -0
  20. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/tests/roots/test-all/index.rst +1 -1
  21. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/tests/unit/test_changelog.py +21 -4
  22. sphinx_github_changelog-2.3.0/tests/unit/test_config.py +40 -0
  23. sphinx_github_changelog-2.3.0/tests/unit/test_github_releases.py +236 -0
  24. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/tests/unit/test_urls.py +9 -4
  25. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/uv.lock +171 -0
  26. sphinx_github_changelog-2.2.0/sphinx_github_changelog/github_releases.py +0 -95
  27. sphinx_github_changelog-2.2.0/tests/acceptance/changelog.html +0 -71
  28. sphinx_github_changelog-2.2.0/tests/acceptance/test_all.py +0 -109
  29. sphinx_github_changelog-2.2.0/tests/conftest.py +0 -54
  30. sphinx_github_changelog-2.2.0/tests/unit/test_github_releases.py +0 -115
  31. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/.editorconfig +0 -0
  32. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/.github/CODEOWNERS +0 -0
  33. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/.github/PULL_REQUEST_TEMPLATE.md +0 -0
  34. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/.github/release.yml +0 -0
  35. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/.github/workflows/autofix.yml +0 -0
  36. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/.github/workflows/coverage-comment.yml +0 -0
  37. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/.gitignore +0 -0
  38. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/.readthedocs.yml +0 -0
  39. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/CHANGELOG.rst +0 -0
  40. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/CODE_OF_CONDUCT.rst +0 -0
  41. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/LICENSE +0 -0
  42. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/docs/Makefile +0 -0
  43. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/docs/conduct.rst +0 -0
  44. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/docs/conf.py +0 -0
  45. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/docs/contributing.rst +0 -0
  46. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/docs/index.rst +0 -0
  47. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/scripts/README.md +0 -0
  48. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/scripts/docs +0 -0
  49. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/scripts/lint +0 -0
  50. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/scripts/tests +0 -0
  51. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/sphinx_github_changelog/__init__.py +0 -0
  52. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/sphinx_github_changelog/credentials.py +0 -0
  53. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/sphinx_github_changelog/exceptions.py +0 -0
  54. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/sphinx_github_changelog/setup.py +0 -0
  55. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/tests/__init__.py +0 -0
  56. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/tests/acceptance/__init__.py +0 -0
  57. {sphinx_github_changelog-2.2.0/tests/roots/test-all → sphinx_github_changelog-2.3.0/tests/roots/test-error}/conf.py +0 -0
  58. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/tests/roots/test-error/index.rst +0 -0
  59. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/tests/unit/__init__.py +0 -0
  60. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.0}/tests/unit/test_git.py +0 -0
@@ -2,6 +2,7 @@
2
2
  extends: ["config:recommended", ":enablePreCommit"],
3
3
  schedule: ["before 4am on Saturday"],
4
4
  labels: ["PR type: dependencies 🤖"],
5
+ minimumReleaseAge: "5 days",
5
6
  lockFileMaintenance: {
6
7
  enabled: true,
7
8
  automerge: true,
@@ -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'
@@ -23,6 +23,7 @@ repos:
23
23
  - id: end-of-file-fixer
24
24
  - id: trailing-whitespace
25
25
  - id: mixed-line-ending
26
+ - id: no-commit-to-branch
26
27
 
27
28
  - repo: https://github.com/astral-sh/ruff-pre-commit
28
29
  rev: v0.15.14
@@ -29,7 +29,10 @@ I want a venv to play locally
29
29
 
30
30
  $ uv sync
31
31
 
32
- Use at ``uv sync --python=3.x`` if you want to work on a specific Python version.
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.2.0
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 GraphQL API and GitHub root URL are derived from this URL.
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 GraphQL API to retrieve the changelog. This
169
- requires authentication using a GitHub API token.
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 (e.g. for ReadTheDocs, at least for the `time
193
- being`__), you'll need a personal access token. If the repository is public, the token
194
- doesn't need any special access (you can uncheck everything). For private and internal
195
- repositories, the token must have ``repo`` scope (classic tokens) or ``contents: read``
196
- access (fine-grained tokens).
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
@@ -221,13 +226,13 @@ All options can also be set via environment variables of the same name in upperc
221
226
  * - ``sphinx_github_changelog_root_repo``
222
227
  - ``None``
223
228
  - Root URL to the repository. Usually detected automatically.
224
- * - ``sphinx_github_changelog_graphql_url``
225
- - ``None``
226
- - URL to GraphQL API. Usually detected automatically.
227
229
  * - ``sphinx_github_changelog_include_prereleases``
228
230
  - ``True``
229
231
  - Whether to include pre-releases in the changelog. Set to ``False``
230
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.
231
236
 
232
237
  .. _ReadTheDocs: https://readthedocs.org/
233
238
 
@@ -127,7 +127,7 @@ git remotes in this order:
127
127
  1. ``upstream`` remote
128
128
  2. ``origin`` remote
129
129
 
130
- The GraphQL API and GitHub root URL are derived from this URL.
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 GraphQL API to retrieve the changelog. This
142
- requires authentication using a GitHub API token.
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 (e.g. for ReadTheDocs, at least for the `time
166
- being`__), you'll need a personal access token. If the repository is public, the token
167
- doesn't need any special access (you can uncheck everything). For private and internal
168
- repositories, the token must have ``repo`` scope (classic tokens) or ``contents: read``
169
- access (fine-grained tokens).
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
@@ -194,13 +198,13 @@ All options can also be set via environment variables of the same name in upperc
194
198
  * - ``sphinx_github_changelog_root_repo``
195
199
  - ``None``
196
200
  - Root URL to the repository. Usually detected automatically.
197
- * - ``sphinx_github_changelog_graphql_url``
198
- - ``None``
199
- - URL to GraphQL API. Usually detected automatically.
200
201
  * - ``sphinx_github_changelog_include_prereleases``
201
202
  - ``True``
202
203
  - Whether to include pre-releases in the changelog. Set to ``False``
203
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.
204
208
 
205
209
  .. _ReadTheDocs: https://readthedocs.org/
206
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"]
@@ -48,19 +48,26 @@ 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
- return no_token(changelog_url=options.changelog_url)
59
+ token = None
58
60
 
59
- releases = github_releases.extract_releases(
60
- github_params=github_params,
61
- token=token,
62
- graphql_url=config.graphql_url,
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
 
@@ -77,8 +84,9 @@ def compute_changelog(
77
84
  def no_token(changelog_url: str | None) -> list[nodes.Node]:
78
85
  par = nodes.paragraph()
79
86
  par += nodes.Text(
80
- "Changelog was not built because no GitHub authentication token was found. "
81
- "An access token can be provided using the "
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 "
82
90
  )
83
91
  par += nodes.literal("", "SPHINX_GITHUB_CHANGELOG_TOKEN")
84
92
  par += nodes.Text(" environment variable or the ")
@@ -25,22 +25,31 @@ class ChangelogDirectiveOptions:
25
25
  class ChangelogConfig:
26
26
  token: str | None = None
27
27
  root_repo: str | None = None
28
- graphql_url: str | None = None
29
28
  include_prereleases: bool = True
29
+ retries: int = 3
30
30
 
31
31
  prefix: ClassVar[str] = "sphinx_github_changelog"
32
32
 
33
33
  @classmethod
34
- def get_config_defaults(cls) -> Iterator[tuple[str, str | bool | None]]:
34
+ def get_config_defaults(cls) -> Iterator[tuple[str, str | bool | int | None]]:
35
35
  for field in dataclasses.fields(cls):
36
36
  option_name = f"{cls.prefix}_{field.name}"
37
37
  env_value = os.environ.get(option_name.upper())
38
38
  if field.type == "bool":
39
- default: str | bool | None = (
39
+ default: str | bool | int | None = (
40
40
  env_value.lower() not in ("0", "false", "no")
41
41
  if env_value
42
42
  else bool(field.default)
43
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
+ )
44
53
  else:
45
54
  default = env_value
46
55
  yield option_name, default
@@ -50,6 +59,6 @@ class ChangelogConfig:
50
59
  return cls(
51
60
  token=sphinx_config.sphinx_github_changelog_token,
52
61
  root_repo=sphinx_config.sphinx_github_changelog_root_repo,
53
- graphql_url=sphinx_config.sphinx_github_changelog_graphql_url,
54
62
  include_prereleases=sphinx_config.sphinx_github_changelog_include_prereleases,
63
+ retries=sphinx_config.sphinx_github_changelog_retries,
55
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
@@ -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 GraphQL endpoints.
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 graphql_url(self) -> str:
81
+ def rest_api_url(self) -> str:
82
82
  if self.is_github_com:
83
- return "https://api.github.com/graphql"
84
- return f"https://{self.hostname}/api/graphql"
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(