isik 0.1.0__py3-none-any.whl

isik/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

isik/_internal/__init__.py

@@ -0,0 +1,11 @@
+import importlib
+
+
+def check_extra(extra_name, package_name):
+    try:
+        importlib.import_module(package_name)
+    except ImportError as exception:
+        raise ImportError(
+            f"The module you are trying to use requires '{extra_name}'. "
+            f"Please install it with: pip install isik[{extra_name}]"
+        ) from exception

isik/common/config/__init__.py

@@ -0,0 +1,25 @@
+from isik.common.config.builder import Config, config
+from isik.common.config.casters import (
+    boolean,
+    caster,
+    comma_separated_float_list,
+    comma_separated_int_list,
+    comma_separated_list,
+    integer,
+    string,
+)
+from isik.common.config.exceptions import ConfigError
+
+
+__all__ = [
+    "Config",
+    "ConfigError",
+    "boolean",
+    "caster",
+    "comma_separated_float_list",
+    "comma_separated_int_list",
+    "comma_separated_list",
+    "config",
+    "integer",
+    "string",
+]

isik/common/config/builder.py

@@ -0,0 +1,105 @@
+import os
+
+from isik.common.config.exceptions import ConfigError
+
+
+_MISSING = object()
+
+
+class Config(dict):
+    """
+    A dict that also allows attribute access, e.g. config.DATABASE.HOST, and can reload its
+    values from the environment via refresh() - callable on the root config or on any nested
+    one, refreshing just that subtree in place so existing references to it see the update too.
+
+    A schema key that collides with a dict method name (items, keys, ...) or with refresh
+    itself is only reachable via item access (config["refresh"]), not attribute access.
+    """
+
+    __setattr__ = dict.__setitem__
+
+    def __getattr__(self, name):
+        try:
+            return self[name]
+        except KeyError as exc:
+            raise AttributeError(name) from exc
+
+    def refresh(self, *path):
+        """
+        Re-read values from the environment, in place. With no arguments, refreshes every
+        value under this node. With a path of key names, refreshes only that one nested
+        value instead - e.g. config.refresh("DATABASE", "HOST") or, equivalently,
+        config.DATABASE.refresh("HOST").
+        """
+        if not path:
+            for key in self._schema:
+                self._refresh_key(key)
+            return self
+
+        key, *rest = path
+        if rest:
+            self[key].refresh(*rest)
+        else:
+            self._refresh_key(key)
+        return self
+
+    def _refresh_key(self, key):
+        try:
+            value = self._schema[key]
+        except KeyError:
+            raise ConfigError(f"'{key}' is not a key in this config.") from None
+        if isinstance(value, dict):
+            self[key].refresh()
+        else:
+            self[key] = _read_leaf(value, _environment_key(self._prefix, [*self._path, key], self._sep))
+
+
+def _environment_key(prefix, path, sep):
+    return sep.join([*([prefix] if prefix else []), *path])
+
+
+def _read_leaf(caster, environment_key):
+    try:
+        raw_value = os.environ[environment_key]
+    except KeyError:
+        default = getattr(caster, "missing_default", _MISSING)
+        if default is _MISSING:
+            raise ConfigError(
+                f"Environment variable {environment_key} not found."
+                f" Please set it or provide a `missing_default` to your caster."
+            ) from None
+        return default
+
+    try:
+        return caster(raw_value)
+    except Exception as exception:
+        default = getattr(caster, "error_default", _MISSING)
+        if default is _MISSING:
+            raise ConfigError(
+                f"Error while parsing {environment_key}={raw_value!r} with '{caster}'."
+                " Please check the value and the caster or provide an `error_default` to your caster."
+            ) from exception
+        return default
+
+
+def _build(data, path, prefix, sep):
+    result = Config()
+    object.__setattr__(result, "_schema", data)
+    object.__setattr__(result, "_path", path)
+    object.__setattr__(result, "_prefix", prefix)
+    object.__setattr__(result, "_sep", sep)
+    for key, value in data.items():
+        key_path = [*path, key]
+        if isinstance(value, dict):
+            result[key] = _build(value, key_path, prefix, sep)
+        elif callable(value):
+            result[key] = _read_leaf(value, _environment_key(prefix, key_path, sep))
+        else:
+            raise ConfigError(
+                f"Values either must be callables or other mappings, not {type(value)}. Key={'.'.join(key_path)}."
+            )
+    return result
+
+
+def config(data, *, prefix=None, sep="__"):
+    return _build(data, [], prefix, sep)

