termcore 0.2.0__py3-none-any.whl

termcore/util/datetime.py

@@ -0,0 +1,173 @@
+"""
+Converting between UNIX timestamps and date strings.
+
+This module offers convenient static methods for working with dates and times,
+including:
+
+- Converting UNIX timestamps to formatted date strings and vice versa.
+- Calculating the number of days between two timestamps.
+- Retrieving today's date or timestamp at midnight.
+
+It supports both German-style date formatting ("DD.MM.YYYY") and ISO-style
+formatting ("YYYY-MM-DD") for flexibility in various locales, selected through
+the `DateFormat` enum.
+
+Every conversion is anchored in the machine's local time zone, and says so:
+the datetimes built here carry their offset instead of leaving it implied. A
+naive timestamp changes meaning with the daylight saving switch, with the
+machine and on serialisation, and the error surfaces months later in wrongly
+sorted or wrongly calculated data rather than at the call site.
+
+"""
+
+from datetime import UTC, datetime, time
+from enum import Enum
+
+# Without this, `from .datetime import *` in the package __init__ re-exports
+# the imported `datetime` class, which then shadows this very module: after
+# importing termcore, `termcore.util.datetime` is the class, not the module.
+__all__ = [
+    "DateFormat",
+    "date_diff",
+    "date_to_timestamp",
+    "timestamp_to_date",
+    "today_date",
+    "today_timestamp",
+]
+
+
+class DateFormat(Enum):
+    """
+    The date layouts these functions read and write.
+
+    Values are `strftime` patterns, so they can be handed to `strftime` and
+    `strptime` directly.
+    """
+
+    GERMAN = "%d.%m.%Y"
+    ISO = "%Y-%m-%d"
+
+
+def timestamp_to_date(
+    timestamp: int | None, date_format: DateFormat = DateFormat.GERMAN
+) -> str:
+    """
+    Converts a UNIX timestamp into a date string.
+
+    Parameters
+    ----------
+    timestamp : int or None
+        UNIX timestamp.
+    date_format : DateFormat, optional
+        Layout of the returned string, German by default.
+
+    Returns
+    -------
+    str
+        The date as seen in the local time zone. Empty string if the given
+        timestamp is None.
+    """
+    # Return empty string if the given timestamp is None
+    if timestamp is None:
+        return ""
+
+    # Convert timestamp to a date in the local zone
+    date_obj = datetime.fromtimestamp(timestamp, tz=UTC).astimezone()
+
+    return date_obj.strftime(date_format.value)
+
+
+def date_to_timestamp(
+    date_str: str, date_format: DateFormat = DateFormat.GERMAN
+) -> int | None:
+    """
+    Converts a date string into a UNIX timestamp.
+
+    The date is read as local midnight.
+
+    Parameters
+    ----------
+    date_str : str
+        The date, laid out as `date_format` describes.
+    date_format : DateFormat, optional
+        Layout the string is expected in, German by default.
+
+    Returns
+    -------
+    int or None
+        Unix timestamp (number of seconds since 1970-01-01), or None if the
+        string does not match the expected layout.
+    """
+    # Check if the date string matches the expected format
+    try:
+        date_obj = datetime.strptime(date_str, date_format.value)  # noqa: DTZ007
+    except ValueError:
+        return None
+
+    # astimezone() reads a naive value as local time and attaches the matching
+    # offset - the assumption this module makes explicit rather than inherits
+    return int(date_obj.astimezone().timestamp())
+
+
+def date_diff(timestamp1: int, timestamp2: int) -> int:
+    """
+    Calculates the number of calendar days between two timestamps.
+
+    Counted as local calendar dates rather than as 86400-second blocks, so
+    the time of day does not matter and a span crossing a daylight saving
+    switch is not off by one. Two moments on the same local day are 0 days
+    apart, whether they are a second or twenty hours apart.
+
+    Parameters
+    ----------
+    timestamp1 : int
+        UNIX time stamp 1.
+    timestamp2 : int
+        UNIX time stamp 2.
+
+    Returns
+    -------
+    int
+        Number of days between the given timestamps, negative when the
+        second one is the later of the two.
+    """
+    first = datetime.fromtimestamp(timestamp1, tz=UTC).astimezone().date()
+    second = datetime.fromtimestamp(timestamp2, tz=UTC).astimezone().date()
+
+    return (first - second).days
+
+
+def today_timestamp() -> int:
+    """
+    Returns the time stamp of today for the time 00:00 h.
+
+    Returns
+    -------
+    int
+        UNIX timestamp of local midnight.
+    """
+    # Date of today in the local zone
+    today = datetime.now(UTC).astimezone().date()
+
+    # Combine with time 00:00 and anchor it in the local zone
+    midnight = datetime.combine(today, time.min).astimezone()
+
+    # Return unix timestamp
+    return int(midnight.timestamp())
+
+
+def today_date(date_format: DateFormat = DateFormat.GERMAN) -> str:
+    """
+    Returns the date of today as a string.
+
+    Parameters
+    ----------
+    date_format : DateFormat, optional
+        Layout of the returned string, German by default.
+
+    Returns
+    -------
+    str
+        Today's date in the local time zone.
+    """
+    return timestamp_to_date(today_timestamp(), date_format)

