issue_role.py

"""Support for referencing issues in the tracker."""

from __future__ importannotations

fromtypingimportTYPE_CHECKING

fromdocutilsimportnodes
fromsphinx.util.docutilsimportSphinxRole

ifTYPE_CHECKING:
fromdocutils.nodesimportElement
fromsphinx.applicationimportSphinx
fromsphinx.util.typingimportExtensionMetadata


classBPOIssue(SphinxRole):
ISSUE_URI="https://bugs.python.org/issue?@action=redirect&bpo={0}"

defrun(self) ->tuple[list[Element], list[nodes.system_message]]:
issue=self.text

# sanity check: there are no bpo issues within these two values
if47_261<int(issue) <400_000:
msg=self.inliner.reporter.error(
f"The BPO ID {issue!r} seems too high. "
"Use :gh:`...` for GitHub IDs.",
line=self.lineno,
 )
prb=self.inliner.problematic(self.rawtext, self.rawtext, msg)
return [prb], [msg]

issue_url=self.ISSUE_URI.format(issue)
refnode=nodes.reference(issue, f"bpo-{issue}", refuri=issue_url)
self.set_source_info(refnode)
return [refnode], []


classGitHubIssue(SphinxRole):
ISSUE_URI="https://github.com/python/cpython/issues/{0}"

defrun(self) ->tuple[list[Element], list[nodes.system_message]]:
issue=self.text

# sanity check: all GitHub issues have ID >= 32426
# even though some of them are also valid BPO IDs
ifint(issue) <32_426:
msg=self.inliner.reporter.error(
f"The GitHub ID {issue!r} seems too low. "
"Use :issue:`...` for BPO IDs.",
line=self.lineno,
 )
prb=self.inliner.problematic(self.rawtext, self.rawtext, msg)
return [prb], [msg]

issue_url=self.ISSUE_URI.format(issue)
refnode=nodes.reference(issue, f"gh-{issue}", refuri=issue_url)
self.set_source_info(refnode)
return [refnode], []


defsetup(app: Sphinx) ->ExtensionMetadata:
app.add_role("issue", BPOIssue())
app.add_role("gh", GitHubIssue())

return {
"version": "1.0",
"parallel_read_safe": True,
"parallel_write_safe": True,
 }