Sphinx 7.2.6__py3-none-any.whl → 7.3.0__py3-none-any.whl

sphinx/builders/linkcheck.py

@@ -7,6 +7,7 @@ import json
 import re
 import socket
 import time
+import warnings
 from html.parser import HTMLParser
 from os import path
 from queue import PriorityQueue, Queue
@@ -16,29 +17,26 @@ from urllib.parse import unquote, urlparse, urlsplit, urlunparse
 
 from docutils import nodes
 from requests.exceptions import ConnectionError, HTTPError, SSLError, TooManyRedirects
+from requests.exceptions import Timeout as RequestTimeout
 
 from sphinx.builders.dummy import DummyBuilder
+from sphinx.deprecation import RemovedInSphinx80Warning
 from sphinx.locale import __
 from sphinx.transforms.post_transforms import SphinxPostTransform
 from sphinx.util import encode_uri, logging, requests
-from sphinx.util.console import (  # type: ignore[attr-defined]
-    darkgray,
-    darkgreen,
-    purple,
-    red,
-    turquoise,
-)
+from sphinx.util.console import darkgray, darkgreen, purple, red, turquoise
 from sphinx.util.http_date import rfc1123_to_epoch
 from sphinx.util.nodes import get_node_line
 
 if TYPE_CHECKING:
-    from collections.abc import Generator, Iterator
+    from collections.abc import Iterator
     from typing import Any, Callable
 
     from requests import Response
 
     from sphinx.application import Sphinx
     from sphinx.config import Config
+    from sphinx.util.typing import ExtensionMetadata
 
 logger = logging.getLogger(__name__)
 
@@ -56,16 +54,37 @@ class CheckExternalLinksBuilder(DummyBuilder):
     """
     Checks for broken external links.
     """
+
     name = 'linkcheck'
     epilog = __('Look for any errors in the above output or in '
                 '%(outdir)s/output.txt')
 
     def init(self) -> None:
         self.broken_hyperlinks = 0
+        self.timed_out_hyperlinks = 0
         self.hyperlinks: dict[str, Hyperlink] = {}
         # set a timeout for non-responding servers
         socket.setdefaulttimeout(5.0)
 
+        if not self.config.linkcheck_allow_unauthorized:
+            deprecation_msg = (
+                "The default value for 'linkcheck_allow_unauthorized' will change "
+                "from `True` in Sphinx 7.3+ to `False`, meaning that HTTP 401 "
+                "unauthorized responses will be reported as broken by default. "
+                "See https://github.com/sphinx-doc/sphinx/issues/11433 for details."
+            )
+            warnings.warn(deprecation_msg, RemovedInSphinx80Warning, stacklevel=1)
+
+        if self.config.linkcheck_report_timeouts_as_broken:
+            deprecation_msg = (
+                "The default value for 'linkcheck_report_timeouts_as_broken' will change "
+                'to False in Sphinx 8, meaning that request timeouts '
+                "will be reported with a new 'timeout' status, instead of as 'broken'. "
+                'This is intended to provide more detail as to the failure mode. '
+                'See https://github.com/sphinx-doc/sphinx/issues/11868 for details.'
+            )
+            warnings.warn(deprecation_msg, RemovedInSphinx80Warning, stacklevel=1)
+
     def finish(self) -> None:
         checker = HyperlinkAvailabilityChecker(self.config)
         logger.info('')
@@ -77,7 +96,7 @@ class CheckExternalLinksBuilder(DummyBuilder):
             for result in checker.check(self.hyperlinks):
                 self.process_result(result)
 
-        if self.broken_hyperlinks:
+        if self.broken_hyperlinks or self.timed_out_hyperlinks:
             self.app.statuscode = 1
 
     def process_result(self, result: CheckResult) -> None:
@@ -104,6 +123,15 @@ class CheckExternalLinksBuilder(DummyBuilder):
             self.write_entry('local', result.docname, filename, result.lineno, result.uri)
         elif result.status == 'working':
             logger.info(darkgreen('ok        ') + result.uri + result.message)
