lyutil 0.1.0__tar.gz

lyutil-0.1.0/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leyton Addison-Roach
+
+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.

lyutil-0.1.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: lyutil
+Version: 0.1.0
+Summary: A lightweight collection of everyday Python utilities.
+Keywords: utilities,timestamps,filenames
+Author: Leyton Addison-Roach
+Author-email: Leyton Addison-Roach <git@laddisonroach.com>
+License-Expression: MIT
+License-File: LICENCE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Project-URL: Repository, https://github.com/leyts/lyutil
+Project-URL: Issues, https://github.com/leyts/lyutil/issues
+Description-Content-Type: text/markdown
+
+# lyutil
+
+A lightweight collection of everyday Python utilities.
+
+## Modules
+
+### Timestamps
+
+Embed and extract timestamps in filenames.
+
+```python
+from pathlib import Path
+from lyutil import FileTimestamp
+```
+
+**Add a timestamp to a filename:**
+
+```python
+>>> result = FileTimestamp.add(Path("backup.tar.gz"))
+>>> print(result.file)
+backup_2026-02-25_14-30-00.tar.gz
+>>> print(result.timestamp)
+2026-02-25 14:30:00
+```
+
+**Read the timestamp back:**
+
+```python
+>>> parsed = FileTimestamp.read(result.file)
+>>> print(parsed.file)
+backup.tar.gz
+>>> print(parsed.timestamp)
+2026-02-25 14:30:00
+>>> print(parsed.age)
+0:00:12.345678
+```
+
+## Requirements
+
+Python 3.14+
+
+## Licence
+
+[MIT](LICENCE)

lyutil-0.1.0/README.md

@@ -0,0 +1,44 @@
+# lyutil
+
+A lightweight collection of everyday Python utilities.
+
+## Modules
+
+### Timestamps
+
+Embed and extract timestamps in filenames.
+
+```python
+from pathlib import Path
+from lyutil import FileTimestamp
+```
+
+**Add a timestamp to a filename:**
+
+```python
+>>> result = FileTimestamp.add(Path("backup.tar.gz"))
+>>> print(result.file)
+backup_2026-02-25_14-30-00.tar.gz
+>>> print(result.timestamp)
+2026-02-25 14:30:00
+```
+
+**Read the timestamp back:**
+
+```python
+>>> parsed = FileTimestamp.read(result.file)
+>>> print(parsed.file)
+backup.tar.gz
+>>> print(parsed.timestamp)
+2026-02-25 14:30:00
+>>> print(parsed.age)
+0:00:12.345678
+```
+
+## Requirements
+
+Python 3.14+
+
+## Licence
+
+[MIT](LICENCE)

lyutil-0.1.0/pyproject.toml

