PostBOUND 0.19.0__py3-none-any.whl

postbound/util/dicts.py

@@ -0,0 +1,330 @@
+"""Contains utilities to access and modify dictionaries more conveniently."""
+
+from __future__ import annotations
+
+import numpy as np
+
+import collections
+import itertools
+import numbers
+import typing
+import warnings
+from collections.abc import Callable, Iterable, Sequence
+from typing import Optional
+
+T = typing.TypeVar("T")
+K = typing.TypeVar("K")
+V = typing.TypeVar("V")
+
+
+def stringify(d: dict[K, V]) -> str:
+    """Generates a string-representation of a dictionary.
+
+    In contrast to calling ``str()`` directly, this method generates proper string representations of both keys and values and
+    does not use ``repr()`` for them. Nested objects are stilled formatted according to ``str()`` however.
+
+    Parameters
+    ----------
+    d : dict[K, V]
+        The dictionary to stringify
+
+    Returns
+    -------
+    str
+        The string representation
+    """
+    items_str = ", ".join(f"{k}: {v}" for k, v in d.items())
+    return "{" + items_str + "}"
+
+
+def key(dictionary: dict[K, V]) -> K:
+    """Provides the key of a dictionary with just 1 item.
+
+    `key({'a': 1}) = 'a'`
+    """
+    if not len(dictionary) == 1:
+        nvals = len(dictionary)
+        raise ValueError(
+            f"Dictionary must contain exactly 1 entry, not {nvals}: {dictionary}"
+        )
+    return next(iter(dictionary.keys()))
+
+
+def value(dictionary: dict[K, V]) -> V:
+    """Provides the value of a dictionary with just 1 item.
+
+    `value({'a': 1}) = 1`
+    """
+    if not len(dictionary) == 1:
+        raise ValueError(
+            "Dictionary must contain exactly 1 entry, not " + str(len(dictionary))
+        )
+    return next(iter(dictionary.values()))
+
+
+def difference(a: dict[K, V], b: dict[K, V]) -> dict[K, V]:
+    """Computes the set difference between two dictionaries based on their keys.
+
+    Parameters
+    ----------
+    a : dict[K, V]
+        The dict to remove entries from
+    b : dict[K, V]
+        The entries to remove
+
+    Returns
+    -------
+    dict[K, V]
+        A dictionary that contains all *key, value* pairs from *a* where the *key* is not in *b*.
+    """
+    return {k: v for k, v in a.items() if k not in b}
+
+
+def intersection(a: dict[K, V], b: dict[K, V]) -> dict[K, V]:
+    """Computes the set intersection between two dictionaries based on their keys.
+
+    Parameters
+    ----------
+    a : dict[K, V]
+        The first dictionary
+    b : dict[K, V]
+        The second dictionary
+
+    Returns
+    -------
+    dict[K, V]
+        A dictionary that contains all *key, value* pairs from *a* where the *key* is also in *b*.
+    """
+    return {k: v for k, v in a.items() if k in b}
+
+
+def merge(
+    a: dict[K, V], b: dict[K, V], *, updater: Optional[Callable[[K, V, V], V]] = None
+) -> dict[K, V]:
+    """Creates a new dict containing all key/values pairs from both argument dictionaries.
+
+    If keys overlap, entries from dictionary `b` will take priority, unless an `update` method is given.
+    If `update` is given, and `a[k] = v` and `b[k] = v'` (i.e. both `a` and `b` share a key `k`) the merged dictionary
+    will contain the result of `update(k, v, v')` as entry for `k`.
+
+    Note that as of Python 3.9, such a method was added to dictionaries as well (via the `|=` syntax). Our current
+    implementation is not optimized for larger dictionaries and will probably have a pretty bad performance on such
+    input data.
+    """
+    if not updater:
+        return dict([*a.items()] + [*b.items()])
+    else:
+        merged = dict(a)
+        for k, v in b.items():
+            if k in merged:
+                merged[k] = updater(k, merged[k], v)
+            else:
+                merged[k] = v
+        return merged
+
+
+def update(dictionary: dict[K, V], updater: Callable[[K, V], T]) -> dict[K, T]:
+    """Creates a new dict by calling update on each key/value pair on the old dict, retaining its keys."""
+    return {k: updater(k, v) for k, v in dictionary.items()}
+
+
+def explode(dictionary: dict[K, list[V]]) -> list[tuple[K, V]]:
+    """Transforms dicts mapping keys to lists of values to a list of key/value pairs."""
+    values: list[tuple[K, V]] = []
+    for k, dict_values in dictionary.items():
+        values.extend(zip(itertools.cycle([k]), dict_values))
+    return values
+
+
+def hash_dict(dictionary: dict[K, V]) -> int:
+    """Calculates a hash value based on the current dict contents (keys and values)."""
+    keys = list(dictionary.keys())
+    values = []
+    for val in dictionary.values():
+        if isinstance(val, collections.abc.Hashable):
+            values.append(hash(val))
+        elif isinstance(val, list) or isinstance(val, set):
+            values.append(hash(tuple(val)))
+        elif isinstance(val, dict):
+            values.append(hash_dict(val))
+        else:
+            warnings.warn("Unhashable type, skipping: " + type(val))
+    keys_hash = hash(tuple(keys))
+    values_hash = hash(tuple(values))
+    return hash((keys_hash, values_hash))
+
+
+def generate_multi(entries: list[tuple[K, V]]) -> dict[K, list[V]]:
+    """Generates a multi-dict based on its entries.
+
+    Each key can occur multiple times and values will be aggregated in a list.
+    """
+    collector = collections.defaultdict(list)
+    for k, v in entries:
+        collector[k].append(v)
+    return dict(collector)
+
+
+def reduce_multi(
+    multi_dict: dict[K, list[V]], reduction: Callable[[K, list[V]], V]
+) -> dict[K, V]:
+    """Ungroups a multi-dict by aggregating the values based on key and values."""
+    return {k: reduction(k, vs) for k, vs in multi_dict.items()}
+
+
+def invert_multi(mapping: dict[K, list[V]]) -> dict[V, list[K]]:
+    """Inverts the `key -> values` mapping of a dict to become `value -> keys` instead.
+
+    Supppose a multi-dict has the following contents: `{'a': [1, 2], 'b': [2, 3]}`.
+    Calling `invert` transforms this mapping to `{1: ['a'], 2: ['a', 'b'], 3: ['b']}`.
+    """
+    level1 = {tuple(vs): k for k, vs in mapping.items()}
+    level2: dict[V, list[K]] = {}
+    for vs, k in level1.items():
+        for v in vs:
+            if v not in level2:
+                level2[v] = [k]
+            else:
+                level2[v].append(k)
+    return level2
+
+
+def aggregate(dictionaries: Iterable[dict[K, V]]) -> dict[K, Sequence[V]]:
+    aggregated_dict = collections.defaultdict(list)
+    for d in dictionaries:
+        for k, v in d.items():
+            aggregated_dict[k].append(v)
+    return dict(aggregated_dict)
+
+
+def invert(mapping: dict[K, V]) -> dict[V, K]:
+    """Inverts the `key -> value` mapping of a dict to become `value -> key` instead.
+
+    In contrast to `invert_multi` this does not handle duplicate values (which leads to duplicate keys), nor does it
+    process the original values of `mapping` in any way.
+
+    Basically, this function is just a better-readable shortcut for `{v: k for k, v in d.items()}`.
+    """
+    return {v: k for k, v in mapping.items()}
+
+
+def argmin(mapping: dict[K, numbers.Number]) -> K:
+    """
+    For a dict mapping keys to numeric types, returns the key `k` with minimum value `v`, s.t. for all keys `k'` with
+    values `v'` it holds that `v <= v'`.
+    """
+    return min(mapping, key=mapping.get)
+
+
+def dict_to_numpy(data: dict[K, V]) -> np.array[V]:
+    sorted_dict = {k: data[k] for k in sorted(data)}
+    return np.asarray(list(sorted_dict.values()))
+
+
+class HashableDict(collections.UserDict[K, V]):
+    """A dictionary implementation that can be hashed.
+
+    Warnings
+    --------
+    This type should be used with extreme caution in order to not violate any invariants due to unintended data modification.
+    """
+
+    def __hash__(self) -> int:
+        return hash_dict(self.data)
+
+
+class CustomHashDict(collections.UserDict[K, V]):
+    """Wrapper of a normal Python dictionary that uses a custom hash function instead of the default hash() method.
+
+    All non-hashing related behavior is directly inherited from the default Python dictionary. Only the item access is changed
+    to enforce the usage of the new hashing function.
+
+    Notice that since the custom hash function always provides an integer value, collision detection is weaker than originally.
+    This is because the actual dictionary never sees the original keys to run an equality comparison. Instead, the comparison
+    is based on the integer values.
+
+    Parameters
+    ----------
+    hash_func : Callable[[K], int]
+        The hashing function to use. It receives the key as input and must produce a valid hash value as output.
+    **kwargs : dict, optional
+        Additional keyword arguments that should be passed to the hashing function upon each invocation.
+    """
+
+    def __init__(self, hash_func: Callable[[K], int], **kwargs) -> None:
+        super().__init__()
+        self.hash_function = hash_func
+        self._hash_args = kwargs
+
+    def _apply_hash(self, key: K) -> int:
+        return self.hash_function(key, **self._hash_args)
+
+    def __getitem__(self, k: K) -> V:
+        return super().__getitem__(self._apply_hash(k))
+
+    def __setitem__(self, k: K, item: V) -> None:
+        super().__setitem__(self._apply_hash(k), item)
+
+    def __delitem__(self, key: K) -> None:
+        return super().__delitem__(self._apply_hash(key))
+
+    def __contains__(self, key: K) -> bool:
+        return super().__contains__(self._apply_hash(key))
+
+
+class DynamicDefaultDict(collections.UserDict[K, V]):
+    """Wrapper of a normal Python `defaultdict` that permits dynamic default values.
+
+    When using a standard Python `defaultdict`, the default value must be decided up-front. This value is used for all missing
+    keys. In contrast, this dictionary implementation allows for the default value to be calculated based on the requested key.
+
+    Parameters
+    ----------
+    factory : Callable[[K], V]
+        A function that generates the value based on a missing key. It receives the key as input and must return the value.
+    """
+
+    def __init__(self, factory: Callable[[K], V]) -> None:
+        super().__init__()
+        self.factory = factory
+
+    def __getitem__(self, k: K) -> V:
+        if k not in self.data:
+            self.data[k] = self.factory(k)
+        return self.data[k]
+
+
+class frozendict(collections.UserDict[K, V]):
+    """Read-only variant of a normal Python dictionary.
+
+    Once the dictionary has been created, its key/value pairs can no longer be modified. At the same time, this allows the
+    dictionary to be hashable by default.
+
+    Parameters
+    ----------
+    items : any, optional
+        Supports the same argument types as the normal dictionary. If no items are supplied, an empty frozen dictionary is
+        returned.
+    """
+
+    def __init__(self, items=None) -> None:
+        self._frozen = False
+        super().__init__(items)
+        self.clear = None
+        self.pop = None
+        self.popitem = None
+        self.update
+        self._frozen = True
+
+    def __setitem__(self, key: K, item: V) -> None:
+        if self._frozen:
+            raise TypeError("Cannot set frozendict entries after creation")
+        return super().__setitem__(key, item)
+
+    def __delitem__(self, key: K) -> None:
+        if self._frozen:
+            raise TypeError("Cannot remove frozendict entries after creation")
+        return super().__delitem__(key)
+
+    def __hash__(self) -> int:
+        return hash_dict(self)

