pytility 1.0.0__py3-none-any.whl

pytility/__init__.py

@@ -0,0 +1,30 @@
+"""Initialisations."""
+
+from importlib.metadata import version as _version
+
+from .files import concat_files
+from .iterables import arg_to_iter, batchify, clear_list, flatten, take_first, window
+from .parsers import parse_bool, parse_date, parse_float, parse_int
+from .strings import normalize_space, to_str, truncate
+
+__version__ = _version("pytility")
+VERSION = tuple(int(part) for part in __version__.split("."))
+
+__all__ = (
+    "VERSION",
+    "__version__",
+    "arg_to_iter",
+    "batchify",
+    "clear_list",
+    "concat_files",
+    "flatten",
+    "normalize_space",
+    "parse_bool",
+    "parse_date",
+    "parse_float",
+    "parse_int",
+    "take_first",
+    "to_str",
+    "truncate",
+    "window",
+)

pytility/files.py

@@ -0,0 +1,54 @@
+"""File utilities."""
+
+import logging
+import os
+import shutil
+from collections.abc import Iterable
+from typing import TextIO
+
+LOGGER = logging.getLogger(__name__)
+
+FilePath = str | bytes | os.PathLike | TextIO
+
+
+def _copy_file(src: FilePath, dst: TextIO, ensure_newline: bool) -> int:
+    if isinstance(src, (str, bytes, os.PathLike)):
+        LOGGER.debug("copy data from <%s>", src)
+        with open(src) as in_file:
+            return _copy_file(in_file, dst, ensure_newline)
+
+    shutil.copyfileobj(src, dst)
+
+    if not src.tell():
+        return 0
+
+    copied = src.tell()
+
+    if ensure_newline:
+        src.seek(src.tell() - 1)
+
+        if src.read(1) != "\n":
+            dst.write("\n")
+            copied += 1
+
+    return copied
+
+
+def concat_files(
+    dst: FilePath, srcs: Iterable[FilePath], ensure_newline: bool = False
+) -> int:
+    """Concatenate files, returning the total number of bytes copied."""
+
+    if isinstance(dst, (str, bytes, os.PathLike)):
+        LOGGER.info("concatenating files into <%s>", dst)
+        with open(dst, "w") as out_file:
+            return concat_files(out_file, srcs, ensure_newline)
+
+    total = 0
+
+    for src in srcs:
+        total += _copy_file(src, dst, ensure_newline)
+
+    LOGGER.info("done concatenating, %d bytes in total", total)
+
+    return total

pytility/iterables.py

