Sphinx 8.0.0rc1__py3-none-any.whl → 8.0.2__py3-none-any.whl

sphinx/project.py

@@ -9,6 +9,7 @@ from typing import TYPE_CHECKING
 
 from sphinx.locale import __
 from sphinx.util import logging
+from sphinx.util._pathlib import _StrPath
 from sphinx.util.matching import get_matching_files
 from sphinx.util.osutil import path_stabilize
 
@@ -24,7 +25,7 @@ class Project:
 
     def __init__(self, srcdir: str | os.PathLike[str], source_suffix: Iterable[str]) -> None:
         #: Source directory.
-        self.srcdir = Path(srcdir)
+        self.srcdir = _StrPath(srcdir)
 
         #: source_suffix. Same as :confval:`source_suffix`.
         self.source_suffix = tuple(source_suffix)
@@ -106,7 +107,7 @@ class Project:
             # the file does not have a docname
             return None
 
-    def doc2path(self, docname: str, absolute: bool) -> Path:
+    def doc2path(self, docname: str, absolute: bool) -> _StrPath:
         """Return the filename for the document name.
 
         If *absolute* is True, return as an absolute path.
@@ -119,5 +120,5 @@ class Project:
             filename = Path(docname + self._first_source_suffix)
 
         if absolute:
-            return self.srcdir / filename
-        return filename
+            return _StrPath(self.srcdir / filename)
+        return _StrPath(filename)

sphinx/util/_pathlib.py

@@ -0,0 +1,132 @@
+"""What follows is awful and will be gone in Sphinx 9.
+
+Instances of _StrPath should not be constructed except in Sphinx itself.
+Consumers of Sphinx APIs should prefer using ``pathlib.Path`` objects
+where possible. _StrPath objects can be treated as equivalent to ``Path``,
+save that ``_StrPath.replace`` is overriden with ``str.replace``.
+
+To continue treating path-like objects as strings, use ``os.fspath``,
+or explicit string coercion.
+
+In Sphinx 9, ``Path`` objects will be expected and returned in all instances
+that ``_StrPath`` is currently used.
+"""
+
+from __future__ import annotations
+
+import sys
+import warnings
+from pathlib import Path, PosixPath, PurePath, WindowsPath
+from typing import Any
+
+from sphinx.deprecation import RemovedInSphinx90Warning
+
+_STR_METHODS = frozenset(str.__dict__)
+_PATH_NAME = Path().__class__.__name__
+
+_MSG = (
+    'Sphinx 9 will drop support for representing paths as strings. '
+    'Use "pathlib.Path" or "os.fspath" instead.'
+)
+
+# https://docs.python.org/3/library/stdtypes.html#typesseq-common
+# https://docs.python.org/3/library/stdtypes.html#string-methods
+
+if sys.platform == 'win32':
+    class _StrPath(WindowsPath):
+        def replace(  # type: ignore[override]
+            self, old: str, new: str, count: int = -1, /,
+        ) -> str:
+            # replace exists in both Path and str;
+            # in Path it makes filesystem changes, so we use the safer str version
+            warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
+            return self.__str__().replace(old, new, count)  # NoQA:  PLC2801
+
+        def __getattr__(self, item: str) -> Any:
+            if item in _STR_METHODS:
+                warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
+                return getattr(self.__str__(), item)
+            msg = f'{_PATH_NAME!r} has no attribute {item!r}'
+            raise AttributeError(msg)
+
+        def __add__(self, other: str) -> str:
+            warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
+            return self.__str__() + other
+
+        def __bool__(self) -> bool:
+            if not self.__str__():
+                warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
+                return False
+            return True
+
+        def __contains__(self, item: str) -> bool:
+            warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
+            return item in self.__str__()
+
+        def __eq__(self, other: object) -> bool:
+            if isinstance(other, PurePath):
+                return super().__eq__(other)
+            if isinstance(other, str):
+                warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
+                return self.__str__() == other
+            return NotImplemented
+
+        def __hash__(self) -> int:
+            return super().__hash__()
+
+        def __getitem__(self, item: int | slice) -> str:
+            warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
+            return self.__str__()[item]
+
+        def __len__(self) -> int:
+            warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
+            return len(self.__str__())
+else:
+    class _StrPath(PosixPath):
+        def replace(  # type: ignore[override]
+            self, old: str, new: str, count: int = -1, /,
+        ) -> str:
+            # replace exists in both Path and str;
+            # in Path it makes filesystem changes, so we use the safer str version
+            warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
+            return self.__str__().replace(old, new, count)  # NoQA:  PLC2801
+
+        def __getattr__(self, item: str) -> Any:
+            if item in _STR_METHODS:
+                warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
+                return getattr(self.__str__(), item)
+            msg = f'{_PATH_NAME!r} has no attribute {item!r}'
+            raise AttributeError(msg)
+
+        def __add__(self, other: str) -> str:
+            warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
+            return self.__str__() + other
+
+        def __bool__(self) -> bool:
+            if not self.__str__():
+                warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
+                return False
+            return True
+
+        def __contains__(self, item: str) -> bool:
+            warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
+            return item in self.__str__()
+
+        def __eq__(self, other: object) -> bool:
+            if isinstance(other, PurePath):
+                return super().__eq__(other)
+            if isinstance(other, str):
+                warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
+                return self.__str__() == other
+            return NotImplemented
+
+        def __hash__(self) -> int:
+            return super().__hash__()
+
+        def __getitem__(self, item: int | slice) -> str:
+            warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
+            return self.__str__()[item]
+
+        def __len__(self) -> int:
+            warnings.warn(_MSG, RemovedInSphinx90Warning, stacklevel=2)
+            return len(self.__str__())

sphinx/util/osutil.py

@@ -11,12 +11,12 @@ import sys
 import unicodedata
 from io import StringIO
 from os import path
+from pathlib import Path
 from typing import TYPE_CHECKING
 
 from sphinx.locale import __
 
 if TYPE_CHECKING:
-    from pathlib import Path
     from types import TracebackType
     from typing import Any
 
@@ -107,12 +107,15 @@ def copyfile(
 
     .. note:: :func:`copyfile` is a no-op if *source* and *dest* are identical.
     """