postbound/util/jsonize.py

@@ -0,0 +1,68 @@
+"""Contains utilities to store and load objects more conveniently to/from JSON.
+
+More specifically, this module introduces the `JsonizeEncoder`, which can be accessed via the `to_json` utility method.
+This encoder allows to transform instances of any class to JSON by providing a `__json__` method in the class
+implementation. This method does not take any (required) parameters and returns a JSON-izeable representation of the
+current instance, e.g. a `dict` or a `list`.
+
+Sadly (or luckily?), the inverse conversion does not work because JSON does not store any type information.
+"""
+
+from __future__ import annotations
+
+import abc
+import enum
+import json
+from pathlib import Path
+from typing import IO, Any, Protocol, runtime_checkable
+
+jsondict = dict
+"""Type alias for a JSON-izeable dictionary."""
+
+
+@runtime_checkable
+class Jsonizable(Protocol):
+    """Protocol to indicate that a certain class provides the `__json__` method."""
+
+    @abc.abstractmethod
+    def __json__(self) -> jsondict:
+        raise NotImplementedError
+
+
+class JsonizeEncoder(json.JSONEncoder):
+    """The  JsonizeEncoder allows to transform instances of any class to JSON.
+
+    This can be achieved by providing a `__json__` method in the class implementation. This method does not take any
+    (required) parameters and returns a JSON-izeable representation of the current instance, e.g. a `dict` or a `list`.
+    """
+
+    def default(self, obj: Any) -> Any:
+        if isinstance(obj, enum.Enum):
+            return obj.value
+        elif isinstance(obj, (set, frozenset)):
+            return list(obj)
+        elif isinstance(obj, Path):
+            return str(obj)
+        elif "__json__" in dir(obj):
+            return obj.__json__()
+        return json.JSONEncoder.default(self, obj)
+
+
+def to_json(obj: Any, *args, **kwargs) -> str | None:
+    """Utility to transform any object to a JSON object, while making use of the `JsonizeEncoder`.
+
+    All arguments other than the object itself are passed to the default Python `json.dumps` function.
+    """
+    if obj is None:
+        return None
+    kwargs.pop("cls", None)
+    return json.dumps(obj, *args, cls=JsonizeEncoder, **kwargs)
+
+
+def to_json_dump(obj: Any, file: IO, *args, **kwargs) -> None:
+    """Utility to transform any object to a JSON object and write it to a file, while making use of the `JsonizeEncoder`.
+
+    All arguments other than the object itself are passed to the default Python `json.dump` function.
+    """
+    kwargs.pop("cls", None)
+    json.dump(obj, file, cls=JsonizeEncoder, *args, **kwargs)

