222 lines
6.4 KiB
Python
222 lines
6.4 KiB
Python
from __future__ import annotations
|
|
|
|
import os
|
|
import shutil
|
|
import sys
|
|
import warnings
|
|
from typing import IO, TYPE_CHECKING, Any, Callable
|
|
|
|
from sphinx.deprecation import RemovedInSphinx90Warning
|
|
|
|
if TYPE_CHECKING:
|
|
import builtins
|
|
|
|
warnings.warn("'sphinx.testing.path' is deprecated. "
|
|
"Use 'os.path' or 'pathlib' instead.",
|
|
RemovedInSphinx90Warning, stacklevel=2)
|
|
|
|
FILESYSTEMENCODING = sys.getfilesystemencoding() or sys.getdefaultencoding()
|
|
|
|
|
|
def getumask() -> int:
|
|
"""Get current umask value"""
|
|
umask = os.umask(0) # Note: Change umask value temporarily to obtain it
|
|
os.umask(umask)
|
|
|
|
return umask
|
|
|
|
|
|
UMASK = getumask()
|
|
|
|
|
|
class path(str):
|
|
"""
|
|
Represents a path which behaves like a string.
|
|
"""
|
|
|
|
__slots__ = ()
|
|
|
|
@property
|
|
def parent(self) -> path:
|
|
"""
|
|
The name of the directory the file or directory is in.
|
|
"""
|
|
return self.__class__(os.path.dirname(self))
|
|
|
|
def basename(self) -> str:
|
|
return os.path.basename(self)
|
|
|
|
def abspath(self) -> path:
|
|
"""
|
|
Returns the absolute path.
|
|
"""
|
|
return self.__class__(os.path.abspath(self))
|
|
|
|
def isabs(self) -> bool:
|
|
"""
|
|
Returns ``True`` if the path is absolute.
|
|
"""
|
|
return os.path.isabs(self)
|
|
|
|
def isdir(self) -> bool:
|
|
"""
|
|
Returns ``True`` if the path is a directory.
|
|
"""
|
|
return os.path.isdir(self)
|
|
|
|
def isfile(self) -> bool:
|
|
"""
|
|
Returns ``True`` if the path is a file.
|
|
"""
|
|
return os.path.isfile(self)
|
|
|
|
def islink(self) -> bool:
|
|
"""
|
|
Returns ``True`` if the path is a symbolic link.
|
|
"""
|
|
return os.path.islink(self)
|
|
|
|
def ismount(self) -> bool:
|
|
"""
|
|
Returns ``True`` if the path is a mount point.
|
|
"""
|
|
return os.path.ismount(self)
|
|
|
|
def rmtree(self, ignore_errors: bool = False, onerror: Callable | None = None) -> None:
|
|
"""
|
|
Removes the file or directory and any files or directories it may
|
|
contain.
|
|
|
|
:param ignore_errors:
|
|
If ``True`` errors are silently ignored, otherwise an exception
|
|
is raised in case an error occurs.
|
|
|
|
:param onerror:
|
|
A callback which gets called with the arguments `func`, `path` and
|
|
`exc_info`. `func` is one of :func:`os.listdir`, :func:`os.remove`
|
|
or :func:`os.rmdir`. `path` is the argument to the function which
|
|
caused it to fail and `exc_info` is a tuple as returned by
|
|
:func:`sys.exc_info`.
|
|
"""
|
|
shutil.rmtree(self, ignore_errors=ignore_errors, onerror=onerror)
|
|
|
|
def copytree(self, destination: str, symlinks: bool = False) -> None:
|
|
"""
|
|
Recursively copy a directory to the given `destination`. If the given
|
|
`destination` does not exist it will be created.
|
|
|
|
:param symlinks:
|
|
If ``True`` symbolic links in the source tree result in symbolic
|
|
links in the destination tree otherwise the contents of the files
|
|
pointed to by the symbolic links are copied.
|
|
"""
|
|
shutil.copytree(self, destination, symlinks=symlinks)
|
|
if os.environ.get('SPHINX_READONLY_TESTDIR'):
|
|
# If source tree is marked read-only (e.g. because it is on a read-only
|
|
# filesystem), `shutil.copytree` will mark the destination as read-only
|
|
# as well. To avoid failures when adding additional files/directories
|
|
# to the destination tree, ensure destination directories are not marked
|
|
# read-only.
|
|
for root, _dirs, files in os.walk(destination):
|
|
os.chmod(root, 0o755 & ~UMASK)
|
|
for name in files:
|
|
os.chmod(os.path.join(root, name), 0o644 & ~UMASK)
|
|
|
|
def movetree(self, destination: str) -> None:
|
|
"""
|
|
Recursively move the file or directory to the given `destination`
|
|
similar to the Unix "mv" command.
|
|
|
|
If the `destination` is a file it may be overwritten depending on the
|
|
:func:`os.rename` semantics.
|
|
"""
|
|
shutil.move(self, destination)
|
|
|
|
move = movetree
|
|
|
|
def unlink(self) -> None:
|
|
"""
|
|
Removes a file.
|
|
"""
|
|
os.unlink(self)
|
|
|
|
def stat(self) -> Any:
|
|
"""
|
|
Returns a stat of the file.
|
|
"""
|
|
return os.stat(self)
|
|
|
|
def utime(self, arg: Any) -> None:
|
|
os.utime(self, arg)
|
|
|
|
def open(self, mode: str = 'r', **kwargs: Any) -> IO:
|
|
return open(self, mode, **kwargs)
|
|
|
|
def write_text(self, text: str, encoding: str = 'utf-8', **kwargs: Any) -> None:
|
|
"""
|
|
Writes the given `text` to the file.
|
|
"""
|
|
with open(self, 'w', encoding=encoding, **kwargs) as f:
|
|
f.write(text)
|
|
|
|
def read_text(self, encoding: str = 'utf-8', **kwargs: Any) -> str:
|
|
"""
|
|
Returns the text in the file.
|
|
"""
|
|
with open(self, encoding=encoding, **kwargs) as f:
|
|
return f.read()
|
|
|
|
def read_bytes(self) -> builtins.bytes:
|
|
"""
|
|
Returns the bytes in the file.
|
|
"""
|
|
with open(self, mode='rb') as f:
|
|
return f.read()
|
|
|
|
def write_bytes(self, bytes: str, append: bool = False) -> None:
|
|
"""
|
|
Writes the given `bytes` to the file.
|
|
|
|
:param append:
|
|
If ``True`` given `bytes` are added at the end of the file.
|
|
"""
|
|
if append:
|
|
mode = 'ab'
|
|
else:
|
|
mode = 'wb'
|
|
with open(self, mode=mode) as f:
|
|
f.write(bytes)
|
|
|
|
def exists(self) -> bool:
|
|
"""
|
|
Returns ``True`` if the path exist.
|
|
"""
|
|
return os.path.exists(self)
|
|
|
|
def lexists(self) -> bool:
|
|
"""
|
|
Returns ``True`` if the path exists unless it is a broken symbolic
|
|
link.
|
|
"""
|
|
return os.path.lexists(self)
|
|
|
|
def makedirs(self, mode: int = 0o777, exist_ok: bool = False) -> None:
|
|
"""
|
|
Recursively create directories.
|
|
"""
|
|
os.makedirs(self, mode, exist_ok=exist_ok)
|
|
|
|
def joinpath(self, *args: Any) -> path:
|
|
"""
|
|
Joins the path with the argument given and returns the result.
|
|
"""
|
|
return self.__class__(os.path.join(self, *map(self.__class__, args)))
|
|
|
|
def listdir(self) -> list[str]:
|
|
return os.listdir(self)
|
|
|
|
__div__ = __truediv__ = joinpath
|
|
|
|
def __repr__(self) -> str:
|
|
return f'{self.__class__.__name__}({super().__repr__()})'
|