path-tools-med 0.1.0__tar.gz

path_tools_med-0.1.0/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.

path_tools_med-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,109 @@
+# 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/pyproject.toml

@@ -0,0 +1,135 @@
+[project]
+name = "path-tools-med"
+version = "0.1.0"
+description = "A few path related functions I wish pathlib supported."
+authors = [
+    {name = "Malcolm E. Davis", email = "malcolm3davis@gmail.com"},
+]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Documentation = "https://malcolm3davis.github.io/path-tools-med"
+Homepage = "https://malcolm3davis.github.io/path-tools-med"
+Repository = "https://github.com/malcolm3davis/path-tools-med"
+
+[tool.poetry]
+packages = [
+    { include = "path_tools_med", from = "src" }
+]
+
+[tool.poetry.dependencies]
+python = ">=3.10.1, <4.0"
+
+[tool.poetry.group.dev.dependencies]
+mkdocstrings = {version = ">=0.23", extras = ["python"]}
+mkdocs-material = "*"
+mypy = "*"
+pre-commit = "*"
+pymdown-extensions = "*"
+pytest = "*"
+pytest-github-actions-annotate-failures = "*"
+pytest-cov = "*"
+python-kacl = "*"
+ruff = ">=0.2.0"
+poetry-bumpversion = "^0.3.3"
+
+[build-system]
+requires = ["poetry-core>=2.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+target-version = "py310" # The lowest supported version
+exclude = ["tests/"]
+line-length = 100
+
+[tool.ruff.lint]
+# By default, enable all the lint rules.
+# Add to the ignore list below if you don't want some rules.
+# If you need some ignores for certain modules, see tool.ruff.lint.per-file-ignores below.
+# For individual ignore cases, prefer inline `# noqa`s within the code.
+select = ["ALL"]
+ignore = [
+    "ANN",      # Type hints related, let mypy handle these.
+    "D",        # Docstrings related, way too strict to our taste
+    "COM812",   # missing-trailing-comma
+    ]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "S101",     # "Use of `assert` detected"
+    "ARG",      # "Unused function argument". Fixtures are often unused.
+    "S105",     # "Possible hardcoded password".
+]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.ruff.lint.pep8-naming]
+classmethod-decorators = [
+    "classmethod",
+    "pydantic.validator",
+    "pydantic.root_validator",
+]
+
+[tool.pytest.ini_options]
+addopts = """\
+    --cov path_tools_med \
+    --cov tests \
+    --cov-report term-missing \
+    --no-cov-on-fail \
+"""
+
+[tool.coverage.report]
+fail_under = 100
+exclude_lines = [
+    'if TYPE_CHECKING:',
+    'pragma: no cover'
+]
+
+[tool.mypy]
+# This is the global mypy configuration.
+# Avoid changing this!
+strict = true  # See all the enabled flags `mypy --help | grep -A 10 'Strict mode'`
+disallow_any_unimported = true
+exclude = [
+    'venv/',
+    'tests/'
+    ]
+
+[tool.poetry_bumpversion.file."src/path_tools_med/__init__.py"]
+
+[tool.poetry_bumpversion.file."mkdocs.yml"]
+search = "site_name: \"Malcolm's Path Tools v{current_version}\""
+replace = "site_name: \"Malcolm's Path Tools v{new_version}\""
+
+# If you need to ignore something for some specific module,
+# add overrides for them. Avoid changing the global config!
+# For example:
+# [[tool.mypy.overrides]]
+# module = [
+#  "my_unpyted_dependency1.*",
+#  "my_unpyted_dependency2.*"
+# ]
+# ignore_missing_imports = true
+
+# [[tool.mypy.overrides]]
+# module = [
+#   "tests/my_thing/test_my_thing",
+# ]
+# disallow_untyped_defs = false

path_tools_med-0.1.0/src/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-0.1.0/src/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)