superpathlib 1.0.1__py2.py3-none-any.whl

plib/__init__.py

@@ -0,0 +1 @@
+from .plib import Path

plib/plib.py

@@ -0,0 +1,529 @@
+from __future__ import annotations  # https://www.python.org/dev/peps/pep-0563/
+
+import io
+import json
+import mimetypes
+import os
+import pathlib
+import shutil
+import subprocess
+import tempfile
+import time
+from collections.abc import Iterable
+from functools import cached_property, wraps
+from typing import Any
+
+from .utils import find_first_match
+
+# Long import times relative to their usage frequency: lazily imported
+# import yaml
+# from datatime import datetime
+# from .tags import XDGTags
+
+
+def catch_missing(default=None):
+    def wrap_function(func):
+        @wraps(func)
+        def wrap_args(*args, **kwargs):
+            try:
+                res = func(*args, **kwargs)
+            except FileNotFoundError:
+                res = default
+            return res
+
+        return wrap_args
+
+    return wrap_function
+
+
+def create_parent_on_missing(func):
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        try:
+            res = func(*args, **kwargs)
+        except FileNotFoundError:
+            path = args[0]
+            path.create_parent()
+            res = func(*args, **kwargs)
+        return res
+
+    return wrapper
+
+
+def create_parent(func):
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        path = func(*args, **kwargs)
+        path.create_parent()
+        return path
+
+    return wrapper
+
+
+class Path(pathlib.Path):
+    """Extend pathlib functionality and enable further extensions by
+    inheriting.
+    """
+
+    _flavour = (
+        pathlib._windows_flavour if os.name == "nt" else pathlib._posix_flavour
+    )  # _flavour attribute needs to inherited explicitely from pathlib
+
+    """
+    Overwrite existing methods with exception handling and default values
+    """
+
+    @create_parent_on_missing
+    def touch(self, mode=0o666, exist_ok=True, mtime=None):
+        super().touch(mode=mode, exist_ok=exist_ok)
+        if mtime is not None:
+            self.mtime = mtime  # set time after touch or it is immediately overwritten
+
+    @catch_missing(default=0)
+    def rmdir(self):
+        return super().rmdir()
+
+    def iterdir(self, missing_ok=True):
+        if self.exists() or not missing_ok:
+            yield from super().iterdir()
+
+    def rename(self, target):
+        target = Path(target)
+        target.create_parent()
+        try:
+            target = super().rename(target)
+        except OSError:
+            target = shutil.move(self, target)
+        return target
+
+    def create_parent(self):
+        self.parent.mkdir(parents=True, exist_ok=True)
+        return self.parent
+
+    def with_nonexistent_name(self):
+        path = self
+        if path.exists():
+            stem = path.stem
+
+            def with_number(i: int):
+                return path.with_stem(f"{stem} ({i})")
+
+            def nonexistent(i):
+                return not with_number(i).exists()
+
+            first_free_number = find_first_match(nonexistent)
+            path = with_number(first_free_number)
+
+        return path
+
+    def with_timestamp(self):
+        from datetime import datetime  # noqa: autoimport
+
+        timestamp = datetime.fromtimestamp(int(time.time()))  # precision up to second
+        return self.with_stem(f"{self.stem} {timestamp}")
+
+    def open(self, mode="r", **kwargs):
+        try:
+            res = super().open(mode, **kwargs)
+        except FileNotFoundError:
+            if "w" in mode or "a" in mode:
+                # exist_ok=True: catch race conditions when calling multiple times
+                self.create_parent()
+                res = super().open(mode, **kwargs)
+            else:
+                encrypted = self.encrypted.exists()
+                if "b" in mode:
+                    byte_content = self.encrypted.byte_content if encrypted else b""
+                    res = io.BytesIO(byte_content)
+                else:
+                    text = self.encrypted.text if encrypted else ""
+                    res = io.StringIO(text)
+            return res
+        return res
+
+    """
+    Properties to read & write content in different formats
+    """
+
+    @property
+    def byte_content(self) -> bytes:
+        return self.read_bytes()
+
+    @byte_content.setter
+    def byte_content(self, value: bytes) -> None:
+        self.write_bytes(value)
+
+    @property
+    def text(self) -> str:
+        return self.read_text()
+
+    @text.setter
+    def text(self, value: Any) -> None:
+        self.write_text(str(value))
+
+    @property
+    def lines(self) -> list[str]:
+        lines = self.text.strip().splitlines()
+        lines = [line for line in lines if line]
+        return lines
+
+    @lines.setter
+    def lines(self, lines: Iterable[Any]) -> None:
+        self.text = "\n".join(str(line) for line in lines)
+
+    @property
+    def json(self):
+        return json.loads(self.text or "{}")
+
+    @json.setter
+    def json(self, content):
+        self.text = json.dumps(content)
+
+    @property
+    def yaml(self):
+        import yaml  # noqa: autoimport
+
+        # C implementation much faster but only supported on Linux
+        Loader = yaml.CFullLoader if hasattr(yaml, "CFullLoader") else yaml.FullLoader
+        return yaml.load(self.text, Loader=Loader) or {}
+
+    @yaml.setter
+    def yaml(self, value):
+        import yaml  # noqa: autoimport
+
+        # C implementation much faster but only supported on Linux
+        Dumper = yaml.CDumper if hasattr(yaml, "CDumper") else yaml.Dumper
+        self.text = yaml.dump(value, Dumper=Dumper, width=1024)
+
+    @property
+    def encrypted(self):
+        path = self
+        encryption_suffix = ".gpg"
+        if path.suffix != encryption_suffix:
+            path = path.with_suffix(path.suffix + encryption_suffix)
+        return EncryptedPath(path)
+
+    """
+    Properties to read & write metadata
+    """
+
+    @property
+    @catch_missing(default=0.0)
+    def mtime(self):
+        return self.stat().st_mtime
+
+    @mtime.setter
+    def mtime(self, time: float):
+        os.utime(self, (time, time))  # set create time as well
+
+        try:
+            subprocess.run(("touch", "-d", "@%f" % time, self))
+        except subprocess.CalledProcessError:
+            pass  # Doesn't work on Windows
+
+    @property
+    def tags(self):
+        from .tags import XDGTags  # noqa: autoimport
+
+        return XDGTags(self).get()
+
+    @tags.setter
+    def tags(self, *values):
+        from .tags import XDGTags  # noqa: autoimport
+
+        if len(values) == 1 and values[0] in (None, []):
+            XDGTags(self).clear()
+        else:
+            XDGTags(self).set(*values)
+
+    @property
+    def tag(self):
+        return self.tags[0] if self.tags else None
+
+    @tag.setter
+    def tag(self, value):
+        self.tags = value
+
+    @property
+    @catch_missing(default=0)
+    def size(self):
+        return self.stat().st_size
+
+    @property
+    def is_root(self):
+        path = self
+        while not path.exists():
+            path = path.parent
+        return path.owner() == "root"
+
+    @property
+    def has_children(self):
+        return next(self.iterdir(), None) is not None if self.is_dir() else False
+
+    @property
+    def number_of_children(self):
+        return sum(1 for _ in self.iterdir()) if self.is_dir() else 0
+
+    @property
+    def filetype(self):
+        filetype = mimetypes.guess_type(self)[0]
+        if filetype:
+            filetype = filetype.split("/")[0]
+        return filetype
+
+    """
+    Additional functionality
+    """
+
+    def copy_to(self, dest: Path, include_properties=True):
+        dest.byte_content = self.byte_content
+        if include_properties:
+            self.copy_properties_to(dest)
+
+    def copy_properties_to(self, dest: Path):
+        for path in dest.find():
+            path.tag = self.tag
+            path.mtime = self.mtime
+
+    @cached_property
+    def archive_format(self):
+        return shutil._find_unpack_format(str(self))
+
+    def unpack_if_archive(self, extract_dir: Path = None, recursive=True):
+        if self.archive_format is not None:
+            self.unpack(extract_dir, recursive=recursive)
+
+    def unpack(
+        self,
+        extract_dir: Path | None = None,
+        remove_existing: bool = True,
+        preserve_properties: bool = True,
+        remove_original: bool = True,
+        format: str = None,
+        recursive: bool = True,
+    ):
+        def cleanup(path: Path):
+            (path / "__MACOSX").rmtree()
+            subfolder = path / path.name
+            if subfolder.exists() and path.number_of_children == 1:
+                subfolder.pop_parent()
+
+        if format is None:
+            format = self.archive_format
+
+        if extract_dir is None:
+            extract_name = self.name
+            unpack_info = shutil._UNPACK_FORMATS[format]
+            for archive_ext in unpack_info[0]:
+                if extract_name.endswith(archive_ext):
+                    extract_name = extract_name.replace(archive_ext, "")
+            extract_dir = self.with_name(extract_name)
+
+        if remove_existing:
+            extract_dir.rmtree()
+
+        shutil.unpack_archive(self, extract_dir=extract_dir, format=format)
+
+        cleanup(extract_dir)
+        if preserve_properties:
+            self.copy_properties_to(extract_dir)
+        if remove_original:
+            self.unlink()
+
+        if recursive:
+            for path in extract_dir.find():
+                path.unpack_if_archive()
+
+    def pop_parent(self):
+        """Remove first parent from path in filesystem."""
+        dest = self.parent.parent / self.name
+        parent = self.parent
+        temp_dest = dest.with_nonexistent_name()  # can only move to nonexisting path
+
+        self.rename(temp_dest)
+
+        if not parent.has_children:
+            parent.rmdir()
+        if not parent.exists():
+            temp_dest.rename(dest)
+        else:
+            # merge in existing folder
+            shutil.copytree(temp_dest, dest, dirs_exist_ok=True)
+            temp_dest.rmtree()
+
+    def is_empty(self):
+        return (
+            not self.exists()
+            or (self.is_dir() and next(self.iterdir(), None) is None)
+            or (self.is_file() and self.size == 0)
+        )
+
+    def load_yaml(self, trusted=False):
+        """
+        :param trusted: if the path is trusted, an unsafe loader
+                        can be used to instantiate any object
+        :return: Content in path that contains yaml format
+        """
+        import yaml  # noqa: autoimport
+
+        loader = yaml.CUnsafeLoader if trusted else yaml.CFullLoader
+        return yaml.load(self.text, Loader=loader) or {}
+
+    def update(self, value):
+        # only read and write if value to add not empty
+        if value:
+            updated_content = self.yaml | value
+            self.yaml = updated_content
+            return updated_content
+
+    def find(
+        self,
+        condition=None,
+        exclude=None,
+        recurse_on_match=False,
+        follow_symlinks=False,
+        only_folders=False,
+    ):
+        """
+        Find all subpaths under path that match condition.
+
+        only_folders option can be used for efficiency reasons
+        """
+        if condition is None:
+            recurse_on_match = True
+
+            def condition(_):
+                return True
+
+        if exclude is None:
+
+            def exclude(_):
+                return False
+
+        to_traverse = [self] if self.exists() else []
+        while to_traverse:
+            path = to_traverse.pop(0)
+
+            if not exclude(path):
+                match = condition(path)
+                if match:
+                    yield path
+
+                if not match or recurse_on_match:
+                    if only_folders or path.is_dir():
+                        try:
+                            for child in path.iterdir():
+                                if follow_symlinks or not child.is_symlink():
+                                    if not only_folders or child.is_dir():
+                                        to_traverse.append(child)
+                        except PermissionError:
+                            pass  # skip folders that do not allow listing
+
+    def rmtree(self, missing_ok=False, remove_root=True):
+        for path in self.iterdir():
+            if path.is_dir():
+                path.rmtree()
+            else:
+                path.unlink()
+        if remove_root:
+            self.rmdir()
+
+    def subpath(self, *parts):
+        path = self
+        for part in parts:
+            path /= part.replace(self._flavour.sep, "_")
+        return path
+
+    @classmethod
+    def tempfile(cls, **kwargs) -> Path:
+        """
+        Usage:
+            with Path.tempfile() as tmp:
+                run_command(log_file=tmp)
+                logs = tmp.text
+            process_logs(logs)
+        """
+        _, path = tempfile.mkstemp(**kwargs)
+        return cls(path)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.unlink(missing_ok=True)
+
+    """
+    Common folders: use properties and classmethods to guarantee
+                    the same behavior for all derived classes
+    """
+
+    @classmethod
+    @property
+    def HOME(cls) -> Path:
+        return cls.home()
+
+    @classmethod
+    @property
+    def docs(cls) -> Path:
+        return cls.HOME / "Documents"
+
+    @classmethod
+    @property
+    def scripts(cls) -> Path:
+        return cls.docs / "Scripts"
+
+    @classmethod
+    @property
+    def script_assets(cls) -> Path:
+        return cls.scripts / "assets"
+
+    @classmethod
+    @property
+    def assets(cls) -> Path:
+        """Often overwritten by child classes for specific project."""
+        return cls.script_assets
+
+    @classmethod
+    @property
+    def draft(cls) -> Path:
+        return cls.docs / "draft.txt"
+
+
+class EncryptedPath(Path):
+    @cached_property
+    def password(self):
+        command = 'ksshaskpass -- "Enter passphrase for file encryption: "'
+        return subprocess.getoutput(command)
+
+    @property
+    def encryption_command(self):
+        return *self.decryption_command, "-c"
+
+    @property
+    def decryption_command(self):
+        return "gpg", "--passphrase", self.password, "--batch", "--quiet", "--yes"
+
+    def read_bytes(self) -> bytes:
+        encrypted_bytes = super().read_bytes()
+        if encrypted_bytes:
+            process = subprocess.Popen(
+                self.decryption_command, stdin=subprocess.PIPE, stdout=subprocess.PIPE
+            )
+            decrypted_bytes, _ = process.communicate(input=encrypted_bytes)
+        else:
+            decrypted_bytes = encrypted_bytes
+        return decrypted_bytes
+
+    def write_bytes(self, data: bytes) -> int:
+        process = subprocess.Popen(
+            self.encryption_command, stdin=subprocess.PIPE, stdout=subprocess.PIPE
+        )
+        encrypted_data = process.communicate(input=data)[0]
+        return super().write_bytes(encrypted_data)
+
+    def read_text(self, encoding: str | None = ..., errors: str | None = ...) -> str:
+        return self.read_bytes().decode()
+
+    def write_text(self, data: str, **_) -> int:
+        data = data.encode()
+        return self.write_bytes(data)

