pathroot 1.0.0__tar.gz

pathroot-1.0.0/MANIFEST.in

@@ -0,0 +1 @@
+include test_pathroot.py

pathroot-1.0.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: pathroot
+Version: 1.0.0
+Summary: Subclass of a pathlib.Path object that does not allow traversal outside of a trusted root.
+Author-email: Josh Schneider <josh.schneider@gmail.com>
+Maintainer-email: Josh Schneider <josh.schneider@gmail.com>
+License-Expression: MIT
+Keywords: path,pathlib,filesystem
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+
+# PathRoot
+
+## What is PathRoot?
+
+A `PathRoot` object is a subclass of `pathlib.Path`. It takes an extra `safe_root=` keyword argument to set a trusted 
+root, and prevents operations that traverse outside of the trusted root.
+
+## How do you use PathRoot?
+
+You can initialize a `PathRoot` object like this:
+
+```python
+from pathroot import PathRoot
+
+root = PathRoot('/Users/foo/bar', safe_root='/Users/foo/bar')
+root = PathRoot('/Users/foo/bar')  # This also works.
+```
+
+From there, you can do anything you can do with a `Path` object. For instance:
+
+```python
+my_file = root / 'groceries.txt'  # This would work.
+my_file = root / '..' / '..' / 'groceries.txt'  # This would raise a `PathOutsideRootError` exception.
+```

pathroot-1.0.0/README.md

@@ -0,0 +1,24 @@
+# PathRoot
+
+## What is PathRoot?
+
+A `PathRoot` object is a subclass of `pathlib.Path`. It takes an extra `safe_root=` keyword argument to set a trusted 
+root, and prevents operations that traverse outside of the trusted root.
+
+## How do you use PathRoot?
+
+You can initialize a `PathRoot` object like this:
+
+```python
+from pathroot import PathRoot
+
+root = PathRoot('/Users/foo/bar', safe_root='/Users/foo/bar')
+root = PathRoot('/Users/foo/bar')  # This also works.
+```
+
+From there, you can do anything you can do with a `Path` object. For instance:
+
+```python
+my_file = root / 'groceries.txt'  # This would work.
+my_file = root / '..' / '..' / 'groceries.txt'  # This would raise a `PathOutsideRootError` exception.
+```

pathroot-1.0.0/pathroot.egg-info/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: pathroot
+Version: 1.0.0
+Summary: Subclass of a pathlib.Path object that does not allow traversal outside of a trusted root.
+Author-email: Josh Schneider <josh.schneider@gmail.com>
+Maintainer-email: Josh Schneider <josh.schneider@gmail.com>
+License-Expression: MIT
+Keywords: path,pathlib,filesystem
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+
+# PathRoot
+
+## What is PathRoot?
+
+A `PathRoot` object is a subclass of `pathlib.Path`. It takes an extra `safe_root=` keyword argument to set a trusted 
+root, and prevents operations that traverse outside of the trusted root.
+
+## How do you use PathRoot?
+
+You can initialize a `PathRoot` object like this:
+
+```python
+from pathroot import PathRoot
+
+root = PathRoot('/Users/foo/bar', safe_root='/Users/foo/bar')
+root = PathRoot('/Users/foo/bar')  # This also works.
+```
+
+From there, you can do anything you can do with a `Path` object. For instance:
+
+```python
+my_file = root / 'groceries.txt'  # This would work.
+my_file = root / '..' / '..' / 'groceries.txt'  # This would raise a `PathOutsideRootError` exception.
+```

pathroot-1.0.0/pathroot.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+MANIFEST.in
+README.md
+pathroot.py
+pyproject.toml
+test_pathroot.py
+pathroot.egg-info/PKG-INFO
+pathroot.egg-info/SOURCES.txt
+pathroot.egg-info/dependency_links.txt
+pathroot.egg-info/requires.txt
+pathroot.egg-info/top_level.txt

pathroot-1.0.0/pathroot.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pathroot-1.0.0/pathroot.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[dev]
+ruff
+pytest

pathroot-1.0.0/pathroot.egg-info/top_level.txt

@@ -0,0 +1 @@
+pathroot

pathroot-1.0.0/pathroot.py