postbound/util/logging.py

@@ -0,0 +1,106 @@
+"""Contains utilities to conveniently log different information."""
+
+from __future__ import annotations
+
+import atexit
+import pprint
+import functools
+import sys
+from collections.abc import Callable
+from datetime import datetime
+from typing import IO
+
+
+Logger = Callable[..., None]
+"""Type alias for our loggers.
+
+Each logger accepts an arbitrary amount of arguments and is inteded to function as a replacement for the `print` function.
+"""
+
+
+def timestamp() -> str:
+    """Provides the current time as a nice and normalized string."""
+    return datetime.now().strftime("%y-%m-%d %H:%M:%S")
+
+
+def make_logger(
+    enabled: bool = True,
+    *,
+    file: IO[str] = sys.stderr,
+    pretty: bool = False,
+    prefix: str | Callable[[], str] = "",
+) -> Logger:
+    """Creates a new logging utility.
+
+    The generated method can be used like a regular `print`, but with defaults that are better suited for logging purposes.
+
+    If `enabled` is `False`, calling the logging function will not actually print anything and simply return. This
+    is especially useful to implement logging-hooks in longer functions without permanently re-checking whether logging
+    is enabled or not.
+
+    By default, all logging output will be written to stderr, but this can be customized by supplying a different
+    `file`.
+
+    If `pretty` is enabled, structured objects such as dictionaries will be pretty-printed instead of being written
+    on a single line. Note that pprint is used for all of the logging data everytime in that case.
+
+    Parameters
+    ----------
+    enabled : bool, optional
+        Whether logging is enabled, by default *True*
+    file : IO[str], optional
+        Destination to write the log entries to, by default ``sys.stderr``
+    pretty : bool, optional
+        Whether complex objects should be pretty-printed using the ``pprint`` module, by default *False*
+    prefix : str | Callable[[], str], optional
+        A common prefix that should be added before each log entry. Can be either a hard-coded string, or a callable that
+        dynamically produces a string for each logging action separately (e.g. timestamp).
+
+    Returns
+    -------
+    Callable
+        _description_
+    """
+
+    def _log(*args, **kwargs) -> None:
+        if prefix and isinstance(prefix, str):
+            args = [prefix] + list(args)
+        elif prefix:
+            args = [prefix()] + list(args)
+        print(*args, file=file, **kwargs)
+
+    def _dummy_log(*args, **kwargs) -> None:
+        pass
+
+    if pretty and enabled:
+        return functools.partial(pprint.pprint, stream=file)
+
+    return _log if enabled else _dummy_log
+
+
+def print_stderr(*args, **kwargs) -> None:
+    """A normal `print` that writes to stderr instead of stdout."""
+    kwargs.pop("file", None)
+    print(*args, file=sys.stderr, **kwargs)
+
+
+def print_if(should_print: bool, *args, use_stderr: bool = False, **kwargs) -> None:
+    """A normal `print` that only prints something if `should_print` evaluates true-ish. Can optionally print to stderr."""
+    if should_print:
+        out_device = kwargs.pop("file", sys.stderr if use_stderr else sys.stdout)
+        print(*args, file=out_device, **kwargs)
+
+
+class _TeeLogger:
+    def __init__(self, target_file: str, output_mode: str = "a") -> None:
+        self._original_stdout = sys.stdout
+        self._log_out = open(target_file, output_mode)
+        atexit.register(lambda: self._log_out.close())
+
+    def write(self, message: str) -> None:
+        self._original_stdout.write(message)
+        self._log_out.write(message)
+
+
+def tee_stdout(target_file: str, output_mode: str = "a") -> None:
+    sys.stdout = _TeeLogger(target_file, output_mode)

