Skip to content

linkcheck: treat URI schemes as case-insensitive (RFC 3986) - #14599

Open
sudorm-rf0 wants to merge 1 commit into
sphinx-doc:masterfrom
sudorm-rf0:fix-linkcheck-uppercase-scheme-14541
Open

linkcheck: treat URI schemes as case-insensitive (RFC 3986)#14599
sudorm-rf0 wants to merge 1 commit into
sphinx-doc:masterfrom
sudorm-rf0:fix-linkcheck-uppercase-scheme-14541

Conversation

@sudorm-rf0

Copy link
Copy Markdown

Hi,

This fixes a linkcheck bug where URIs with an uppercase scheme (e.g. FTP://example.test/file) were reported as [broken], while the lowercase form ftp:// was correctly reported as [unchecked].

AI assistance disclosure (per the AI policy): I used an AI coding assistant to help produce the initial patch and the regression test. I have reviewed the diff, understand exactly what it does, and can explain it below. I am opening this PR myself after checking it.

What's going on / why I think this is the right fix

Per RFC 3986 §3.1, URI schemes are case-insensitive, so FTP:// and ftp:// are the same scheme. Sphinx's linkcheck decides whether a link is "external" (a non-HTTP scheme) with this regex in sphinx/builders/linkcheck.py:

uri_re = re.compile('([a-z]+:)?//')

Because the character class is [a-z] only, an uppercase scheme like FTP:// never matches, so linkcheck does not recognise it as an external link. It then falls through to the local-file existence check and reports [broken] for a URI that is actually a remote FTP link.

The fix is a one-liner: make the regex case-insensitive.

uri_re = re.compile('([a-z]+:)?//', re.IGNORECASE)

Now FTP://, SSH://, etc. are treated exactly like their lowercase forms and reported as [unchecked]. http:/https: links are unaffected (they are still checked normally), and nothing else in the matching logic changes.

How I verified it

  • Added a regression test tests/test_builders/test_build_linkcheck.py::test_linkcheck_uppercase_scheme_is_unchecked covering FTP://, ftp://, and SSH://. It reports broken on the unpatched code and unchecked with the fix.
  • pytest tests/test_builders/test_build_linkcheck.py → 51 passed, no regressions.
  • ruff check / ruff format --check clean on the changed files.

Fixes #14541.

…oc#14541)

Per RFC 3986, URI schemes are case-insensitive, but linkcheck used a case-sensitive regex ('([a-z]+:)?//') to detect non-HTTP schemes. Uppercase schemes such as 'FTP://' were not recognised as external links and were wrongly reported as [broken] instead of [unchecked]. Make the regex case-insensitive. Fixes sphinx-doc#14541.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

linkcheck reports uppercase-scheme URIs as broken

3 participants