@@ -0,0 +1,170 @@
+"""Variant of a Path that does not allow traversal outside of the root."""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path, PosixPath, WindowsPath
+
+LOG = logging.getLogger(__name__)
+OS_NAME = os.name
+
+
+class PathOutsideRootError(OSError):
+    """Exception to raise when a path traverses outside a root."""
+
+    def __init__(self, path: Path, root: PathRoot, *args):
+        """Prepare a PathOutsideRootError for use.
+
+        Args:
+            path: Target path.
+            root: Trusted root path.
+            *args: Arguments passed to OSError.
+        """
+        super().__init__(*args)
+        self.path = path
+        self.root = root
+
+    def __str__(self) -> str:
+        """String message."""
+        return f"Path {self.path} ({self.path.resolve()}) is outside of {self.root}."
+
+
+class PathRoot(Path):
+    """Base class for a path that does not allow traversal outside.
+
+    Notes:
+        When a PathRoot is first instantiated, if a `safe_root` is not provided, then
+        the current directory is used as the SafeRoot. All methods that mutate the path
+        or work off of additional provided paths have those paths resolved and checked
+        against the safe root. If the resolved path is not relative to the safe root,
+        then a `PathOutsideRootError` is raised.
+    """
+
+    def __new__(cls, *args, **kwargs) -> WindowsPathRoot | PosixPathRoot:  # noqa: ARG004
+        """Generate the OS-specific subclass based on the current OS."""
+        if cls is PathRoot:
+            cls = WindowsPathRoot if OS_NAME == "nt" else PosixPathRoot
+        return object.__new__(cls)
+
+    def __init__(self, *args, safe_root: Path | None = None):
+        """Prepare a PathRoot for use.
+
+        Args:
+            *args: Path segments, passed to Path.
+            safe_root: Root path to use for all operations. Defaults to None (current path is used).
+        """
+        super().__init__(*args)
+
+        # If the safe_root is None, then one was not provided. Look through the args
+        # and see if we have any PathRoot instances... first one wins.
+        if safe_root is None:
+            for arg in args:
+                if isinstance(arg, PathRoot):
+                    safe_root = arg.safe_root
+                    break
+            else:  # no break
+                # Set the safe_root to this path.
+                safe_root = Path(self)
+        self.safe_root = safe_root.resolve()  # Ensure safe_root is resolved.
+        LOG.debug("Created %r", self)
+
+    def __repr__(self) -> str:
+        """Internal string representation."""
+        return f"{type(self).__name__}({self.as_posix()!r}, safe_root={self.safe_root.as_posix()!r})"
+
+    def __check_path(self, path: Path | PathRoot) -> PathRoot:
+        """Check if a path traverses outside.
+
+        Args:
+            path: Path to check.
+
+        Returns:
+            The tested path.
+
+        Raises:
+            PathOutsideRootError: If the path traverses outside of the root path.
+        """
+        p = Path(path).resolve()
+        LOG.debug("Testing %s against %s", p, self.safe_root)
+        if not p.is_relative_to(self.safe_root):
+            raise PathOutsideRootError(path, self.safe_root)
+
+        match path:
+            # If the path is a PathRoot with no safe_root set, set it.
+            case PathRoot():
+                path.safe_root = self.safe_root
+
+            # If the path is not a PathRoot, make it one.
+            case Path() if not isinstance(path, PathRoot):
+                path = PathRoot(path, safe_root=self.safe_root)
+
+        return path
+
+    def with_segments(self, *args) -> PathRoot:
+        """Return a new path with segments.
+
+        Args:
+            *args: Path segments.
+
+        Returns:
+            New path.
+        """
+        return self.__check_path(super().with_segments(*args))
+
+    def rename(self, target: Path | str) -> PathRoot:
+        """Rename this path to the target path.
+
+        Args:
+            target: Target path. Must be in the root.
+
+        Returns:
+            New PathRoot instance pointing to the target path.
+
+        Notes:
+            The target path may be absolute or relative. Relative paths are
+            interpreted relative to the current working directory *not* the
+            directory of the Path object.
+        """
+        return super().rename(self.__check_path(target))
+
+    def replace(self, target: Path | str) -> PathRoot:
+        """Rename this path to the target path, overwriting if that path exists.
+
+        Args:
+            target: Target path. Must be in the root.
+
+        Returns:
+            New PathRoot instance pointing to the target path.
+
+        Notes:
+            The target path may be absolute or relative. Relative paths are
+            interpreted relative to the current working directory *not* the
+            directory of the Path object.
+        """
+        return super().replace(self.__check_path(target))
+
+    def symlink_to(self, target: Path | str, target_is_directory: bool = False) -> None:
+        """Make this path a symlink pointing to the target path.
+
+        Args:
+            target: Target to link to. Must be inside root path.
+            target_is_directory: Should the target be treated as a directory (only valid for Windows). Defaults to False.
+        """
+        return super().symlink_to(self.__check_path(target), target_is_directory)
+
+    def hardlink_to(self, target: Path | str) -> None:
+        """Make this path a hard link pointing to the same file as *target*.
+
+        Args:
+            target: Target to link to. Must be inside the root path.
+        """
+        return super().hardlink_to(self.__check_path(target))
+
+
+class PosixPathRoot(PosixPath, PathRoot):
+    """Path that does not allow traversal outside of root for Linux/MacOS."""
+
+
+class WindowsPathRoot(WindowsPath, PathRoot):
+    """Path that does not allow traversal outside of the root for Windows."""