isik/common/config/casters.py

@@ -0,0 +1,56 @@
+from functools import wraps
+
+
+def caster(f):
+    """
+    Turns a plain string->value function into a config caster that accepts an optional
+    missing_default (used when the environment variable isn't set) and error_default (used
+    when f(value) raises). Neither is set by default, meaning a missing or unparseable
+    value raises ConfigError instead.
+    """
+    sentinel = object()
+
+    def wrapper(missing_default=sentinel, error_default=sentinel):
+        @wraps(f)
+        def function_clone(value):
+            return f(value)
+
+        if missing_default is not sentinel:
+            function_clone.missing_default = missing_default
+        if error_default is not sentinel:
+            function_clone.error_default = error_default
+        return function_clone
+
+    return wrapper
+
+
+@caster
+def comma_separated_list(value):
+    return value.split(",")
+
+
+@caster
+def comma_separated_int_list(value):
+    return [int(i) for i in value.split(",")]
+
+
+@caster
+def comma_separated_float_list(value):
+    return [float(i) for i in value.split(",")]
+
+
+@caster
+def boolean(value):
+    truthy = ["true", "True", "1"]
+    falsy = ["false", "False", "0"]
+
+    if value in truthy:
+        return True
+    elif value in falsy:
+        return False
+    else:
+        raise ValueError(f"Value {value!r} can not be parsed into a boolean.")
+
+
+string = caster(str)
+integer = caster(int)

isik/common/config/exceptions.py

@@ -0,0 +1 @@
+class ConfigError(ValueError): ...

isik/common/utils/__init__.py

@@ -0,0 +1,46 @@
+from isik.common.utils.caching import get_cached
+from isik.common.utils.concurrency import ContextLocal, ThreadLocal, ThreadLock
+from isik.common.utils.error_handling import SuppressAndRun, TransformExceptions, suppress_callable
+from isik.common.utils.functional import (
+    cloned,
+    enabled_if,
+    identity,
+    noop,
+    raises,
+    require_exclusive_keys,
+    returns,
+    with_attrs,
+)
+from isik.common.utils.iterables import all_combinations, first_of, not_none, purge_iterable, purge_mapping
+from isik.common.utils.metaclasses import transform
+from isik.common.utils.sentinel import Sentinel
+from isik.common.utils.strings import camel_to_snake, snake_to_human, snake_to_pascal
+
+
+__all__ = [
+    "ContextLocal",
+    "Sentinel",
+    "SuppressAndRun",
+    "ThreadLocal",
+    "ThreadLock",
+    "TransformExceptions",
+    "all_combinations",
+    "camel_to_snake",
+    "cloned",
+    "enabled_if",
+    "first_of",
+    "get_cached",
+    "identity",
+    "noop",
+    "not_none",
+    "purge_iterable",
+    "purge_mapping",
+    "raises",
+    "require_exclusive_keys",
+    "returns",
+    "snake_to_human",
+    "snake_to_pascal",
+    "suppress_callable",
+    "transform",
+    "with_attrs",
+]

isik/common/utils/caching.py

@@ -0,0 +1,21 @@
+def get_cached(obj, attr, factory):
+    """
+    Get a cached attribute from an object, computing and storing it if absent.
+
+    Bypasses __getattribute__ via object.__getattribute__ and object.__setattr__,
+    making it safe to call from within a custom __getattribute__ implementation.
+
+    Args:
+        obj: The object to cache the attribute on.
+        attr: The attribute name to use as the cache key.
+        factory: A zero-argument callable that computes the value on cache miss.
+
+    Returns:
+        The cached value if present, otherwise the result of calling factory().
+    """
+    try:
+        return object.__getattribute__(obj, attr)
+    except AttributeError:
+        value = factory()
+        object.__setattr__(obj, attr, value)
+        return value