termcore/util/debug.py

@@ -0,0 +1,196 @@
+"""
+Decorators for inspecting calls and measuring execution time.
+
+This module offers decorators that can be used to:
+
+- Log function calls, including arguments, keyword arguments and return values.
+- Measure and display execution time of functions, with optional nanosecond
+precision.
+
+These utilities are useful for tracking function behavior and identifying
+performance bottlenecks during runtime, without requiring changes to the
+function logic itself.
+
+Examples
+--------
+Printing arguments
+~~~~~~~~~~~~~~~~~~
+
+>>> @print_arguments
+... def do_something(t: str, n: int) -> None:
+...     print(f'I am not doing anything with string "{t}" and number {str(n)}.')
+...
+>>> do_something('ABC', 11)
+
+Measuring execution time of a function
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+>>> @timing()
+... def iterate_something() -> None:
+...     v: int = 0
+...     for i in range(10**7):
+...         v += 1
+...
+>>> iterate_something()
+
+"""
+
+import logging
+import time
+from collections.abc import Callable
+from functools import wraps
+from typing import ParamSpec, TypeVar
+
+__all__ = [
+    "print_arguments",
+    "timing",
+    "timing_ns",
+]
+
+_logger = logging.getLogger(__name__)
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def print_arguments[**P, R](fn: Callable[P, R]) -> Callable[P, R]:
+    """
+    Logs name, arguments and return value on every call.
+
+    Parameters
+    ----------
+    fn : Callable
+        The function to be decorated.
+
+    Returns
+    -------
+    Callable
+        A wrapper function that adds debugging output.
+    """
+    @wraps(fn)  # Without this fn.__name__ would be empty
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        """
+        Wrapper function that prints the function's arguments and return value.
+
+        Parameters
+        ----------
+        *args : P.args
+            Positional arguments.
+        **kwargs : P.kwargs
+            Keyword arguments.
+
+        Returns
+        -------
+        R
+            The original return value of the decorated function.
+        """
+        # Report the call through the logger, so a consumer can filter
+        # or silence it like any other diagnostic
+        _logger.debug("Function %s called", fn.__name__)
+        _logger.debug("Args: %r", args)
+        _logger.debug("Kwargs: %r", kwargs)
+
+        # Call function
+        fn_result = fn(*args, **kwargs)
+
+        _logger.debug(
+            "Function %s returns: %r", fn.__name__, fn_result
+        )
+
+        return fn_result
+
+    return wrapper
+
+
+def timing() -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """
+    A decorator factory that measures the execution time in seconds.
+
+    Returns
+    -------
+    Callable
+        A decorator that wraps the target function with timing logic.
+    """
+    return _timing(time.perf_counter, "s")
+
+
+def timing_ns() -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """
+    A decorator factory that measures the execution time in nanoseconds.
+
+    Returns
+    -------
+    Callable
+        A decorator that wraps the target function with timing logic.
+    """
+    return _timing(time.perf_counter_ns, "ns")
+
+
+def _timing(
+    time_fn: Callable[[], float], time_scale: str
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """
+    Builds the timing decorator around the given clock.
+
+    Parameters
+    ----------
+    time_fn : Callable
+        The clock to read, in the unit `time_scale` names.
+    time_scale : str
+        Unit suffix written to the log.
+
+    Returns
+    -------
+    Callable
+        A decorator that wraps the target function with timing logic.
+    """
+    def wrap_with_timing(fn: Callable[P, R]) -> Callable[P, R]:
+        """
+        Wraps the function so its execution time is measured.
+
+        Parameters
+        ----------
+        fn : Callable
+            Reference to the function.
+
+        Returns
+        -------
+        Callable
+            A wrapped version of the function with timing logic.
+        """
+        @wraps(fn)
+        def timer(*args: P.args, **kwargs: P.kwargs) -> R:
+            """
+            Measures the execution time of the function call.
+
+            Parameters
+            ----------
+            *args : P.args
+                Positional arguments.
+            **kwargs : P.kwargs
+                Keyword arguments.
+
+            Returns
+            -------
+            R
+                The original return value of the decorated function.
+            """
+            # Store start time
+            start_time = time_fn()
+
+            # Call function
+            fn_result = fn(*args, **kwargs)
+
+            # Store end time + calculate and print execution time
+            end_time = time_fn()
+            duration = end_time - start_time
+            _logger.debug(
+                "Function %s took: %s %s",
+                fn.__name__, duration, time_scale
+            )
+
+            return fn_result
+
+        return timer
+
+    return wrap_with_timing

termcore/util/index.py

@@ -0,0 +1,112 @@
+"""
+Index arithmetic for navigating lists.
+
+In particular the cyclic movement selection lists in a terminal user
+interface are expected to have.
+
+Two functions rather than one with a switch: `next_index` wraps around at
+both ends, `clamped_index` stops at them. Which one a view wants is a
+property of that view, and naming it at the call site says so.
+
+"""
+
+
+
+__all__ = [
+    "clamped_index",
+    "next_index",
+]
+
+
+def next_index(current_index: int, length: int, direction: int = 1) -> int:
+    """
+    Calculates the next index in a list, wrapping around at both ends.
+
+    Parameters
+    ----------
+    current_index : int
+        The current index in the list.
+    length : int
+        The number of items in the list.
+    direction : int, optional
+        The direction and size of the movement (1 for one step forward,
+        -1 for one step backward).
+
+    Returns
+    -------
+    int
+        The calculated next index. An empty list always yields 0.
+
+    Notes
+    -----
+    The expression `(current_index + direction) % length` keeps the index
+    within the valid range from `0` to `length - 1`. The modulo operator
+    makes it "wrap around":
+
+        - If the index moves past the end of the list, it wraps back
+          to 0.
+        - If the index moves before the beginning, it wraps to the
+          last position.
+
+    Examples
+    --------
+    For a list of length 5 (indices 0 to 4):
+
+    >>> next_index(4, 5)  # moves from the end to the start
+    0
+    >>> next_index(0, 5, direction=-1)  # moves from the start to the end
+    4
+    >>> next_index(2, 5)  # normal forward movement
+    3
+    >>> next_index(2, 5, direction=-1)  # normal backward movement
+    1
+
+    An empty list has no valid index, so 0 is returned:
+
+    >>> next_index(0, 0)
+    0
+    """
+    # An empty list has no index to move to - and % 0 would raise
+    if length <= 0:
+        return 0
+
+    return (current_index + direction) % length
+
+
+def clamped_index(current_index: int, length: int, direction: int = 1) -> int:
+    """
+    Calculates the next index in a list, stopping at both ends.
+
+    Parameters
+    ----------
+    current_index : int
+        The current index in the list.
+    length : int
+        The number of items in the list.
+    direction : int, optional
+        The direction and size of the movement (1 for one step forward,
+        -1 for one step backward).
+
+    Returns
+    -------
+    int
+        The calculated next index, never outside the list. An empty list
+        always yields 0.
+
+    Examples
+    --------
+    For a list of length 5 (indices 0 to 4):
+
+    >>> clamped_index(4, 5)  # already at the end, stays there
+    4
+    >>> clamped_index(0, 5, direction=-1)  # already at the start
+    0
+    >>> clamped_index(2, 5)  # normal forward movement
+    3
+    >>> clamped_index(0, 5, direction=10)  # a step past the end is clamped
+    4
+    """
+    if length <= 0:
+        return 0
+
+    return max(0, min(current_index + direction, length - 1))

termcore/util/logger.py

@@ -0,0 +1,36 @@
+"""Sets up file and console logging for an application."""
+
+import logging
+from pathlib import Path
+
+__all__ = [
+    "setup_logging",
+]
+
+
+def setup_logging(appname: str, level: int = logging.DEBUG) -> None:
+    """
+    Sets up logging for the application.
+
+    Logs are stored in the user's home directory, under
+    `.local/state/{appname}/app.log`.
+
+    Parameters
+    ----------
+    appname : str
+        The name of the application, used to create a unique log directory.
+    level : int, optional
+        The logging level (e.g., logging.DEBUG, logging.INFO),
+        by default logging.DEBUG.
+    """
+    log_dir = Path.home() / ".local" / "state" / appname
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    log_file = log_dir / "app.log"
+
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+        handlers=[logging.FileHandler(log_file, encoding="utf-8")],
+    )