pathroot-1.0.0/pyproject.toml

@@ -0,0 +1,70 @@
+[project]
+name = "pathroot"
+version = "1.0.0"
+description = "Subclass of a pathlib.Path object that does not allow traversal outside of a trusted root."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = []
+authors = [{ name = "Josh Schneider", email = "josh.schneider@gmail.com" }]
+maintainers = [{ name = "Josh Schneider", email = "josh.schneider@gmail.com" }]
+license = "MIT"
+keywords = ["path", "pathlib", "filesystem"]
+
+[project.optional-dependencies]
+dev = ["ruff", "pytest"]
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+py-modules = ["pathroot"]
+
+[tool.ruff]
+line-length = 120
+respect-gitignore = true
+
+[tool.ruff.lint]
+select = [
+    "C90",  # mccabe
+    "I",    # iSort
+    "N",    # pep8-naming
+    "D",    # pydocstyle
+    "ANN",  # flake8-annotations
+    "S",    # flake8-bandit
+    "B",    # flake8-bugbear
+    "A",    # flake8-builtins
+    "COM",  # flake8-commas
+    "C4",   # flake8-comprehensions
+    "EM",   # flake8-errmsg
+    "FA",   # flake8-future-annotations
+    "ISC",  # flake8-implicit-str-concat
+    "LOG",  # flake8-logging
+    "G",    # flake8-logging-format
+    "T20",  # flake8-print
+    "Q",    # flake8-quotes
+    "SIM",  # flake8-simplify
+    "ARG",  # flake8-unused-arguments
+    "PT",   # flake8-pytest-style
+    "PTH",  # flake8-use-pathlib
+    "PERF", # perflint
+    "RUF",  # Ruff-specific rules
+]
+
+ignore = [
+    "ANN002", # No need to type *args
+    "ANN003", # No need to type **kwargs
+]
+
+[tool.ruff.lint.extend-per-file-ignores]
+"test_*.py" = [ # Pytest tests
+    "ANN001", # No need to type hint fixtures
+    "T201",   # Print is fine in unit tests
+    "S101",   # assert is kinda the reason we're here...
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.flake8-annotations]
+suppress-none-returning = true

pathroot-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pathroot-1.0.0/test_pathroot.py

