diff --git a/sphinx/builders/html/__init__.py b/sphinx/builders/html/__init__.py
index 8f5917a208..3e7a2b7fd1 100644
--- a/sphinx/builders/html/__init__.py
+++ b/sphinx/builders/html/__init__.py
@@ -26,7 +26,7 @@ from sphinx import __display_version__, package_dir
from sphinx import version_info as sphinx_version
from sphinx.application import Sphinx
from sphinx.builders import Builder
-from sphinx.builders.html._assets import _file_checksum
+from sphinx.builders.html._assets import _CascadingStyleSheet, _file_checksum, _JavaScript
from sphinx.config import ENUM, Config
from sphinx.domains import Domain, Index, IndexEntry
from sphinx.environment import BuildEnvironment
@@ -95,52 +95,6 @@ def convert_locale_to_language_tag(locale: str | None) -> str | None:
return None
-class Stylesheet(str):
- """A metadata of stylesheet.
-
- To keep compatibility with old themes, an instance of stylesheet behaves as
- its filename (str).
- """
-
- attributes: dict[str, str]
- filename: str
- priority: int
-
- def __new__(cls, filename: str, *args: str, priority: int = 500, **attributes: str,
- ) -> Stylesheet:
- self = str.__new__(cls, filename)
- self.filename = filename
- self.priority = priority
- self.attributes = attributes
- self.attributes.setdefault('rel', 'stylesheet')
- self.attributes.setdefault('type', 'text/css')
- if args: # old style arguments (rel, title)
- self.attributes['rel'] = args[0]
- self.attributes['title'] = args[1]
-
- return self
-
-
-class JavaScript(str):
- """A metadata of javascript file.
-
- To keep compatibility with old themes, an instance of javascript behaves as
- its filename (str).
- """
-
- attributes: dict[str, str]
- filename: str
- priority: int
-
- def __new__(cls, filename: str, priority: int = 500, **attributes: str) -> JavaScript:
- self = str.__new__(cls, filename)
- self.filename = filename
- self.priority = priority
- self.attributes = attributes
-
- return self
-
-
class BuildInfo:
"""buildinfo file manipulator.
@@ -228,10 +182,10 @@ class StandaloneHTMLBuilder(Builder):
super().__init__(app, env)
# CSS files
- self.css_files: list[Stylesheet] = []
+ self.css_files: list[_CascadingStyleSheet] = []
# JS files
- self.script_files: list[JavaScript] = []
+ self.script_files: list[_JavaScript] = []
# Cached Publisher for writing doctrees to HTML
reader = docutils.readers.doctree.Reader(parser_name='restructuredtext')
@@ -356,7 +310,7 @@ class StandaloneHTMLBuilder(Builder):
if '://' not in filename:
filename = posixpath.join('_static', filename)
- self.css_files.append(Stylesheet(filename, **kwargs))
+ self.css_files.append(_CascadingStyleSheet(filename, **kwargs))
def init_js_files(self) -> None:
self.script_files = []
@@ -378,7 +332,7 @@ class StandaloneHTMLBuilder(Builder):
if filename and '://' not in filename:
filename = posixpath.join('_static', filename)
- self.script_files.append(JavaScript(filename, **kwargs))
+ self.script_files.append(_JavaScript(filename, **kwargs))
@property
def math_renderer_name(self) -> str | None:
@@ -1203,7 +1157,7 @@ def setup_css_tag_helper(app: Sphinx, pagename: str, templatename: str,
"""
pathto = context['pathto']
- def css_tag(css: Stylesheet) -> str:
+ def css_tag(css: _CascadingStyleSheet) -> str:
attrs = []
for key in sorted(css.attributes):
value = css.attributes[key]
@@ -1226,10 +1180,10 @@ def setup_js_tag_helper(app: Sphinx, pagename: str, templatename: str,
"""
pathto = context['pathto']
- def js_tag(js: JavaScript) -> str:
+ def js_tag(js: _JavaScript) -> str:
attrs = []
body = ''
- if isinstance(js, JavaScript):
+ if isinstance(js, _JavaScript):
for key in sorted(js.attributes):
value = js.attributes[key]
if value is not None:
@@ -1413,3 +1367,21 @@ def setup(app: Sphinx) -> dict[str, Any]:
'parallel_read_safe': True,
'parallel_write_safe': True,
}
+
+
+# deprecated name -> (object to return, canonical path or empty string)
+_DEPRECATED_OBJECTS = {
+ 'Stylesheet': (_CascadingStyleSheet, 'sphinx.builders.html._assets._CascadingStyleSheet', (9, 0)), # NoQA: E501
+ 'JavaScript': (_JavaScript, 'sphinx.builders.html._assets._JavaScript', (9, 0)),
+}
+
+
+def __getattr__(name):
+ if name not in _DEPRECATED_OBJECTS:
+ raise AttributeError(f'module {__name__!r} has no attribute {name!r}')
+
+ from sphinx.deprecation import _deprecation_warning
+
+ deprecated_object, canonical_name, remove = _DEPRECATED_OBJECTS[name]
+ _deprecation_warning(__name__, name, canonical_name, remove=remove)
+ return deprecated_object
diff --git a/sphinx/builders/html/_assets.py b/sphinx/builders/html/_assets.py
index 92bec213a4..85d4e4f7cc 100644
--- a/sphinx/builders/html/_assets.py
+++ b/sphinx/builders/html/_assets.py
@@ -10,6 +10,32 @@ if TYPE_CHECKING:
from pathlib import Path
+class _CascadingStyleSheet:
+ def __init__(
+ self,
+ filename: str | os.PathLike[str], /, *,
+ priority: int = 500,
+ rel: str = 'stylesheet',
+ type: str = 'text/css',
+ **attributes: str,
+ ) -> None:
+ self.filename = filename
+ self.priority = priority
+ self.attributes = {'rel': rel, 'type': type, **attributes}
+
+
+class _JavaScript:
+ def __init__(
+ self,
+ filename: str | os.PathLike[str], /, *,
+ priority: int = 500,
+ **attributes: str,
+ ) -> None:
+ self.filename = filename
+ self.priority = priority
+ self.attributes = attributes
+
+
def _file_checksum(outdir: Path, filename: str | os.PathLike[str]) -> str:
filename = os.fspath(filename)
# Don't generate checksums for HTTP URIs