plib/tags.py

@@ -0,0 +1,39 @@
+try:
+    import xattr
+
+except:
+    xattr = None  # Don't fail if xattr not supported (Windows)
+
+delim = ","
+default_tag_name = "user.xdg.tags"
+
+"""
+More user-friendly way to interact with tags.
+- Work with strings and integers instead of bytes
+- Use xdg tags by default -> useful for filemanager that can order according to this tag
+"""
+
+
+class XDGTags:
+    def __init__(self, path, name=default_tag_name):
+        self.tags = xattr.xattr(path) if xattr is not None else None
+        self.name = name
+
+    def get(self):
+        tags = set({})
+        if self.tags and self.tags.has_key(self.name):
+            tags = self.tags[self.name].decode().strip().split(delim)
+        return tags
+
+    def set(self, *values, name=default_tag_name):
+        """
+        :param values: tag values to set
+        """
+        if self.tags is not None:
+            values = {str(v).zfill(4) if isinstance(v, int) else str(v) for v in values}
+            values = delim.join(values).encode()
+            self.tags.set(self.name, values)
+
+    def clear(self):
+        if self.tags is not None and self.tags.has_key(self.name):
+            self.tags.remove(self.name)

plib/utils.py

@@ -0,0 +1,25 @@
+from typing import Callable
+
+
+def find_first_match(condition: Callable) -> int:
+    """
+    :param condition: Condition that number needs to match.
+                      The condition is assumed to be valid for all integers staring from an initial value.
+    :return: First integer for which condition is valid.
+    """
+
+    # exponential increase for logarithmic search
+    upper_bound = 1
+    while not condition(upper_bound):
+        upper_bound *= 2
+
+    # narrow down range of first match = [lower_bound + 1, upper_bound] until one value left
+    lower_bound = upper_bound // 2
+    while lower_bound + 1 < upper_bound:
+        middle = (upper_bound + lower_bound) // 2
+        if condition(middle):
+            upper_bound = middle
+        else:
+            lower_bound = middle
+
+    return upper_bound