isik/common/utils/concurrency.py

@@ -0,0 +1,83 @@
+import threading
+from contextvars import ContextVar
+
+
+class ThreadLocal:
+    """
+    A factory for thread local identified by name.
+    Calling ThreadLocal("FOO") returns a thread local object shared across all calls with the same name.
+    """
+
+    _registry = {}
+    _registry_lock = threading.Lock()
+
+    def __new__(cls, name):
+        if name not in cls._registry:
+            with cls._registry_lock:
+                if name not in cls._registry:
+                    cls._registry[name] = threading.local()
+        return cls._registry[name]
+
+
+class ThreadLock:
+    """
+    A factory for thread lock identified by name.
+    Calling ThreadLock("FOO") returns a lock object shared across all calls with the same name.
+    """
+
+    _registry = {}
+    _registry_lock = threading.Lock()
+
+    def __new__(cls, name):
+        if name not in cls._registry:
+            with cls._registry_lock:
+                if name not in cls._registry:
+                    cls._registry[name] = threading.Lock()
+        return cls._registry[name]
+
+
+class ContextLocal:
+    """
+    A named, registry-backed namespace of ContextVars.
+    Calling ContextLocal("FOO") returns the same instance across all calls with the same name,
+    making it safe for async and coroutine contexts.
+
+    Usage:
+        local = ContextLocal("MY_NAMESPACE")
+        token = local.set("foo", "bar")
+        local.get("foo")  # "bar"
+        local.get("foo", "default")  # "bar"
+        local.reset("foo", token)
+    """
+
+    _registry = {}
+    _registry_lock = threading.Lock()
+
+    def __new__(cls, name):
+        if name not in cls._registry:
+            with cls._registry_lock:
+                if name not in cls._registry:
+                    instance = super().__new__(cls)
+                    object.__setattr__(instance, "_name", name)
+                    object.__setattr__(instance, "_vars", {})
+                    cls._registry[name] = instance
+        return cls._registry[name]
+
+    def _get_var(self, key):
+        vars_ = object.__getattribute__(self, "_vars")
+        if key not in vars_:
+            name = object.__getattribute__(self, "_name")
+            vars_[key] = ContextVar(f"{name}.{key}")
+        return vars_[key]
+
+    def get(self, key, *args):
+        """Get a value. Accepts an optional default as a second argument, like dict.get()."""
+        return self._get_var(key).get(*args)
+
+    def set(self, key, value):
+        """Set a value and return a token that can be used to restore the previous state."""
+        return self._get_var(key).set(value)
+
+    def reset(self, key, token):
+        """Reset a value to its state before the corresponding set() call."""
+        self._get_var(key).reset(token)

isik/common/utils/error_handling.py