termcore/util/singleton.py

@@ -0,0 +1,46 @@
+"""The metaclass implementing the singleton pattern."""
+
+from typing import Any, cast
+
+__all__ = [
+    "Singleton",
+]
+
+# Keyed by class, so that two classes using this metaclass keep their own
+# instance. Holding the registry here rather than on the metaclass is also
+# what lets __call__ report the constructed class as its return type.
+_instances: dict[type, object] = {}
+
+
+class Singleton(type):
+    """
+    Metaclass for the singleton pattern.
+
+    Ensures that a class has only one instance and provides global access
+    to it.
+
+    Examples
+    --------
+    >>> class SomeClass(metaclass=Singleton):
+    ...     pass
+    >>> SomeClass() is SomeClass()
+    True
+    """
+
+    def __call__[T](cls: type[T], *args: Any, **kwargs: Any) -> T:  # noqa: ANN401
+        """
+        Returns the one instance, building it on the first call.
+
+        The arguments are whatever the class itself takes, which is what Any
+        says here. The return type is the class, so that a consumer sees the
+        type it asked for instead of `object`.
+        """
+        if cls not in _instances:
+            _instances[cls] = super().__call__(*args, **kwargs)  # pyright: ignore[reportAny]
+
+        return cast("T", _instances[cls])
+
+    @property
+    def instance(cls) -> object | None:
+        """Returns the single instance, or None before it was built."""
+        return _instances.get(cls)