superpathlib 2.0.14__tar.gz → 2.1.1__tar.gz

{superpathlib-2.0.14/src/superpathlib.egg-info → superpathlib-2.1.1}/PKG-INFO

@@ -1,36 +1,33 @@
 Metadata-Version: 2.4
 Name: superpathlib
-Version: 2.0.14
+Version: 2.1.1
 Summary: Extended Pathlib
 Author-email: Quinten Roets <qdr2104@columbia.edu>
 License-Expression: MIT
 Project-URL: Source Code, https://github.com/quintenroets/superpathlib
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: simple-classproperty<5,>=4.0.2
-Requires-Dist: typing_extensions<5,>=4.0
 Provides-Extra: full
 Requires-Dist: dirhash<1,>=0.2.1; extra == "full"
 Requires-Dist: numpy<3,>=1.26.4; extra == "full"
-Requires-Dist: package-utils<1,>=0.8.1; extra == "full"
+Requires-Dist: package-utils<1,>=0.9.0; extra == "full"
 Requires-Dist: PyYaml<7,>=6.0.1; extra == "full"
-Requires-Dist: xattr<2,>=0.10.1; extra == "full"
 Provides-Extra: dev
 Requires-Dist: hypothesis<7,>=6.97.1; extra == "dev"
-Requires-Dist: package-dev-tools<1,>=0.8.1; extra == "dev"
+Requires-Dist: package-dev-tools<1,>=0.8.6; extra == "dev"
 Requires-Dist: types-PyYaml<7,>=6.0.12.12; extra == "dev"
 Requires-Dist: dirhash<1,>=0.2.1; extra == "dev"
 Requires-Dist: numpy<3,>=1.26.4; extra == "dev"
-Requires-Dist: package-utils<1,>=0.8.0; extra == "dev"
+Requires-Dist: package-utils<1,>=0.9.0; extra == "dev"
 Requires-Dist: PyYaml<7,>=6.0.1; extra == "dev"