+        elif result.status == 'timeout':
+            if self.app.quiet or self.app.warningiserror:
+                logger.warning('timeout   ' + result.uri + result.message,
+                               location=(result.docname, result.lineno))
+            else:
+                logger.info(red('timeout   ') + result.uri + red(' - ' + result.message))
+            self.write_entry('timeout', result.docname, filename, result.lineno,
+                             result.uri + ': ' + result.message)
+            self.timed_out_hyperlinks += 1
         elif result.status == 'broken':
             if self.app.quiet or self.app.warningiserror:
                 logger.warning(__('broken link: %s (%s)'), result.uri, result.message,
@@ -206,7 +234,7 @@ class HyperlinkAvailabilityChecker:
         self.to_ignore: list[re.Pattern[str]] = list(map(re.compile,
                                                          self.config.linkcheck_ignore))
 
-    def check(self, hyperlinks: dict[str, Hyperlink]) -> Generator[CheckResult, None, None]:
+    def check(self, hyperlinks: dict[str, Hyperlink]) -> Iterator[CheckResult]:
         self.invoke_threads()
 
         total_links = 0
@@ -283,6 +311,11 @@ class HyperlinkAvailabilityCheckWorker(Thread):
         self.allowed_redirects = config.linkcheck_allowed_redirects
         self.retries: int = config.linkcheck_retries
         self.rate_limit_timeout = config.linkcheck_rate_limit_timeout
+        self._allow_unauthorized = config.linkcheck_allow_unauthorized
+        if config.linkcheck_report_timeouts_as_broken:
+            self._timeout_status = 'broken'
+        else:
+            self._timeout_status = 'timeout'
 
         self.user_agent = config.user_agent
         self.tls_verify = config.tls_verify
@@ -384,7 +417,7 @@ class HyperlinkAvailabilityCheckWorker(Thread):
             req_url = encode_uri(req_url)
 
         # Get auth info, if any
-        for pattern, auth_info in self.auth:  # noqa: B007 (false positive)
+        for pattern, auth_info in self.auth:  # NoQA: B007 (false positive)
             if pattern.match(uri):
                 break
         else:
@@ -424,6 +457,9 @@ class HyperlinkAvailabilityCheckWorker(Thread):
                 del response
                 break
 
+            except RequestTimeout as err:
+                return self._timeout_status, str(err), 0
+
             except SSLError as err:
                 # SSL failure; report that the link is broken.
                 return 'broken', str(err), 0
@@ -437,9 +473,31 @@ class HyperlinkAvailabilityCheckWorker(Thread):
             except HTTPError as err:
                 error_message = str(err)
 
-                # Unauthorised: the reference probably exists
+                # Unauthorized: the client did not provide required credentials
                 if status_code == 401:
-                    return 'working', 'unauthorized', 0
+                    if self._allow_unauthorized:
+                        deprecation_msg = (
+                            "\n---\n"
+                            "The linkcheck builder encountered an HTTP 401 "
+                            "(unauthorized) response, and will report it as "
+                            "'working' in this version of Sphinx to maintain "
+                            "backwards-compatibility."
+                            "\n"
+                            "This logic will change in Sphinx 8.0 which will "
+                            "report the hyperlink as 'broken'."
+                            "\n"
+                            "To explicitly continue treating unauthorized "
+                            "hyperlink responses as 'working', set the "
+                            "'linkcheck_allow_unauthorized' config option to "
+                            "``True``."
+                            "\n"
+                            "See https://github.com/sphinx-doc/sphinx/issues/11433 "
+                            "for details."
+                            "\n---"
+                        )
+                        warnings.warn(deprecation_msg, RemovedInSphinx80Warning, stacklevel=1)
+                    status = 'working' if self._allow_unauthorized else 'broken'
+                    return status, 'unauthorized', 0
 
                 # Rate limiting; back-off if allowed, or report failure otherwise
                 if status_code == 429:
@@ -534,7 +592,6 @@ def _get_request_headers(
 
 def contains_anchor(response: Response, anchor: str) -> bool:
     """Determine if an anchor is contained within an HTTP response."""
-
     parser = AnchorCheckParser(unquote(anchor))
     # Read file in chunks. If we find a matching anchor, we break
     # the loop early in hopes not to have to download the whole thing.
@@ -607,24 +664,26 @@ def compile_linkcheck_allowed_redirects(app: Sphinx, config: Config) -> None:
             app.config.linkcheck_allowed_redirects.pop(url)
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_builder(CheckExternalLinksBuilder)
     app.add_post_transform(HyperlinkCollector)
 
-    app.add_config_value('linkcheck_ignore', [], False)
-    app.add_config_value('linkcheck_exclude_documents', [], False)
-    app.add_config_value('linkcheck_allowed_redirects', {}, False)
-    app.add_config_value('linkcheck_auth', [], False)
-    app.add_config_value('linkcheck_request_headers', {}, False)
-    app.add_config_value('linkcheck_retries', 1, False)
-    app.add_config_value('linkcheck_timeout', None, False, [int, float])
-    app.add_config_value('linkcheck_workers', 5, False)
-    app.add_config_value('linkcheck_anchors', True, False)
+    app.add_config_value('linkcheck_ignore', [], '')
+    app.add_config_value('linkcheck_exclude_documents', [], '')
+    app.add_config_value('linkcheck_allowed_redirects', {}, '')
+    app.add_config_value('linkcheck_auth', [], '')
+    app.add_config_value('linkcheck_request_headers', {}, '')
+    app.add_config_value('linkcheck_retries', 1, '')
+    app.add_config_value('linkcheck_timeout', 30, '', (int, float))
+    app.add_config_value('linkcheck_workers', 5, '')
+    app.add_config_value('linkcheck_anchors', True, '')
     # Anchors starting with ! are ignored since they are
     # commonly used for dynamic pages
-    app.add_config_value('linkcheck_anchors_ignore', ['^!'], False)
-    app.add_config_value('linkcheck_anchors_ignore_for_url', (), False, (tuple, list))
-    app.add_config_value('linkcheck_rate_limit_timeout', 300.0, False)
+    app.add_config_value('linkcheck_anchors_ignore', ['^!'], '')
+    app.add_config_value('linkcheck_anchors_ignore_for_url', (), '', (tuple, list))
+    app.add_config_value('linkcheck_rate_limit_timeout', 300.0, '')
+    app.add_config_value('linkcheck_allow_unauthorized', True, '')
+    app.add_config_value('linkcheck_report_timeouts_as_broken', True, '', bool)
 
     app.add_event('linkcheck-process-uri')
 

sphinx/builders/manpage.py

@@ -13,7 +13,7 @@ from sphinx import addnodes
 from sphinx.builders import Builder
 from sphinx.locale import __
 from sphinx.util import logging
-from sphinx.util.console import darkgreen  # type: ignore[attr-defined]
+from sphinx.util.console import darkgreen
 from sphinx.util.display import progress_message
 from sphinx.util.nodes import inline_all_toctrees
 from sphinx.util.osutil import ensuredir, make_filename_from_project
@@ -22,6 +22,7 @@ from sphinx.writers.manpage import ManualPageTranslator, ManualPageWriter
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
     from sphinx.config import Config
+    from sphinx.util.typing import ExtensionMetadata
 
 logger = logging.getLogger(__name__)
 
@@ -30,6 +31,7 @@ class ManualPageBuilder(Builder):
     """
     Builds groff output in manual page format.
     """
+
     name = 'man'
     format = 'man'
     epilog = __('The manual pages are in %(outdir)s.')
@@ -107,18 +109,18 @@ class ManualPageBuilder(Builder):
 
 
 def default_man_pages(config: Config) -> list[tuple[str, str, str, list[str], int]]:
-    """ Better default man_pages settings. """
+    """Better default man_pages settings."""
     filename = make_filename_from_project(config.project)
     return [(config.root_doc, filename, f'{config.project} {config.release}',
              [config.author], 1)]
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_builder(ManualPageBuilder)
 
-    app.add_config_value('man_pages', default_man_pages, False)
-    app.add_config_value('man_show_urls', False, False)
-    app.add_config_value('man_make_section_directory', False, False)
+    app.add_config_value('man_pages', default_man_pages, '')
+    app.add_config_value('man_show_urls', False, '')
+    app.add_config_value('man_make_section_directory', False, '')
 
     return {
         'version': 'builtin',

sphinx/builders/singlehtml.py

@@ -11,7 +11,7 @@ from sphinx.builders.html import StandaloneHTMLBuilder
 from sphinx.environment.adapters.toctree import global_toctree_for_doc
 from sphinx.locale import __
 from sphinx.util import logging
-from sphinx.util.console import darkgreen  # type: ignore[attr-defined]
+from sphinx.util.console import darkgreen
 from sphinx.util.display import progress_message
 from sphinx.util.nodes import inline_all_toctrees
 
@@ -19,6 +19,7 @@ if TYPE_CHECKING:
     from docutils.nodes import Node
 
     from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
 
 logger = logging.getLogger(__name__)
 
@@ -28,6 +29,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
     A StandaloneHTMLBuilder subclass that puts the whole document tree on one
     HTML page.
     """
+
     name = 'singlehtml'
     epilog = __('The HTML page is in %(outdir)s.')
 
@@ -39,8 +41,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
     def get_target_uri(self, docname: str, typ: str | None = None) -> str:
         if docname in self.env.all_docs:
             # all references are on the same page...
-            return self.config.root_doc + self.out_suffix + \
-                '#document-' + docname
+            return '#document-' + docname
         else:
             # chances are this is a html_additional_page
             return docname + self.out_suffix
@@ -189,7 +190,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
             self.handle_page('opensearch', {}, 'opensearch.xml', outfilename=fn)
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.setup_extension('sphinx.builders.html')
 
     app.add_builder(SingleFileHTMLBuilder)

sphinx/builders/texinfo.py

@@ -17,7 +17,7 @@ from sphinx.environment.adapters.asset import ImageAdapter
 from sphinx.errors import NoUri
 from sphinx.locale import _, __
 from sphinx.util import logging
-from sphinx.util.console import darkgreen  # type: ignore[attr-defined]
+from sphinx.util.console import darkgreen
 from sphinx.util.display import progress_message, status_iterator
 from sphinx.util.docutils import new_document
 from sphinx.util.fileutil import copy_asset_file
@@ -32,6 +32,7 @@ if TYPE_CHECKING:
 
     from sphinx.application import Sphinx
     from sphinx.config import Config
+    from sphinx.util.typing import ExtensionMetadata
 
 logger = logging.getLogger(__name__)
 template_dir = os.path.join(package_dir, 'templates', 'texinfo')
@@ -41,6 +42,7 @@ class TexinfoBuilder(Builder):
     """
     Builds Texinfo output to create Info documentation.
     """
+
     name = 'texinfo'
     format = 'texinfo'
     epilog = __('The Texinfo files are in %(outdir)s.')
@@ -133,7 +135,7 @@ class TexinfoBuilder(Builder):
     def assemble_doctree(
         self, indexfile: str, toctree_only: bool, appendices: list[str],
     ) -> nodes.document:
-        self.docnames = set([indexfile] + appendices)
+        self.docnames = {indexfile, *appendices}
         logger.info(darkgreen(indexfile) + " ", nonl=True)
         tree = self.env.get_doctree(indexfile)
         tree['docname'] = indexfile
@@ -165,9 +167,11 @@ class TexinfoBuilder(Builder):
             newnodes: list[Node] = [nodes.emphasis(sectname, sectname)]
             for subdir, title in self.titles:
                 if docname.startswith(subdir):
-                    newnodes.append(nodes.Text(_(' (in ')))
-                    newnodes.append(nodes.emphasis(title, title))
-                    newnodes.append(nodes.Text(')'))
+                    newnodes.extend((
+                        nodes.Text(_(' (in ')),
+                        nodes.emphasis(title, title),
+                        nodes.Text(')'),
+                    ))
                     break
             else:
                 pass
@@ -205,22 +209,22 @@ class TexinfoBuilder(Builder):
 def default_texinfo_documents(
     config: Config,
 ) -> list[tuple[str, str, str, str, str, str, str]]:
-    """ Better default texinfo_documents settings. """
+    """Better default texinfo_documents settings."""
     filename = make_filename_from_project(config.project)
     return [(config.root_doc, filename, config.project, config.author, filename,
              'One line description of project', 'Miscellaneous')]
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_builder(TexinfoBuilder)
 
-    app.add_config_value('texinfo_documents', default_texinfo_documents, False)
-    app.add_config_value('texinfo_appendices', [], False)
-    app.add_config_value('texinfo_elements', {}, False)
-    app.add_config_value('texinfo_domain_indices', True, False, [list])
-    app.add_config_value('texinfo_show_urls', 'footnote', False)
-    app.add_config_value('texinfo_no_detailmenu', False, False)
-    app.add_config_value('texinfo_cross_references', True, False)
+    app.add_config_value('texinfo_documents', default_texinfo_documents, '')
+    app.add_config_value('texinfo_appendices', [], '')
+    app.add_config_value('texinfo_elements', {}, '')
+    app.add_config_value('texinfo_domain_indices', True, '', list)
+    app.add_config_value('texinfo_show_urls', 'footnote', '')
+    app.add_config_value('texinfo_no_detailmenu', False, '')
+    app.add_config_value('texinfo_cross_references', True, '')
 
     return {
         'version': 'builtin',

sphinx/builders/text.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from os import path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from docutils.io import StringOutput
 
@@ -19,6 +19,7 @@ if TYPE_CHECKING:
     from docutils.nodes import Node
 
     from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
 
 logger = logging.getLogger(__name__)
 
@@ -79,7 +80,7 @@ class TextBuilder(Builder):
         pass
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_builder(TextBuilder)
 
     app.add_config_value('text_sectionchars', '*=-~"+`', 'env')

sphinx/builders/xml.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from os import path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from docutils import nodes
 from docutils.io import StringOutput
@@ -21,6 +21,7 @@ if TYPE_CHECKING:
     from docutils.nodes import Node
 
     from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
 
 logger = logging.getLogger(__name__)
 
@@ -29,6 +30,7 @@ class XMLBuilder(Builder):
     """
     Builds Docutils-native XML.
     """
+
     name = 'xml'
     format = 'xml'
     epilog = __('The XML files are in %(outdir)s.')
@@ -101,6 +103,7 @@ class PseudoXMLBuilder(XMLBuilder):
     """
     Builds pseudo-XML for display purposes.
     """
+
     name = 'pseudoxml'
     format = 'pseudoxml'
     epilog = __('The pseudo-XML files are in %(outdir)s.')
@@ -110,7 +113,7 @@ class PseudoXMLBuilder(XMLBuilder):
     _writer_class = PseudoXMLWriter
 
 
-def setup(app: Sphinx) -> dict[str, Any]:
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_builder(XMLBuilder)
     app.add_builder(PseudoXMLBuilder)