Raise an error when local asset files contain a ?

Author: AA-Turner

sphinx/builders/html/__init__.py

@@ -1255,9 +1255,17 @@ def js_tag(js: JavaScript) -> str:
 
 
 def _file_checksum(outdir: str | os.PathLike[str], filename: str | os.PathLike[str]) -> str:
+    filename = os.fspath(filename)
     # Don't generate checksums for HTTP URIs
-    if '://' in str(filename):
+    if '://' in filename:
         return ''
+    # Some themes and extensions have used query strings
+    # for a similar asset checksum feature.
+    # As we cannot safely strip the query string,
+    # raise an error to the user.
+    if '?' in filename:
+        msg = f'Local asset file paths must not contain query strings: {filename!r}'
+        raise ThemeError(msg)
     try:
         # Ensure universal newline mode is used to avoid checksum differences
         with open(path.join(outdir, filename), encoding='utf-8') as f:

tests/test_build_html.py

@@ -11,8 +11,12 @@
 from html5lib import HTMLParser
 
 import sphinx.builders.html
-from sphinx.builders.html import validate_html_extra_path, validate_html_static_path
-from sphinx.errors import ConfigError
+from sphinx.builders.html import (
+    _file_checksum,
+    validate_html_extra_path,
+    validate_html_static_path,
+)
+from sphinx.errors import ConfigError, ThemeError
 from sphinx.testing.util import strip_escseq
 from sphinx.util.inventory import InventoryFile
 
@@ -1242,6 +1246,20 @@ def test_file_checksum(app):
     assert '<script src="https://example.com/script.js"></script>' in content
 
 
+def test_file_checksum_query_string():
+    with pytest.raises(ThemeError, match='Local asset file paths must not contain query strings'):
+        _file_checksum('', 'with_query_string.css?dead_parrots=1')
+
+    with pytest.raises(ThemeError, match='Local asset file paths must not contain query strings'):
+        _file_checksum('', 'with_query_string.js?dead_parrots=1')
+
+    with pytest.raises(ThemeError, match='Local asset file paths must not contain query strings'):
+        _file_checksum(Path.cwd(), '_static/with_query_string.css?dead_parrots=1')
+
+    with pytest.raises(ThemeError, match='Local asset file paths must not contain query strings'):
+        _file_checksum(Path.cwd(), '_static/with_query_string.js?dead_parrots=1')
+
+
 @pytest.mark.sphinx('html', testroot='html_assets')
 def test_javscript_loading_method(app):
     app.add_js_file('normal.js')