-Requires-Dist: xattr<2,>=0.10.1; extra == "dev"
 Dynamic: license-file
 
 # Superpathlib
 [![PyPI version](https://badge.fury.io/py/superpathlib.svg)](https://badge.fury.io/py/superpathlib)
 ![PyPI downloads](https://img.shields.io/pypi/dm/superpathlib)
-![Python version](https://img.shields.io/badge/python-3.10+-brightgreen)
+![Python version](https://img.shields.io/badge/python-3.11+-brightgreen)
 ![Operating system](https://img.shields.io/badge/os-linux%20%7c%20macOS-brightgreen)
 ![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)
 
@@ -42,13 +39,13 @@ For custom operations, the package supports subclassing, which has been added to
 
 ## Key features:
 * Read and write content in various formats such as text, bytes, YAML, JSON, and even NumPy arrays
-* Access and modify file metadata like file size, modification time, and custom tags
+* Access and modify file metadata like file size and modification time
 * Utility methods:
     * `rmtree` to remove directories recursively
     * `copy_to` to copy content
     * `tempfile` to create and use temporary files
     * `find` for recursive search
-    * `unpack` for unpacking archives
+    * `unpack_if_archive` for unpacking archives
 
 ## Usage
 
@@ -66,10 +63,17 @@ path = Path(filename)
 * json
 * numpy
 
+read-only:
+* cached_yaml: yaml content, cached as json next to the file
+
+gpg-encrypted on disk:
+* encrypted: prefix any of the above to read & write plaintext (e.g. `path.encrypted.json`)
+
 examples:
 
 ```shell
 path.json = {key: value}
+path.encrypted.json = {key: secret}
 
 for line in path.lines:
     if interesting(line):
@@ -85,14 +89,13 @@ for line in path.lines:
     * content_hash: a hash of the complete substructure found in a folder
 * get & set:
     * mtime: modified time
-    * tag: can be used for alternative ordering or metadata
 
 examples:
 
 ```shell
 path_new.mtime = path_old.mtime
 
-if path.tag != skip_keyword and path.filetype == "video":
+if path.filetype == "video":
     process(path)
 ```
 ### 3) Use class properties to access commonly used folders:
@@ -110,11 +113,10 @@ names = names_path.lines
 * find(): recursively find all paths under a root that match a condition (extra options available for performance optimization)
 * rmtree(): remove directory recursively
 * copy_to(dest): copy content to dest
-* copy_properties_to(dest): recursively copy path properties (mtime, tag) to all n-level children of dest
+* copy_mtime_to(dest): recursively copy modified time to all n-level children of dest
 * tempfile(): create temporary file that can be used as context manager
-* unpack(): extract archive(zip, tar, ..) file to desired folder
+* unpack_if_archive(): extract an archive(zip, tar, ..) file to desired folder, recursively
 * pop_parent(): remove first parent from path in filesystem
-* from_uri(uri): create path object from uri string
 
 examples:
 

{superpathlib-2.0.14 → superpathlib-2.1.1}/README.md

@@ -1,7 +1,7 @@
 # Superpathlib
 [![PyPI version](https://badge.fury.io/py/superpathlib.svg)](https://badge.fury.io/py/superpathlib)
 ![PyPI downloads](https://img.shields.io/pypi/dm/superpathlib)
-![Python version](https://img.shields.io/badge/python-3.10+-brightgreen)
+![Python version](https://img.shields.io/badge/python-3.11+-brightgreen)
 ![Operating system](https://img.shields.io/badge/os-linux%20%7c%20macOS-brightgreen)
 ![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)
 
@@ -13,13 +13,13 @@ For custom operations, the package supports subclassing, which has been added to
 
 ## Key features:
 * Read and write content in various formats such as text, bytes, YAML, JSON, and even NumPy arrays
-* Access and modify file metadata like file size, modification time, and custom tags
+* Access and modify file metadata like file size and modification time
 * Utility methods:
     * `rmtree` to remove directories recursively
     * `copy_to` to copy content
     * `tempfile` to create and use temporary files
     * `find` for recursive search
-    * `unpack` for unpacking archives
+    * `unpack_if_archive` for unpacking archives
 
 ## Usage
 
@@ -37,10 +37,17 @@ path = Path(filename)
 * json
 * numpy
 
+read-only:
+* cached_yaml: yaml content, cached as json next to the file
+
+gpg-encrypted on disk:
+* encrypted: prefix any of the above to read & write plaintext (e.g. `path.encrypted.json`)
+
 examples:
 
 ```shell
 path.json = {key: value}
+path.encrypted.json = {key: secret}
 
 for line in path.lines:
     if interesting(line):
@@ -56,14 +63,13 @@ for line in path.lines:
     * content_hash: a hash of the complete substructure found in a folder
 * get & set:
     * mtime: modified time
-    * tag: can be used for alternative ordering or metadata
 
 examples:
 
 ```shell
 path_new.mtime = path_old.mtime
 
-if path.tag != skip_keyword and path.filetype == "video":
+if path.filetype == "video":
     process(path)
 ```
 ### 3) Use class properties to access commonly used folders:
@@ -81,11 +87,10 @@ names = names_path.lines
 * find(): recursively find all paths under a root that match a condition (extra options available for performance optimization)
 * rmtree(): remove directory recursively
 * copy_to(dest): copy content to dest
-* copy_properties_to(dest): recursively copy path properties (mtime, tag) to all n-level children of dest
+* copy_mtime_to(dest): recursively copy modified time to all n-level children of dest
 * tempfile(): create temporary file that can be used as context manager
-* unpack(): extract archive(zip, tar, ..) file to desired folder
+* unpack_if_archive(): extract an archive(zip, tar, ..) file to desired folder, recursively
 * pop_parent(): remove first parent from path in filesystem
-* from_uri(uri): create path object from uri string
 
 examples:
 

{superpathlib-2.0.14 → superpathlib-2.1.1}/pyproject.toml

@@ -1,27 +1,25 @@
 [project]
 name = "superpathlib"
-version = "2.0.14"
+version = "2.1.1"
 description = "Extended Pathlib"
 authors = [{name = "Quinten Roets", email = "qdr2104@columbia.edu"}]
 license = "MIT"
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 dependencies = [
     "simple-classproperty >=4.0.2, <5",
-    "typing_extensions >=4.0, <5",
 ]
 
 [project.optional-dependencies]
 full = [
     "dirhash >=0.2.1, <1",
     "numpy >=1.26.4, <3",
-    "package-utils >=0.8.1, <1",
+    "package-utils >=0.9.0, <1",
     "PyYaml >=6.0.1, <7",
-    "xattr >=0.10.1, <2",
 ]
 dev = [
     "hypothesis >=6.97.1, <7",
-    "package-dev-tools >=0.8.1, <1",
+    "package-dev-tools >=0.8.6, <1",
 
     # types
     "types-PyYaml >=6.0.12.12, <7",
@@ -29,9 +27,8 @@ dev = [
     # full
     "dirhash >=0.2.1, <1",
     "numpy >=1.26.4, <3",
-    "package-utils >=0.8.0, <1",
+    "package-utils >=0.9.0, <1",
     "PyYaml >=6.0.1, <7",
-    "xattr >=0.10.1, <2",
 ]
 
 [project.urls]
@@ -43,6 +40,7 @@ build-backend = "setuptools.build_meta"
 
 [tool.coverage.run]
 command_line = "-m pytest tests"
+relative_files = true
 
 [tool.coverage.report]
 precision = 4
@@ -55,7 +53,6 @@ no_implicit_reexport = false
 [[tool.mypy.overrides]]
 module = [
     "dirhash.*",
-    "xattr.*",
 ]
 ignore_missing_imports = true
 
@@ -71,6 +68,7 @@ fix = true
 select = ["ALL"]
 ignore = [
     "ANN401",   # annotated with Any
+    "CPY001",   # missing copyright notice
     "D1",       # missing docstrings
     "D200",     # one-line docstring
     "D203",     # conflicts with D211
@@ -78,6 +76,7 @@ ignore = [
     "D212",     # conflicts with D213
     "D401",     # imperative first line
     "G004",     # logging f-string
+    "PLC0415",  # lazy imports for import performance and optional dependencies
 ]
 
 [tool.ruff.lint.per-file-ignores]
@@ -87,18 +86,6 @@ ignore = [
 "tests/*" = [
     "S101",  # assert used
 ]
-"src/superpathlib/cached_content.py" = [
-    "PLC0415",  # lazy imports for optional dependency
-]
-"src/superpathlib/content_properties.py" = [
-    "PLC0415",  # lazy imports for optional dependencies
-]
-"src/superpathlib/extra_functionality.py" = [
-    "PLC0415",  # lazy imports for optional dependencies
-]
-"src/superpathlib/metadata_properties.py" = [
-    "PLC0415",  # lazy imports for optional dependencies
-]
 
 [tool.setuptools.package-data]
 superpathlib = ["py.typed"]

superpathlib-2.1.1/src/superpathlib/archive.py

@@ -0,0 +1,71 @@
+import shutil
+from functools import cached_property
+from typing import Generic, TypeVar, cast
+
+from .extra_functionality import Path
+
+P = TypeVar("P", bound=Path)
+
+
+class Archive(Generic[P]):
+    def __init__(self, path: P) -> None:
+        self.path = path
+
+    @cached_property
+    def format_(self) -> str | None:
+        # noinspection PyProtectedMember
+        format_ = shutil._find_unpack_format(str(self.path))  # type: ignore[attr-defined] # noqa: SLF001
+        return cast("str | None", format_)
+
+    def unpack(  # noqa: PLR0913
+        self,
+        extraction_directory: P | None = None,
+        *,
+        remove_existing: bool = True,
+        preserve_mtime: bool = True,
+        remove_original: bool = True,
+        format_: str | None = None,
+        recursive: bool = True,
+    ) -> None:
+        format_ = cast("str", self.format_) if format_ is None else format_
+        extraction_directory = (
+            self.create_extraction_directory(format_)
+            if extraction_directory is None
+            else extraction_directory
+        )
+
+        if remove_existing:
+            extraction_directory.remove()
+
+        shutil.unpack_archive(
+            self.path,
+            extract_dir=extraction_directory,
+            format=format_,
+        )
+
+        self.cleanup(extraction_directory)
+        if preserve_mtime:
+            self.path.copy_mtime_to(extraction_directory)
+
+        if remove_original:
+            self.path.unlink()
+
+        if recursive:
+            for path in extraction_directory.find():
+                path.unpack_if_archive()
+
+    def create_extraction_directory(self, format_: str) -> P:
+        # noinspection PyProtectedMember
+        unpack_formats = shutil._UNPACK_FORMATS  # type: ignore[attr-defined] # noqa: SLF001
+        extensions, *_ = unpack_formats[format_]
+        extract_name = self.path.name
+        for archive_extension in extensions:
+            extract_name = extract_name.removesuffix(archive_extension)
+        return self.path.with_name(extract_name)
+
+    @staticmethod
+    def cleanup(extraction_directory: P) -> None:
+        (extraction_directory / "__MACOSX").rmtree(missing_ok=True)
+        subfolder = extraction_directory / extraction_directory.name
+        if subfolder.exists() and extraction_directory.number_of_children == 1:
+            subfolder.pop_parent()  # pragma: nocover

{superpathlib-2.0.14 → superpathlib-2.1.1}/src/superpathlib/common_folders.py

@@ -1,17 +1,14 @@
 import abc
 import sys
 import typing
-from typing import Any, TypeVar
+from typing import Any, Self
 
 from simple_classproperty import classproperty
-from typing_extensions import Self
 
 from . import base
 
-T = TypeVar("T", bound="Path")
 
-
-def enable_classproperties(cls: type[T]) -> None:  # pragma: nocover
+def enable_classproperties(cls: type) -> None:  # pragma: nocover
     for name, method in vars(cls).items():
         if isinstance(method, classmethod):
             wrapped_method = method.__func__
@@ -28,9 +25,7 @@ class PropertyMeta(abc.ABCMeta):
     ) -> "PropertyMeta":
         meta_class = super().__new__(cls, name, bases, attributes)
         if sys.version_info >= (3, 13):
-            enable_classproperties(
-                meta_class,  # type: ignore[arg-type]
-            )  # pragma: nocover
+            enable_classproperties(meta_class)  # pragma: nocover
         return meta_class
 
 

{superpathlib-2.0.14 → superpathlib-2.1.1}/src/superpathlib/content_properties.py

@@ -1,10 +1,10 @@
 from __future__ import annotations
 
-import json
 import typing
 from typing import Any
 
-from . import base
+from . import metadata_properties
+from .utils import catch_missing
 
 if typing.TYPE_CHECKING:  # pragma: nocover
     from collections.abc import Iterable
@@ -12,12 +12,7 @@ if typing.TYPE_CHECKING:  # pragma: nocover
     from numpy.typing import NDArray
 
 
-# Lazy imports for:
-# - performance optimization
-# - enabling optional dependencies
-
-
-class Path(base.Path):
+class Path(metadata_properties.Path):
     """
     Properties to read & write content in different formats.
     """
@@ -31,11 +26,12 @@ class Path(base.Path):
         self.write_bytes(value)
 
     @property
+    @catch_missing(default="")
     def text(self) -> str:
         return self.read_text()
 
     @text.setter
-    def text(self, value: str | Any) -> None:
+    def text(self, value: object) -> None:
         self.write_text(str(value))
 
     @property
@@ -56,31 +52,48 @@ class Path(base.Path):
         self.lines = typing.cast("list[str]", lines)
 
     @property
-    def json(self) -> dict[str, Any] | list[Any]:
-        value = json.loads(self.text or "{}")
-        return typing.cast("dict[str, Any] | list[Any]", value)
+    @catch_missing(default=None)
+    def json(self) -> Any:
+        with self.open("rb") as fp:
+            import json
+
+            return json.load(fp)
 
     @json.setter
-    def json(self, content: dict[Any, Any] | list[Any]) -> None:
-        self.text = json.dumps(content)
+    def json(self, content: Any) -> None:
+        import json
+
+        with self.open("w") as fp:
+            json.dump(content, fp)
 
     @property
-    def yaml(self) -> dict[str, Any] | list[Any]:
-        import yaml
+    @catch_missing(default=None)
+    def yaml(self) -> Any:
+        with self.open("rb") as fp:
+            import yaml
 
-        # C implementation much faster but only supported on Linux
-        Loader: type[yaml.CFullLoader | yaml.FullLoader] = (  # noqa: N806
-            yaml.CFullLoader if hasattr(yaml, "CFullLoader") else yaml.FullLoader
-        )
-        return yaml.load(self.text, Loader=Loader) or {}  # noqa: S506
+            # C implementation much faster
+            loader = yaml.CSafeLoader if yaml.__with_libyaml__ else yaml.SafeLoader
+            return yaml.load(fp, Loader=loader)  # noqa: S506
 
     @yaml.setter
-    def yaml(self, value: dict[str, Any] | list[Any]) -> None:
+    def yaml(self, value: Any) -> None:
         import yaml
 
-        # C implementation much faster but only supported on Linux
-        Dumper = yaml.CDumper if hasattr(yaml, "CDumper") else yaml.Dumper  # noqa: N806
-        self.text = yaml.dump(value, Dumper=Dumper, width=1024)
+        # C implementation much faster
+        dumper = yaml.CSafeDumper if yaml.__with_libyaml__ else yaml.SafeDumper
+        with self.open("w") as fp:
+            yaml.dump(value, fp, Dumper=dumper, width=1024)
+
+    @property
+    def cached_yaml(self) -> Any:
+        cache_file = self.with_name(self.name + ".cache")
+        mtime = self.mtime
+        exists = mtime > 0
+        if exists and cache_file.mtime != mtime:
+            cache_file.json = self.yaml
+            cache_file.mtime = mtime
+        return cache_file.json if exists else None
 
     @property
     def numpy(self) -> NDArray[Any]:

superpathlib-2.1.1/src/superpathlib/encrypted.py

@@ -0,0 +1,79 @@
+import io
+import subprocess
+from functools import cache
+from types import TracebackType
+from typing import IO, Any, cast
+
+from package_utils.secrets_ import load_secret
+
+from .path import Path
+
+
+class EncryptedPath(Path):
+    def open(  # type: ignore[override]
+        self,
+        mode: str = "r",
+        buffering: int = -1,  # noqa: ARG002
+        encoding: str | None = None,
+        errors: str | None = None,
+        newline: str | None = None,
+    ) -> IO[Any]:
+        access = mode.replace("b", "").replace("t", "")
+        writing = {"r": False, "w": True}[access]
+        buffer = EncryptedFile(Path(self), writing=writing)
+        return (
+            buffer
+            if "b" in mode
+            else EncryptedTextFile(buffer, encoding, errors, newline)
+        )
+
+
+class EncryptedFile(io.BytesIO):
+    def __init__(self, path: Path, *, writing: bool) -> None:
+        self.path = path
+        self.writing = writing
+        plaintext = b"" if writing else run_gpg(path.read_bytes(), "--decrypt")
+        super().__init__(plaintext)
+
+    def __exit__(
+        self,
+        exception_type: type[BaseException] | None,
+        exception: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.cancel_write_if_failed(exception_type)
+        super().__exit__(exception_type, exception, traceback)
+
+    def cancel_write_if_failed(
+        self,
+        exception_type: type[BaseException] | None,
+    ) -> None:
+        self.writing &= exception_type is None
+
+    def close(self) -> None:
+        if not self.closed and self.writing:
+            self.path.write_bytes(run_gpg(self.getvalue(), "--symmetric"))
+        super().close()
+
+
+class EncryptedTextFile(io.TextIOWrapper):
+    def __exit__(
+        self,
+        exception_type: type[BaseException] | None,
+        exception: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        cast("EncryptedFile", self.buffer).cancel_write_if_failed(exception_type)
+        super().__exit__(exception_type, exception, traceback)
+
+
+def run_gpg(data: bytes, *options: str) -> bytes:
+    command = ("gpg", "--passphrase-fd", "0", "--batch", "--quiet", *options)
+    input_ = f"{load_passphrase()}\n".encode() + data
+    process = subprocess.run(command, input=input_, stdout=subprocess.PIPE, check=True)  # noqa: S603
+    return process.stdout
+
+
+@cache
+def load_passphrase() -> str:
+    return load_secret("file encryption password")