From 2986aa113c61c23346e4097f1055172a363e66cc Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Wed, 23 Aug 2023 22:45:58 +0100
Subject: [PATCH] Override special methods for string paths

---
 sphinx/util/_pathlib.py | 83 ++++++++++++++++++++++++++++++++---------
 1 file changed, 66 insertions(+), 17 deletions(-)

diff --git a/sphinx/util/_pathlib.py b/sphinx/util/_pathlib.py
index 91a1d2cabe2..ef85e734939 100644
--- a/sphinx/util/_pathlib.py
+++ b/sphinx/util/_pathlib.py
@@ -4,45 +4,94 @@
 
 import sys
 import warnings
-from pathlib import Path, PosixPath, WindowsPath
+from pathlib import Path, PosixPath, PurePath, WindowsPath
 
 from sphinx.deprecation import RemovedInSphinx80Warning
 
 _STR_METHODS = frozenset(str.__dict__)
 _PATH_NAME = Path().__class__.__name__
 
+_MSG = (
+    'Sphinx 8 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(self, old, new, count=-1, /):
             # replace exists in both Path and str;
             # in Path it makes filesystem changes, so we use the safer str version
-            warnings.warn('Sphinx 8 will drop support for representing paths as strings. '
-                          'Use "pathlib.Path" or "os.fspath" instead.',
-                          RemovedInSphinx80Warning, stacklevel=2)
-            return str(self).replace(old, new, count)
+            warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+            return self.__str__().replace(old, new, count)
 
         def __getattr__(self, item):
             if item in _STR_METHODS:
-                warnings.warn('Sphinx 8 will drop support for representing paths as strings. '
-                              'Use "pathlib.Path" or "os.fspath" instead.',
-                              RemovedInSphinx80Warning, stacklevel=2)
-                return getattr(str(self), item)
+                warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+                return getattr(self.__str__(), item)
             msg = f'{_PATH_NAME!r} has no attribute {item!r}'
             raise AttributeError(msg)
+
+        def __add__(self, other):
+            warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+            return self.__str__() + other
+
+        def __contains__(self, item):
+            warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+            return item in self.__str__()
+
+        def __eq__(self, other):
+            if isinstance(other, PurePath):
+                return super().__eq__(other)
+            if isinstance(other, str):
+                warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+                return self.__str__() == other
+            return NotImplemented
+
+        def __getitem__(self, item):
+            warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+            return self.__str__()[item]
+
+        def __len__(self):
+            warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+            return len(self.__str__())
 else:
     class _StrPath(PosixPath):
         def replace(self, old, new, count=-1, /):
-            warnings.warn('Sphinx 8 will drop support for representing paths as strings. '
-                          'Use "pathlib.Path" or "os.fspath" instead.',
-                          RemovedInSphinx80Warning, stacklevel=2)
-            return str(self).replace(old, new, count)
+            # replace exists in both Path and str;
+            # in Path it makes filesystem changes, so we use the safer str version
+            warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+            return self.__str__().replace(old, new, count)
 
         def __getattr__(self, item):
             if item in _STR_METHODS:
-                warnings.warn('Sphinx 8 will drop support for representing paths as strings. '
-                              'Use "pathlib.Path" or "os.fspath" instead.',
-                              RemovedInSphinx80Warning, stacklevel=2)
-                return getattr(str(self), item)
+                warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+                return getattr(self.__str__(), item)
             msg = f'{_PATH_NAME!r} has no attribute {item!r}'
             raise AttributeError(msg)
+
+        def __add__(self, other):
+            warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+            return self.__str__() + other
+
+        def __contains__(self, item):
+            warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+            return item in self.__str__()
+
+        def __eq__(self, other):
+            if isinstance(other, PurePath):
+                return super().__eq__(other)
+            if isinstance(other, str):
+                warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+                return self.__str__() == other
+            return NotImplemented
+
+        def __getitem__(self, item):
+            warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+            return self.__str__()[item]
+
+        def __len__(self):
+            warnings.warn(_MSG, RemovedInSphinx80Warning, stacklevel=2)
+            return len(self.__str__())