superpathlib-1.0.1.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 quintenroets
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

superpathlib-1.0.1.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.1
+Name: superpathlib
+Version: 1.0.1
+Summary: extended pathlib
+Home-page: https://github.com/quintenroets/superpathlib
+Author: Quinten Roets
+Author-email: quinten.roets@gmail.com
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML
+
+# Superpathlib
+Superpathlib offers Path objects with functionality extended from pathlib to maximize your productivity with a minimal amount of code.
+
+## Usage
+
+```shell
+from plib import Path
+path = Path(filename)
+```
+
+### 1) Use properties to read & write path content in different formats
+* text
+* byte_content
+* lines
+* yaml
+* json
+
+examples: 
+
+```shell
+path.json = {key: value}
+
+for line in path.lines:
+    if interesting(line):
+        process(line)
+```
+### 2) Use instance properties to get/set file metadata:
+* get:
+    * size: filesize
+    * is_root: whether the owner of the file is a root user
+    * has_children: whether a path has children
+    * number_of_children: number of children in a folder
+    * filetype: content type of a file
+* 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":
+    process(path)
+```
+### 3) Use class properties to access commonly used folders:
+* docs
+* assets
+* ..
+
+example: 
+
+```shell
+names_path = Path.assets / 'names'
+names = names_path.lines
+```
+### 4) Use additional functionality
+* 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
+* tempfile(): create temporary file that can be used as context manager
+* unpack(): extract archive(zip, tar, ..) file to desired folder
+* pop_parent(): remove first parent from path in filesystem
+
+examples: 
+
+```shell
+with Path.tempfile() as tmp:
+    do_work(logfile=tmp)
+    log = tmp.text
+process(log)
+
+condition = lambda p: (p / '.git').exists()
+for git_path in root.find(condition):
+    process_git(git_path)
+```
+### 5) Enhance existing functionality
+* Automatically create parents when writing files, creating new files, renaming files, ..
+* Return default values when path does not exist (e.g. size = 0, lines=[])
+
+### 6) Inherit from Path to define your own additional functionality:
+
+example: 
+
+```shell
+from plib import Path as BasePath
+
+class Path(BasePath):
+    def count_children(self):
+        return sum(1 for _ in self.iterdir())
+```
+
+This only works if you inherit from plib and not from the builtin pathlib
+
+
+## Installation
+
+```shell
+pip install superpathlib
+requires python version >= 3.9
+```

superpathlib-1.0.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+plib/__init__.py,sha256=ibGdCuiCzlbTOWSQKvy6O1DnBkSiRBLqdlW0dPnFQAg,23
+plib/plib.py,sha256=0spcnXus4C45hKeqpbf4QZji0fWtATK3HVCVMc1bx-E,15026
+plib/tags.py,sha256=xXovH46eRim-JSM0b2MAHY-uhqg9VXofJeqyHiR7I1s,1152
+plib/utils.py,sha256=bcAbMWUnmAdLdJ0bNhKKwYmH0QRlrbO_jb3J8IBIy_Y,808
+superpathlib-1.0.1.dist-info/LICENSE,sha256=coy5XgzwxQweNZLEXayFiokEKOaK232vkE8TFfBDbFw,1069
+superpathlib-1.0.1.dist-info/METADATA,sha256=9M_6w4l152AuYr0hM18DccvQisQezMZOELX04COBeLE,2830
+superpathlib-1.0.1.dist-info/WHEEL,sha256=a-zpFRIJzOq5QfuhBzbhiA1eHTzNCJn8OdRvhdNX0Rk,110
+superpathlib-1.0.1.dist-info/top_level.txt,sha256=-V_xRFwJBbUgjbv9DhvFKSZizOCXvDIGZcwqg-jGvks,5
+superpathlib-1.0.1.dist-info/RECORD,,

superpathlib-1.0.1.dist-info/WHEEL

@@ -0,0 +1,6 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.40.0)
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any
+

superpathlib-1.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+plib