@@ -0,0 +1,221 @@
+"""Unit tests for pathroot."""
+
+import logging
+from contextlib import contextmanager
+from pathlib import Path
+
+import pytest
+
+import pathroot
+
+LOG = logging.getLogger(__name__)
+
+# Dictionary of test files to create in root_folder.
+# Keys should be Path objects, and values should be None
+# for directories, or a bytes object for contents.
+TEST_FILES = {
+    Path("d1"): None,
+    Path("d1/f1.txt"): b"First file",
+    Path("d2"): None,
+    Path("d2/f2.txt"): b"Second file",
+}
+
+
+# region Fixtures
+@pytest.fixture
+def root_folder(tmp_path) -> Path:  # type: ignore
+    """Self cleaning test folder, populated by TEST_FILES."""
+    for p, c in TEST_FILES.items():
+        p = tmp_path / p
+        if c is None:
+            p.mkdir(exist_ok=True, parents=True)
+            LOG.info("** Created dir %s", p)
+        else:
+            p.parent.mkdir(exist_ok=True, parents=True)
+            p.write_bytes(c)
+            LOG.info("** Create file %s", p)
+
+    LOG.info("** Returning %s", tmp_path)
+    yield tmp_path
+
+    for p in sorted(tmp_path.rglob("*"), reverse=True):
+        if p.is_symlink() or p.is_file():
+            p.unlink()
+            LOG.info("** Unlinking %s", p)
+        elif p.is_dir():
+            p.rmdir()
+            LOG.info("** Removing dir %s", p)
+
+
+@contextmanager
+def fix_os_name(v: str):
+    """Context manager for replacing pathroot.OS_NAME temporarily.
+
+    Args:
+        v: Value to set OS_NAME to.
+    """
+    old_val = pathroot.OS_NAME
+    pathroot.OS_NAME = v
+    LOG.info("** Set OS_NAME to %r", v)
+    try:
+        yield
+    finally:
+        pathroot.OS_NAME = old_val
+        LOG.info("** Set OS_NAME back to %r", old_val)
+
+
+@pytest.fixture
+def _force_nt():
+    """Force the OS name to nt (for Windows)."""
+    with fix_os_name("nt"):
+        yield
+
+
+@pytest.fixture
+def _force_posix():
+    """Force the OS name to darwin (for POSIX)."""
+    with fix_os_name("darwin"):
+        yield
+
+
+# endregion
+
+
+# region Tests
+@pytest.mark.usefixtures("_force_nt")
+def test_new_windows(root_folder):
+    """Test that PathRoot, on Windows, returns a WindowsPathRoot instance."""
+    # Act
+    r = pathroot.PathRoot(root_folder)
+
+    # Assert
+    assert type(r) is pathroot.WindowsPathRoot
+
+
+@pytest.mark.usefixtures("_force_posix")
+def test_new_posix(root_folder):
+    """Test that PathRoot, on a POSIX OS, returns a PosixPathRoot instance."""
+    # Act
+    r = pathroot.PathRoot(root_folder)
+
+    # Assert
+    assert type(r) is pathroot.PosixPathRoot
+
+
+def test_joinpath_works(root_folder):
+    """Test that when we use joinpath with a path inside the the root, it works, and we get a PathRoot instance."""
+    # Arrange
+    r = pathroot.PathRoot(root_folder)
+
+    # Act
+    p1 = r.joinpath("foo/bar.txt")
+
+    # Assert
+    assert isinstance(p1, pathroot.PathRoot)
+    assert p1.safe_root is r.safe_root
+
+
+def test_joinpath_errors(root_folder):
+    """Test that when we use joinpath with a path outside the root, it raises a PathOutsideRootError."""
+    # Arrange
+    r = pathroot.PathRoot(root_folder)
+
+    # Act and Assert
+    with pytest.raises(pathroot.PathOutsideRootError):
+        r.joinpath("..", "..", "etc")
+
+
+def test_divide_works(root_folder):
+    """Test that when we use the divide operator inside the root, it works, and we get a PathRoot instance."""
+    # Arrange
+    r = pathroot.PathRoot(root_folder)
+
+    # Act
+    p1 = r / "foo" / "bar.txt"
+
+    # Assert
+    assert isinstance(p1, pathroot.PathRoot)
+    assert p1.safe_root is r.safe_root
+
+
+def test_divide_errors(root_folder):
+    """Test that when we use the divide operator outside the root, it raises a PathOutsideRootError."""
+    # Arrange
+    r = pathroot.PathRoot(root_folder)
+
+    # Act and Assert
+    with pytest.raises(pathroot.PathOutsideRootError):
+        r / ".." / ".." / "etc"
+
+
+def test_with_segments_works(root_folder):
+    """Test that with_segments with a path inside the root works, and we get a PathRoot instance."""
+    # Arrange
+    r = pathroot.PathRoot(root_folder)
+
+    # Act
+    p1 = r.with_segments(root_folder, "foo/bar.txt")
+
+    # Assert
+    assert isinstance(p1, pathroot.PathRoot)
+    assert p1.safe_root is r.safe_root
+
+
+def test_with_segments_errors(root_folder):
+    """Test that when we use with_segments with a path inside the the root, it works, and we get a PathRoot instance."""
+    # Arrange
+    r = pathroot.PathRoot(root_folder)
+
+    # Act and Assert
+    with pytest.raises(pathroot.PathOutsideRootError):
+        r.with_segments(root_folder, "..", "..", "etc")
+
+
+def test_rename_works(root_folder):
+    """Test that rename works when it should."""
+    # Arrange
+    p1 = pathroot.PathRoot(root_folder) / "d1"
+
+    # Act
+    p2 = p1.rename(root_folder / "d3")
+
+    # Assert
+    assert isinstance(p2, pathroot.PathRoot)
+    assert p2.safe_root is p1.safe_root
+
+
+def test_rename_errors(root_folder):
+    """Test that rename errors when the target path is outside of the root."""
+    # Arrange
+    r = pathroot.PathRoot(root_folder)
+
+    # Act and Assert
+    with pytest.raises(pathroot.PathOutsideRootError):
+        r.rename(root_folder / ".." / ".." / "etc")
+
+
+def test_replace_works(root_folder):
+    """Test that replae works."""
+    # Arrange
+    p1 = pathroot.PathRoot(root_folder) / "d1"
+
+    # Act
+    p2 = p1.replace(root_folder / "d3")
+
+    # Assert
+    assert isinstance(p2, pathroot.PathRoot)
+    assert p2.safe_root is p1.safe_root
+
+
+def test_replace_errors(root_folder):
+    """Test that replace errors when the target path is outside of the root."""
+    # Arrange
+    r = pathroot.PathRoot(root_folder)
+
+    # Act and Assert
+    with pytest.raises(pathroot.PathOutsideRootError):
+        r.replace(root_folder / ".." / ".." / "etc")
+
+
+# TODO: Other corner cases?
+# endregion