@@ -0,0 +1,64 @@
+"""Iterable utilities."""
+
+from collections import OrderedDict
+from collections.abc import Iterable
+from itertools import groupby, tee
+from typing import Any, TypeVar
+
+ITERABLE_SINGLE_VALUES = (dict, str, bytes)
+Typed = TypeVar("Typed")
+
+
+def clear_list(items: Iterable[Typed | None]) -> list[Typed]:
+    """Return unique items in order of first ocurrence."""
+    return list(OrderedDict.fromkeys(filter(None, items)))
+
+
+def flatten(*args: Any) -> Iterable:
+    """Flatten iterables of iterables recursively."""
+    for arg in args:
+        if not isinstance(arg, ITERABLE_SINGLE_VALUES) and hasattr(arg, "__iter__"):
+            for item in arg:
+                yield from flatten(item)
+        else:
+            yield arg
+
+
+def arg_to_iter(arg: Any) -> Iterable:
+    """Wraps arg into tuple if not an iterable."""
+
+    if arg is None:
+        return ()
+
+    if not isinstance(arg, ITERABLE_SINGLE_VALUES) and hasattr(arg, "__iter__"):
+        return arg
+
+    return (arg,)
+
+
+def take_first(items):
+    """Take first item that is not None or zero-length str."""
+
+    for item in arg_to_iter(items):
+        if item is not None and item != "":
+            return item
+
+    return None
+
+
+def batchify(iterable, size):
+    """Make batches of given size."""
+    for _, group in groupby(enumerate(iterable), key=lambda x: x[0] // size):
+        yield (x[1] for x in group)
+
+
+def window(iterable: Iterable[Typed], size: int = 2) -> Iterable[tuple[Typed, ...]]:
+    """Sliding window of an iterator."""
+
+    iterables = tee(iterable, size)
+
+    for num, itb in enumerate(iterables):
+        for _ in range(num):
+            next(itb, None)
+
+    return zip(*iterables, strict=False)

pytility/parsers.py

@@ -0,0 +1,104 @@
+"""Parsers."""
+
+from datetime import date as date_cls
+from datetime import datetime, timezone
+from typing import Any
+
+
+def parse_int(string: Any, base: int = 10) -> int | None:
+    """Safely convert an object to int if possible, else return None."""
+
+    if isinstance(string, int):
+        return string
+
+    try:
+        return int(string, base=base)
+    except Exception:
+        pass
+
+    try:
+        return int(string)
+    except Exception:
+        pass
+
+    return None
+
+
+def parse_float(number: Any) -> float | None:
+    """Safely convert an object to float if possible, else return None."""
+
+    try:
+        return float(number)
+    except Exception:
+        pass
+    return None
+
+
+def parse_bool(item: Any) -> bool:
+    """Parses an item and converts it to a boolean."""
+
+    if isinstance(item, int):
+        return bool(item)
+    if item in ("True", "true", "Yes", "yes"):
+        return True
+    integer = parse_int(item)
+    if integer is not None:
+        return bool(integer)
+    return False
+
+
+def _add_tz(date: datetime | None, tzinfo: timezone | None = None) -> datetime | None:
+    return (
+        date if not tzinfo or not date or date.tzinfo else date.replace(tzinfo=tzinfo)
+    )
+
+
+def parse_date(
+    date: Any, tzinfo: timezone | None = None, format_str: str | None = None
+) -> datetime | None:
+    """Try to turn input into a datetime object."""
+
+    if not date:
+        return None
+
+    # already a datetime
+    if isinstance(date, datetime):
+        return _add_tz(date, tzinfo)
+
+    # date without time
+    if isinstance(date, date_cls):
+        return _add_tz(datetime(date.year, date.month, date.day), tzinfo=tzinfo)
+
+    # parse as epoch time
+    timestamp = parse_float(date)
+    if timestamp is not None:
+        return datetime.fromtimestamp(timestamp, tzinfo or timezone.utc)
+
+    if format_str:
+        try:
+            # parse as string in given format
+            return _add_tz(datetime.strptime(date, format_str), tzinfo)
+        except Exception:
+            pass
+
+    try:
+        import dateutil.parser
+
+        # parse as string
+        return _add_tz(dateutil.parser.parse(date), tzinfo)
+    except Exception:
+        pass
+
+    try:
+        # parse as (year, month, day, hour, minute, second, microsecond, tzinfo)
+        return datetime(*date)
+    except Exception:
+        pass
+
+    try:
+        # parse as time.struct_time
+        return datetime(*date[:6], tzinfo=tzinfo or timezone.utc)
+    except Exception:
+        pass
+
+    return None

pytility/strings.py

@@ -0,0 +1,65 @@
+"""String utilities."""
+
+import re
+import string as string_lib
+from typing import Any
+
+PRINTABLE_SET = frozenset(string_lib.printable)
+NON_PRINTABLE_SET = frozenset(chr(i) for i in range(128)) - PRINTABLE_SET
+NON_PRINTABLE_TRANSLATE = {ord(character): None for character in NON_PRINTABLE_SET}
+REGEX_WORD = re.compile(r"^\w+")
+
+
+def to_str(string: Any, encoding: str = "utf-8") -> str | None:
+    """Safely returns either string or None."""
+
+    string = (
+        string
+        if isinstance(string, str)
+        else string.decode(encoding)
+        if isinstance(string, bytes)
+        else None
+    )
+
+    return string.translate(NON_PRINTABLE_TRANSLATE) if string is not None else None
+
+
+def normalize_space(item: Any, preserve_newline: bool = False) -> str:
+    """Normalize space in a string."""
+
+    item = to_str(item)
+
+    if not item:
+        return ""
+
+    if preserve_newline:
+        return "\n".join(normalize_space(line) for line in item.splitlines()).strip()
+
+    return " ".join(item.split())
+
+
+def truncate(
+    string: str,
+    length: int,
+    ellipsis: str = "[…]",
+    respect_word: bool = False,
+) -> str:
+    """Truncates a string at given length."""
+
+    if length < 0 or len(string) <= length + len(ellipsis):
+        return string
+
+    string_trunc = string[:length]
+
+    if respect_word:
+        match = REGEX_WORD.match(string[length:])
+        if match:
+            string_trunc += match.group(0)
+
+    if string_trunc.rstrip().endswith(ellipsis):
+        return string_trunc.rstrip()
+
+    if not respect_word or not string_trunc or string_trunc[-1].isspace():
+        return string_trunc + ellipsis
+
+    return f"{string_trunc} {ellipsis}"

pytility-1.0.0.dist-info/METADATA

@@ -0,0 +1,185 @@
+Metadata-Version: 2.5
+Name: pytility
+Version: 1.0.0
+Summary: A lean collection of Python utilities
+Project-URL: Homepage, https://gitlab.com/mshepherd/pytility
+Project-URL: Documentation, https://gitlab.com/mshepherd/pytility/blob/master/README.md
+Project-URL: Source, https://gitlab.com/mshepherd/pytility
+Project-URL: Tracker, https://gitlab.com/mshepherd/pytility/issues
+Author-email: Markus Shepherd <markus.r.shepherd@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: pytility,utilities,utility
+Classifier: Programming Language :: Python
+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
+Requires-Python: >=3.10
+Provides-Extra: dates
+Requires-Dist: python-dateutil; extra == 'dates'
+Description-Content-Type: text/markdown
+
+# 🛠 Pytility 🛠
+
+[![PyPI](https://img.shields.io/pypi/v/pytility?style=flat-square)](https://pypi.python.org/pypi/pytility/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pytility?style=flat-square)](https://pypi.python.org/pypi/pytility/)
+[![PyPI - License](https://img.shields.io/pypi/l/pytility?style=flat-square)](https://pypi.python.org/pypi/pytility/)
+
+---
+
+**Source Code**: [https://gitlab.com/mshepherd/pytility](https://gitlab.com/mshepherd/pytility)
+
+**PyPI**: [https://pypi.org/project/pytility/](https://pypi.org/project/pytility/)
+
+---
+
+A lean collection of Python utilities — small, dependency-free helpers for
+strings, iterables, parsing, and files, with no runtime dependencies unless
+you opt into the `dates` extra.
+
+## Installation
+
+```sh
+pip install pytility
+```
+
+Date parsing via [`python-dateutil`](https://pypi.org/project/python-dateutil/)
+is an optional extra:
+
+```sh
+pip install pytility[dates]
+```
+
+## Usage
+
+```python
+import pytility
+
+pytility.normalize_space("  too   much   space  ")  # "too much space"
+pytility.truncate("a long string", 6)  # "a long[…]"
+pytility.parse_bool("yes")  # True
+pytility.parse_int("2a", base=16)  # 42
+pytility.clear_list([1, 1, None, 2, "", 3])  # [1, 2, 3]
+list(pytility.flatten([1, [2, [3, 4]], 5]))  # [1, 2, 3, 4, 5]
+```
+
+### API reference
+
+#### Strings (`pytility.strings`)
+
+* `to_str(string, encoding="utf-8") -> str | None` — coerces `str` or
+  `bytes` to `str`, stripping non-printable characters; anything else
+  returns `None`.
+* `normalize_space(item, preserve_newline=False) -> str` — collapses runs of
+  whitespace to single spaces; with `preserve_newline=True`, newlines are
+  kept but whitespace is normalized within each line.
+* `truncate(string, length, ellipsis="[…]", respect_word=False) -> str` —
+  truncates `string` to `length` characters plus an ellipsis; with
+  `respect_word=True`, extends the cut to the end of the word it lands in
+  rather than splitting it.
+
+#### Iterables (`pytility.iterables`)
+
+* `arg_to_iter(arg) -> Iterable` — wraps a non-iterable (or a `str`/`bytes`/
+  `dict`, which are treated as scalars) in a 1-tuple; `None` becomes `()`;
+  anything else iterable is returned as-is.
+* `clear_list(items) -> list` — unique items in order of first occurrence,
+  with falsy values (`None`, `""`, `0`, …) dropped.
+* `flatten(*args) -> Iterable` — recursively flattens nested iterables;
+  `str`/`bytes`/`dict` are treated as scalars, not flattened further.
+* `take_first(items) -> Any | None` — the first item that isn't `None` or
+  `""`, or `None` if there isn't one.
+* `batchify(iterable, size) -> Iterable[Iterable]` — splits `iterable` into
+  chunks of at most `size` items.
+* `window(iterable, size=2) -> Iterable[tuple]` — a sliding window of
+  `size` consecutive items over `iterable`.
+
+#### Parsers (`pytility.parsers`)
+
+* `parse_int(string, base=10) -> int | None` — safely converts to `int`,
+  or `None` on failure.
+* `parse_float(number) -> float | None` — safely converts to `float`, or
+  `None` on failure.
+* `parse_bool(item) -> bool` — recognizes `int`s, the strings `"True"`,
+  `"true"`, `"Yes"`, `"yes"`, and anything else `parse_int` can parse as
+  non-zero; everything else is `False`.
+* `parse_date(date, tzinfo=None, format_str=None) -> datetime | None` —
+  parses `datetime`/`date` objects, epoch timestamps, a given
+  `format_str`, free-form strings (via `python-dateutil`, if installed),
+  or `(year, month, day, ...)` tuples / `time.struct_time`. Falsy input
+  (including `0`) returns `None` before any parsing is attempted.
+
+#### Files (`pytility.files`)
+
+* `concat_files(dst, srcs, ensure_newline=False) -> int` — concatenates
+  `srcs` into `dst` (paths or open file objects), returning the total
+  bytes written. With `ensure_newline=True`, a newline is appended after
+  every source that doesn't already end in one — including the last.
+
+## Development
+
+* Clone this repository
+* Requirements:
+  * [uv](https://docs.astral.sh/uv/)
+  * Python 3.10+
+* Create a virtual environment and install the dependencies
+
+```sh
+uv sync
+```
+
+### Testing
+
+```sh
+uv run pytest
+```
+
+### Pre-commit
+
+Pre-commit hooks run the auto-formatter and linter (`ruff`), the type
+checker (`ty`), and other housekeeping checks so the changeset is in good
+shape before a commit happens.
+
+Install the hooks with (runs on every commit):
+
+```sh
+uv run pre-commit install
+```
+
+Or run all checks manually against every file:
+
+```sh
+uv run pre-commit run --all-files
+```
+
+CI (`.gitlab-ci.yml`) runs the same lint hooks, the test suite across
+Python 3.10–3.14, and a package build on every push.
+
+### Releasing
+
+This project is published to PyPI manually — there's no CI publish job or
+GitHub-style draft release here, just these steps run locally:
+
+```sh
+# 1. Bump version (major|minor|patch|stable|alpha|beta|rc|post|dev, or pass an explicit value)
+uv version --bump patch
+VERSION=$(uv version --short)
+
+# 2. Commit the version bump
+git add pyproject.toml uv.lock
+git commit -m "Release $VERSION"
+
+# 3. Tag and push to GitLab (the only remote this repo has)
+git tag "v$VERSION"
+git push gitlab master
+git push gitlab "v$VERSION"
+
+# 4. Build and publish to PyPI (needs a token, e.g. via a UV_PUBLISH_TOKEN env var)
+uv build
+uv publish
+```
+
+Note that `uv version` only edits `pyproject.toml`; `uv.lock` is re-synced
+alongside it since it also records the project's own version.

pytility-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pytility/__init__.py,sha256=u_fOHyunMkqfgMDa1Dr0QnYf2rD40QqabhURJMEoa9k,709
+pytility/files.py,sha256=SPKRn60zMcuUlVIEVhOsKhCM_iGmjf3gsJNBK6Uk3LA,1307
+pytility/iterables.py,sha256=uQPC9X_WoHgJU6HzBm30MypaCj8LjtJtbF_WZiRnz4A,1676
+pytility/parsers.py,sha256=YEiGDZ2PUPI783A7flyZUmR6xrSjauQ8I0-uSj2tdSg,2493
+pytility/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pytility/strings.py,sha256=DWbK9XlAII43ued2HUj670rBMVBaI7hoUuLq-ke8ScI,1672
+pytility-1.0.0.dist-info/METADATA,sha256=G2y9RQMc1LIzX4ewrdiMinFNP4ci02dBkd62dP95M8M,6381
+pytility-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+pytility-1.0.0.dist-info/licenses/LICENSE,sha256=WcYkIFKvE2InORAE70AfXkBoQqXLLRsXETBDkNkwxNc,1072
+pytility-1.0.0.dist-info/RECORD,,

pytility-1.0.0.dist-info/WHEEL

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

pytility-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Markus Shepherd
+
+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.