postbound/util/misc.py

@@ -0,0 +1,168 @@
+"""Contains various utilities that did not fit any other category."""
+
+from __future__ import annotations
+
+import collections
+import re
+from collections.abc import Iterable
+from datetime import datetime
+from typing import Any, Generator, Generic, Optional, TypeVar
+
+from . import jsonize
+
+T = TypeVar("T")
+
+
+def current_timestamp() -> str:
+    """Provides the current time (year-month-day hour:minute)"""
+    return datetime.now().strftime("%y-%m-%d %H:%M")
+
+
+_CamelCasePattern = re.compile(r"(?<!^)(?=[A-Z])")
+
+
+def camel_case2snake_case(camel_case: str) -> str:
+    # adapted from https://stackoverflow.com/a/1176023
+    return _CamelCasePattern.sub("_", camel_case).lower()
+
+
+def _wrap_version(v: Any) -> Version:
+    """Transforms any object into a Version instance if it is not already."""
+    return v if isinstance(v, Version) else Version(v)
+
+
+class Version(jsonize.Jsonizable):
+    """Version instances represent versioning information and ensure that comparison operations work as expected.
+
+    For example, Version instances can be created for strings such as "14.6" or "1.3.1" and ensure that 14.6 > 1.3.1
+    """
+
+    def __init__(self, ver: str | int | list[str] | list[int]) -> None:
+        try:
+            if isinstance(ver, int):
+                self._version = [ver]
+            elif isinstance(ver, str):
+                self._version = [int(v) for v in ver.split(".")]
+            elif isinstance(ver, list) and ver:
+                self._version = [int(v) for v in ver]
+            else:
+                raise ValueError(f"Unknown version string: '{ver}'")
+        except ValueError:
+            raise ValueError(f"Unknown version string: '{ver}'")
+
+    def formatted(self, *, prefix: str = "", suffix: str = "", separator: str = "."):
+        return prefix + separator.join(str(v) for v in self._version) + suffix
+
+    def __json__(self) -> object:
+        return str(self)
+
+    def __eq__(self, __o: object) -> bool:
+        try:
+            other = _wrap_version(__o)
+            if not len(self) == len(other):
+                return False
+            for i in range(len(self)):
+                if not self._version[i] == other._version[i]:
+                    return False
+            return True
+        except ValueError:
+            return False
+
+    def __ge__(self, __o: object) -> bool:
+        return not self < __o
+
+    def __gt__(self, __o: object) -> bool:
+        return not self <= __o
+
+    def __le__(self, __o: object) -> bool:
+        other = _wrap_version(__o)
+        for comp in zip(self._version, other._version):
+            own_version, other_version = comp
+            if own_version < other_version:
+                return True
+            if other_version < own_version:
+                return False
+        return len(self) <= len(other)
+
+    def __lt__(self, __o: object) -> bool:
+        other = _wrap_version(__o)
+        for comp in zip(self._version, other._version):
+            own_version, other_version = comp
+            if own_version < other_version:
+                return True
+            if other_version < own_version:
+                return False
+        return len(self) < len(other)
+
+    def __len__(self) -> int:
+        return len(self._version)
+
+    def __repr__(self) -> str:
+        return str(self)
+
+    def __str__(self) -> str:
+        return "v" + ".".join(str(v) for v in self._version)
+
+
+class DependencyGraph(Generic[T]):
+    """A simple dependency graph abstraction. Entries are added via `add_task` and iteration yields the source nodes first."""
+
+    def __init__(self) -> None:
+        self._source_nodes: set[int] = set()
+        self._dependencies: dict[int, list[int]] = collections.defaultdict(list)
+        self._nodes: dict[int, T] = {}
+
+    def add_task(self, node: T, *, depends_on: Optional[Iterable[T]] = None) -> None:
+        """Queues a new task/entry/whatever.
+
+        Parameters
+        ----------
+        node : T
+            The new task
+        depends_on : Optional[Iterable[T]], optional
+            Optional other tasks that have to be completed before this one. If those task have not been added yet, this will
+            be done automatically.
+        """
+        node_id = hash(node)
+        self._nodes[node_id] = node
+
+        if not depends_on:
+            self._source_nodes.add(node_id)
+            return
+
+        if node_id in self._source_nodes:
+            self._source_nodes.remove(node_id)
+
+        for dep in depends_on:
+            dep_id = hash(dep)
+            self._dependencies[dep_id].append(node_id)
+
+            if dep_id not in self._nodes:
+                self._source_nodes.add(dep_id)
+                self._nodes[dep_id] = dep
+
+    def __iter__(self) -> Generator[T, Any, None]:
+        provided_nodes: set[int] = set()
+        for node_id in self._source_nodes:
+            yield self._nodes[node_id]
+
+            provided_nodes.add(node_id)
+            dependency_stack = list(self._dependencies[node_id])
+
+            while dependency_stack:
+                dep_id = dependency_stack.pop()
+                if dep_id in provided_nodes:
+                    continue
+
+                yield self._nodes[dep_id]
+
+                provided_nodes.add(dep_id)
+                dependency_stack.extend(self._dependencies[dep_id])
+        provided_nodes = set()
+
+    def __repr__(self) -> str:
+        return str(self)
+
+    def __str__(self) -> str:
+        nodes_str = ", ".join(str(node) for node in self._nodes.values())
+        return f"DependencyGraph({nodes_str})"