-    if not path.exists(source):
-        msg = f'{os.fsdecode(source)} does not exist'
+    # coerce to Path objects
+    source = Path(source)
+    dest = Path(dest)
+    if not source.exists():
+        msg = f'{source} does not exist'
         raise FileNotFoundError(msg)
 
     if (
-        not (dest_exists := path.exists(dest)) or
+        not (dest_exists := dest.exists()) or
         # comparison must be done using shallow=False since
         # two different files might have the same size
         not filecmp.cmp(source, dest, shallow=False)
@@ -125,7 +128,7 @@ def copyfile(
 
             msg = __('Aborted attempted copy from %s to %s '
                      '(the destination path has existing data).')
-            logger.warning(msg, os.fsdecode(source), os.fsdecode(dest),
+            logger.warning(msg, source, dest,
                            type='misc', subtype='copy_overwrite')
             return
 

{sphinx-8.0.0rc1.dist-info → sphinx-8.0.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: Sphinx
-Version: 8.0.0rc1
+Version: 8.0.2
 Summary: Python documentation generator
 Author-email: Georg Brandl <georg@python.org>
 Requires-Python: >=3.10
@@ -52,7 +52,7 @@ Requires-Dist: Pygments>=2.17
 Requires-Dist: docutils>=0.20,<0.22
 Requires-Dist: snowballstemmer>=2.2
 Requires-Dist: babel>=2.13
-Requires-Dist: alabaster~=0.7.14
+Requires-Dist: alabaster>=0.7.14
 Requires-Dist: imagesize>=1.3
 Requires-Dist: requests>=2.30.0
 Requires-Dist: packaging>=23.0
@@ -60,7 +60,7 @@ Requires-Dist: tomli>=2; python_version < '3.11'
 Requires-Dist: colorama>=0.4.6; sys_platform == 'win32'
 Requires-Dist: sphinxcontrib-websupport ; extra == "docs"
 Requires-Dist: flake8>=6.0 ; extra == "lint"
-Requires-Dist: ruff==0.5.4 ; extra == "lint"
+Requires-Dist: ruff==0.5.5 ; extra == "lint"
 Requires-Dist: mypy==1.11.0 ; extra == "lint"
 Requires-Dist: sphinx-lint>=0.9 ; extra == "lint"
 Requires-Dist: types-colorama==0.4.15.20240311 ; extra == "lint"