@@ -0,0 +1,73 @@
+[project]
+name = "lyutil"
+version = "0.1.0"
+description = "A lightweight collection of everyday Python utilities."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENCE"]
+authors = [
+    { name = "Leyton Addison-Roach", email = "git@laddisonroach.com" },
+]
+requires-python = ">=3.14"
+keywords = ["utilities", "timestamps", "filenames"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/leyts/lyutil"
+Issues = "https://github.com/leyts/lyutil/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "ruff>=0.15.2",
+    "time-machine>=3.2.0",
+    "ty>=0.0.18",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.4,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 79
+
+[tool.ruff.format]
+docstring-code-format = true
+docstring-code-line-length = 20
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "W191",
+    "E111",
+    "E114",
+    "E117",
+    "D206",
+    "D300",
+    "Q000",
+    "Q001",
+    "Q002",
+    "Q003",
+    "COM812",
+    "COM819",
+    "TD",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*.py" = [
+    "ANN201",
+    "D104",
+    "S101",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"

lyutil-0.1.0/src/lyutil/__init__.py

@@ -0,0 +1,11 @@
+"""lyutil — lightweight utility functions."""
+
+from lyutil.exceptions import InvalidPathError, TimestampParseError
+from lyutil.timestamps import FileTimestamp, TimestampedFile
+
+__all__ = [
+    "FileTimestamp",
+    "InvalidPathError",
+    "TimestampParseError",
+    "TimestampedFile",
+]

lyutil-0.1.0/src/lyutil/exceptions.py

@@ -0,0 +1,9 @@
+"""Custom exceptions for lyutil."""
+
+
+class InvalidPathError(ValueError):
+    """Raised when a path has no usable stem."""
+
+
+class TimestampParseError(ValueError):
+    """Raised when a filename does not contain a valid timestamp."""

lyutil-0.1.0/src/lyutil/timestamps.py

@@ -0,0 +1,118 @@
+"""Utilities for embedding timestamps in filenames."""
+
+from datetime import datetime, timedelta
+from typing import TYPE_CHECKING, ClassVar, NamedTuple
+
+from lyutil.exceptions import InvalidPathError, TimestampParseError
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class TimestampedFile(NamedTuple):
+    """A path paired with the timestamp extracted from its filename."""
+
+    file: Path
+    timestamp: datetime
+
+    @property
+    def age(self) -> timedelta:
+        """Time elapsed since the embedded timestamp."""
+        return datetime.now() - self.timestamp  # noqa: DTZ005
+
+
+class FileTimestamp:
+    """Add and read timestamps in filenames."""
+
+    _DT_FORMAT: ClassVar[str] = "%Y-%m-%d_%H-%M-%S"
+    _SEPARATOR: ClassVar[str] = "_"
+
+    @staticmethod
+    def _validate_file(file: Path) -> None:
+        """Raise ``InvalidPathError`` if *file* has no usable stem."""
+        if not file.stem or file.stem.isspace():
+            msg = "Path has no usable stem"
+            raise InvalidPathError(msg)
+
+    @staticmethod
+    def _split_stem(stem: str) -> tuple[str, str]:
+        """Split a stem into the original stem and raw timestamp.
+
+        Args:
+            stem: The filename stem to split.
+
+        Returns:
+            A ``(original_stem, raw_timestamp)`` tuple.
+
+        Raises:
+            TimestampParseError: If the stem is too short or the
+                separator is missing.
+        """
+        sep: str = FileTimestamp._SEPARATOR
+        min_length: int = len(
+            datetime.min.strftime(format=FileTimestamp._DT_FORMAT) + sep  # noqa: DTZ901
+        )
+
+        if len(stem) <= min_length:
+            msg = f"Stem too short to contain a timestamp: {stem}"
+            raise TimestampParseError(msg)
+
+        if stem[-min_length] != sep:
+            msg = f"Expected {sep!r} before timestamp in: {stem}"
+            raise TimestampParseError(msg)
+
+        return stem[:-min_length], stem[-min_length + len(sep) :]
+
+    @staticmethod
+    def add(file: Path, timestamp: datetime | None = None) -> TimestampedFile:
+        """Return a new path with a timestamp appended to the stem.
+
+        Args:
+            file: The original file path.
+            timestamp: The datetime to embed.
+                Defaults to ``datetime.now()``.
+
+        Returns:
+            A :class:`TimestampedFile` containing the timestamped
+            path and the datetime used.
+        """
+        FileTimestamp._validate_file(file)
+
+        if timestamp is None:
+            timestamp = datetime.now()  # noqa: DTZ005
+
+        formatted: str = timestamp.strftime(format=FileTimestamp._DT_FORMAT)
+        stamped: Path = file.with_stem(
+            stem=f"{file.stem}{FileTimestamp._SEPARATOR}{formatted}"
+        )
+        return TimestampedFile(file=stamped, timestamp=timestamp)
+
+    @staticmethod
+    def read(file: Path) -> TimestampedFile:
+        """Extract a timestamp previously added by :meth:`add`.
+
+        Args:
+            file: A path whose stem ends with
+                ``_YYYY-MM-DD_HH-MM-SS``.
+
+        Returns:
+            A :class:`TimestampedFile` containing the original path
+            (without the timestamp) and the parsed ``datetime``.
+
+        Raises:
+            TimestampParseError: If *file* does not contain a valid
+                timestamp suffix.
+        """
+        FileTimestamp._validate_file(file)
+        org_stem, raw_ts = FileTimestamp._split_stem(file.stem)
+
+        try:
+            ts: datetime = datetime.strptime(  # noqa: DTZ007
+                raw_ts, FileTimestamp._DT_FORMAT
+            )
+        except ValueError:
+            msg = f"Could not parse timestamp: {raw_ts!r}"
+            raise TimestampParseError(msg) from None
+
+        org_file: Path = file.with_stem(stem=org_stem)
+        return TimestampedFile(file=org_file, timestamp=ts)