@@ -0,0 +1,155 @@
+from contextlib import ContextDecorator, suppress
+from functools import wraps
+
+from isik.common.utils.functional import require_exclusive_keys
+
+
+class TransformExceptions(ContextDecorator):
+    """
+    A context manager and decorator that catches the given exception types and transforms
+    them into a new exception via a transformation function.
+
+    Args:
+        *exception_types: One or more exception types to catch and transform.
+        transform: A callable that receives the original exception and returns a new one.
+                   Can be left out and filled in later - see the two-step form below.
+        keep_original: If True (default), the original exception is chained to the new one
+                       via `raise new from original`, preserving the traceback context.
+                       If False, the original exception is suppressed and the new one is
+                       raised in isolation.
+
+    Raises:
+        Whatever exception `transform` returns: at call time if a matching exception is caught.
+
+    Example:
+        @TransformExceptions(ValueError, transform=lambda e: MyCustomError(str(e)))
+        def parse(x):
+            ...
+
+        with TransformExceptions(ValueError, KeyError, transform=lambda e: MyCustomError(str(e))):
+            ...
+
+        # Without chaining:
+        with TransformExceptions(ValueError, transform=lambda e: MyCustomError(str(e)), keep_original=False):
+            ...
+
+        # Two-step form: give it exception types now, decorate the transform function
+        # later - useful when the transform itself is more than a lambda one-liner.
+        # The transform function becomes a named, reusable decorator.
+        @TransformExceptions(ValueError)
+        def value_error_to_my_error(e):
+            return MyCustomError(str(e))
+
+        @value_error_to_my_error
+        def parse(x):
+            ...
+    """
+
+    def __init__(self, *exception_types, transform=None, keep_original=True):
+        self.exception_types = exception_types
+        self.transform = transform
+        self.keep_original = keep_original
+
+    def __call__(self, func):
+        if self.transform is None:
+            # two-step form: `func` is the transform, not the guarded code
+            self.transform = func
+            return self
+        return super().__call__(func)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if isinstance(exc_val, self.exception_types):
+            if self.transform is None:
+                raise TypeError(
+                    "TransformExceptions has no transform set - "
+                    "pass transform=... or decorate a transform function with it first."
+                )
+            new_exception = self.transform(exc_val)
+            raise new_exception from (exc_val if self.keep_original else None)
+        return False
+
+
+class SuppressAndRun(suppress):
+    """
+    A context manager that suppresses the given exceptions and calls a function with the
+    suppressed exception.
+
+    Extends contextlib.suppress with the ability to run a callable when an exception is
+    suppressed, for example to log it, print it, or send it to an error tracker.
+
+    Args:
+        *exceptions: One or more exception types to suppress.
+        func: A callable that receives the suppressed exception as its only argument.
+              Defaults to print. Must accept a single exception argument.
+
+    Example:
+        with SuppressAndRun(ValueError, func=logger.warning):
+            raise ValueError("oops")  # suppressed, logger.warning called with the exception
+
+        with SuppressAndRun(ValueError, KeyError, func=my_handler):
+            ...
+    """
+
+    def __init__(self, *exceptions, func=print):
+        super().__init__(*exceptions)
+        self.func = func
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        suppressed = super().__exit__(exc_type, exc_val, exc_tb)
+        if suppressed:
+            self.func(exc_val)
+        return suppressed
+
+
+@require_exclusive_keys(
+    {"by_return_value": ["return_value"]},
+    {"by_return_func": ["return_func"]},
+    allow_empty=True,
+)
+def suppress_callable(*exceptions, func=print, return_value=None, return_func=None):
+    """
+    A decorator that suppresses the given exceptions, calls func with the suppressed
+    exception, and returns either a static value or the result of a replacement function.
+
+    Args:
+        *exceptions: One or more exception types to suppress.
+        func: A callable that receives the suppressed exception as its only argument.
+              Defaults to print.
+        return_value: A static value to return when an exception is suppressed.
+                      Mutually exclusive with return_func.
+        return_func: A callable with the same signature as the decorated function.
+                     Called with the original arguments when an exception is suppressed.
+                     Mutually exclusive with return_value.
+
+    Raises:
+        ValueError: If both return_value and return_func are provided.
+
+    Example:
+        @suppress_callable(ValueError, func=logger.warning, return_value=0)
+        def parse(x):
+            ...
+
+        @suppress_callable(ValueError, return_func=lambda x: x * 0)
+        def parse(x):
+            ...
+
+        @suppress_callable(ValueError)
+        def parse(x):
+            ...  # returns None when suppressed
+    """
+
+    def decorator(f):
+        @wraps(f)
+        def wrapper(*a, **kw):
+            with SuppressAndRun(*exceptions, func=func):
+                return f(*a, **kw)
+            if return_func is not None:
+                return return_func(*a, **kw)
+            return return_value
+
+        return wrapper
+
+    return decorator