path-tools-med 0.1.0__py3-none-any.whl

path_tools_med/__init__.py

@@ -0,0 +1,15 @@
+__version__ = "0.0.1"
+
+from .tools import (
+    PathRerooter,
+    backup_path,
+    get_highest_backup_version,
+    make_versioned_backup,
+)
+
+__all__ = [
+    "PathRerooter",
+    "backup_path",
+    "get_highest_backup_version",
+    "make_versioned_backup",
+]

path_tools_med/tools.py

@@ -0,0 +1,142 @@
+import logging
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def backup_path(path: Path | str, backup_extension: str = ".bak") -> Path:
+    """
+    Rename the path object specified by `path` to `path.backup_extension`.
+    If there is an existing `path.backup_extension`, file it will be renamed
+    with a version number extension using `make_versioned_backup`.
+
+    WARNING: The operations are not atomic and so it is possible for another
+    process to create another `path.backup_extension` or `path.backup_extension.~#~`
+    file in between the time that this process determines the file to create doesn't
+    exist and when it renames the file.  If this happens the earlier created file
+    will be overwritten, see `pathlib.Path.replace`.
+
+    :param path: the path to the file to be renamed
+    :param backup_extension: the backup extension to be appended
+    :return: the new path object
+    """
+    this_path = Path(path)
+    path_backup = Path(str(this_path) + backup_extension)
+    if path_backup.exists():
+        make_versioned_backup(path_backup)
+    return this_path.replace(path_backup)
+
+
+def make_versioned_backup(path: Path) -> Path:
+    """
+    Rename the path object specified with a version number extension
+    that will be greater than any existing version number.
+
+    WARNING: The operations are not atomic and so it is possible for another
+    process to create another `path.backup_extension` or `path.backup_extension.~#~`
+    file in between the time that this process determines the file to create doesn't
+    exist and when it renames the file.  If this happens the earlier created file
+    will be overwritten, see `pathlib.Path.replace`.
+
+    :param path: the path to the file to be renamed
+    :return: the new path object
+    """
+    this_path = Path(path)
+    return this_path.replace(
+        f"{this_path}.~{get_highest_backup_version(this_path) + 1}~",
+    )
+
+
+def get_highest_backup_version(path: Path | str) -> int:
+    """
+    Return the highest existing backup version number for existing `path.~#~` files.
+    If no such files exist return 0.
+
+    :param path:
+    :return: hightest existing backup version number
+    """
+    versions = [0]
+    this_path = Path(path)
+    versions.extend(
+        [
+            int(x[x.rindex("~", 0, -1) + 1 : -1])
+            for x in map(str, this_path.parent.glob(f"{this_path.name}.~*~"))
+        ],
+    )
+    return max(versions)
+
+
+class PathRerooter:
+    """Class to facilitate converting paths with old-root to new-root.
+
+    This is not a replacement for `shutil.copytree`.  This does not actually rename
+    any files.  It just creates the updated path, and so is useful for updating data
+    files containing paths that have been changed.
+    """
+
+    def __init__(
+        self,
+        old_path_root: Path | str | None,
+        new_path_root: Path | str | None,
+        *_: Any,
+        ignore: bool = False,
+    ):
+        """
+        Constructor
+
+        If both roots are None, then the fix operation quietly does nothing.
+
+        If ignore is true, then the fix operation quietly does nothing for
+        paths that do not start with the old root.
+        This applies to all invocations of `fix(path)` called on this
+        `PathRerooter` object.
+        To only selectively ignore these situations leave `ignore=False`
+        in the constructor,
+        but use `fix(path, ignore=True)` on the pertinant invocations.
+
+        :param old_path_root: the old root path to be converted from
+        :param new_path_root: the new root path to be converted to
+        :param ignore: if true, quietly just return paths that do not
+                       start with the old root.
+        """
+        self.noop = old_path_root is None and new_path_root is None
+        self.old_path_root_parts = list(Path(old_path_root).parts) if old_path_root else []
+        self.new_path_root_parts = list(Path(new_path_root).parts) if new_path_root else []
+        self.ignore = ignore
+
+    def fix(self, path: Path | str, *_: Any, ignore: bool = False) -> Path:
+        """
+        Apply the defined root conversion to the specified path returning
+        the new path object.
+
+        No files are renamed, the new `pathlib.Path` object is just created.
+
+        A RuntimeError is raised if the path does not start with the old-path,
+        unless either `ignore=True` is passed on this invocation,
+        or `ignore=True` was set in the constructor.
+
+        :param path: path to be converted
+        :param ignore: if true, quietly just return paths that do not start
+                       with the old root.
+        :return: the converted path
+        """
+        this_path = Path(path)
+        if self.noop:
+            return this_path
+
+        old_path_parts = list(this_path.parts)
+        for part in self.old_path_root_parts:
+            if part == old_path_parts[0]:
+                old_path_parts.pop(0)
+            elif ignore or self.ignore:
+                return this_path
+            else:
+                msg = (
+                    f"old_path_part '{part}' does not match "
+                    f"'{old_path_parts[0]}' in path '{this_path}'"
+                )
+                logger.error(msg)
+                raise RuntimeError(msg)
+        new_path_parts = [*self.new_path_root_parts, *old_path_parts]
+        return Path().joinpath(*new_path_parts)

path_tools_med-0.1.0.dist-info/METADATA

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: path-tools-med
+Version: 0.1.0
+Summary: A few path related functions I wish pathlib supported.
+License-Expression: MIT
+License-File: LICENSE
+Author: Malcolm E. Davis
+Author-email: malcolm3davis@gmail.com
+Requires-Python: >=3.10
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Project-URL: Documentation, https://malcolm3davis.github.io/path-tools-med
+Project-URL: Homepage, https://malcolm3davis.github.io/path-tools-med
+Project-URL: Repository, https://github.com/malcolm3davis/path-tools-med
+Description-Content-Type: text/markdown
+
+# Malcolm's Path Tools
+
+[![PyPI](https://img.shields.io/pypi/v/path-tools-med?style=flat-square)](https://pypi.python.org/pypi/path-tools-med/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/path-tools-med?style=flat-square)](https://pypi.python.org/pypi/path-tools-med/)
+[![PyPI - License](https://img.shields.io/pypi/l/path-tools-med?style=flat-square)](https://pypi.python.org/pypi/path-tools-med/)
+[![Coookiecutter - Malcolm](https://img.shields.io/badge/cookiecutter-Malcolm_Wolt-00c2e8?style=flat-square&logo=cookiecutter&logoColor=D4AA00&link=https://github.com/malcolm-3/malcolm-3-python-package-cookiecutter)](https://github.com/woltapp/wolt-python-package-cookiecutter)
+
+
+---
+
+**Documentation**: [https://malcolm3davis.github.io/path-tools-med](https://malcolm3davis.github.io/path-tools-med)
+
+**Source Code**: [https://github.com/malcolm3davis/path-tools-med](https://github.com/malcolm3davis/path-tools-med)
+
+**PyPI**: [https://pypi.org/project/path-tools-med/](https://pypi.org/project/path-tools-med/)
+
+---
+
+A few path related functions I wish pathlib supported.
+
+## Usage
+
+- ``make_versioned_backup(path: Path|str) -> Path``
+  - Renames the specified path adding a ``.~#~`` style version number that is higher than any existing version number.
+- ``backup_path(paht: Path|str, backup_extension=".bak") -> Path``
+  - Renames the specified file adding the backup_extension.
+    If that backup file already exists it renamed with ``make_versioned_backup``.
+- ``get_highest_backup_version(path: Path|str) -> int``
+  - Utility function to see what the current highest backup version number exists.
+
+It also provides the ``PathRerooter`` class that can be used to update path objects to have
+a new initial root path.
+
+```python
+r = PathRerooter("/old/root/path", "/new/root/path/is/here")
+assert r.fix("/old/root/path/some/file.txt") == "/new/root/path/is/here/some/file.txt"
+```
+
+## Installation
+
+```sh
+pip install path-tools-med
+```
+
+## Development
+
+* Clone this repository
+* Requirements:
+  * [Poetry](https://python-poetry.org/)
+  * Python 3.8+
+* Create a virtual environment and install the dependencies
+
+```sh
+poetry install
+```
+
+* Activate the virtual environment
+
+```sh
+poetry shell
+```
+
+### Testing
+
+```sh
+pytest
+```
+
+### Documentation
+
+The documentation is automatically generated from the content of the [docs directory](https://github.com/malcolm3davis/path-tools-med/tree/master/docs) and from the docstrings
+ of the public signatures of the source code. The documentation is updated and published as a [Github Pages page](https://pages.github.com/) automatically as part each release.
+
+### Releasing
+
+Trigger the [Draft release workflow](https://github.com/malcolm3davis/path-tools-med/actions/workflows/draft_release.yml)
+(press _Run workflow_). This will update the changelog & version and create a GitHub release which is in _Draft_ state.
+
+Find the draft release from the
+[GitHub releases](https://github.com/malcolm3davis/path-tools-med/releases) and publish it. When
+ a release is published, it'll trigger [release](https://github.com/malcolm3davis/path-tools-med/blob/master/.github/workflows/release.yml) workflow which creates PyPI
+ release and deploys updated documentation.
+
+### Pre-commit
+
+Pre-commit hooks run all the auto-formatting (`ruff format`), linters (e.g. `ruff` and `mypy`), and other quality
+ checks to make sure the changeset is in good shape before a commit/push happens.
+
+You can install the hooks with (runs for each commit):
+
+```sh
+pre-commit install
+```
+
+Or if you want them to run only for each push:
+
+```sh
+pre-commit install -t pre-push
+```
+
+Or if you want e.g. want to run all checks manually for all files:
+
+```sh
+pre-commit run --all-files
+```
+
+---
+
+This project was generated using the [wolt-python-package-cookiecutter](https://github.com/woltapp/wolt-python-package-cookiecutter) template.
+

path_tools_med-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+path_tools_med/__init__.py,sha256=uW5wo65sVt_IZYJgBw76wDlMJmvWDJeQlXoURWYQrpE,257
+path_tools_med/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+path_tools_med/tools.py,sha256=ji-u3Th-GMcH_8vAJdVw22wfMYZp6UwoY63ER2nh4Kc,5395
+path_tools_med-0.1.0.dist-info/METADATA,sha256=H0es4XRs2JS1etIVTpeYNDjhVj5JNCBAp13rAxymcu4,4965
+path_tools_med-0.1.0.dist-info/WHEEL,sha256=EGEvSphFYqXKs23-kQBeyNoJP1nrT8ZJKQoi5p5DYL8,88
+path_tools_med-0.1.0.dist-info/licenses/LICENSE,sha256=rELAJLOKMmhrGVEGrfHFl_8KpjgFqbKIb3NLe7Esz1g,1109
+path_tools_med-0.1.0.dist-info/RECORD,,

path_tools_med-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.4.0
+Root-Is-Purelib: true
+Tag: py3-none-any

path_tools_med-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Malcolm E. Davis <malcolm3davis@gmail.com>
+
+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.