python-corekit 0.1.0__py3-none-any.whl

corekit/data/expressions/expression.py

@@ -0,0 +1,98 @@
+from typing import Any
+
+
+class Expression:
+    """
+    Base class for composable predicates. Subclasses implement __call__
+    """
+
+    def __call__(self, *args: Any, **kwargs: Any) -> bool:
+        raise NotImplementedError
+
+    def __and__(self, other: "Expression") -> "Expression":
+        return And(self, other)
+
+    def __or__(self, other: "Expression") -> "Expression":
+        return Or(self, other)
+
+    def __invert__(self) -> "Expression":
+        return Not(self)
+
+    def to_sql(self, *args: Any, **kwargs: Any) -> str:
+        raise NotImplementedError
+
+    def to_mongo(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
+        raise NotImplementedError
+
+    def to_elasticsearch(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
+        raise NotImplementedError
+
+
+class And(Expression):
+    def __init__(self, left: Expression, right: Expression) -> None:
+        self.left = left
+        self.right = right
+
+    def __call__(self, *args: Any, **kwargs: Any) -> bool:
+        return bool(self.left(*args, **kwargs)) and bool(self.right(*args, **kwargs))
+
+    def __repr__(self) -> str:
+        return f"({self.left!r} & {self.right!r})"
+
+    def to_sql(self, *args: Any, **kwargs: Any) -> str:
+        return f"({self.left.to_sql(*args, **kwargs)} AND {self.right.to_sql(*args, **kwargs)})"
+
+    def to_mongo(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
+        return {"$and": [self.left.to_mongo(), self.right.to_mongo()]}
+
+    def to_elasticsearch(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
+        return {
+            "bool": {
+                "must": [self.left.to_elasticsearch(*args, **kwargs), self.right.to_elasticsearch(*args, **kwargs)]
+            }
+        }
+
+
+class Or(Expression):
+    def __init__(self, left: Expression, right: Expression) -> None:
+        self.left = left
+        self.right = right
+
+    def __call__(self, *args: Any, **kwargs: Any) -> bool:
+        return bool(self.left(*args, **kwargs)) or bool(self.right(*args, **kwargs))
+
+    def __repr__(self) -> str:
+        return f"({self.left!r} | {self.right!r})"
+
+    def to_sql(self, *args: Any, **kwargs: Any) -> str:
+        return f"({self.left.to_sql(*args, **kwargs)} OR {self.right.to_sql(*args, **kwargs)})"
+
+    def to_mongo(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
+        return {"$or": [self.left.to_mongo(*args, **kwargs), self.right.to_mongo(*args, **kwargs)]}
+
+    def to_elasticsearch(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
+        return {
+            "bool": {
+                "should": [self.left.to_elasticsearch(*args, **kwargs), self.right.to_elasticsearch(*args, **kwargs)]
+            }
+        }
+
+
+class Not(Expression):
+    def __init__(self, expr: Expression) -> None:
+        self.expr = expr
+
+    def __call__(self, *args: Any, **kwargs: Any) -> bool:
+        return not self.expr(*args, **kwargs)
+
+    def __repr__(self) -> str:
+        return f"~{self.expr!r}"
+
+    def to_sql(self, *args: Any, **kwargs: Any) -> str:
+        return f"NOT ({self.expr.to_sql(*args, **kwargs)})"
+
+    def to_mongo(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
+        return {"$not": self.expr.to_mongo(*args, **kwargs)}
+
+    def to_elasticsearch(self, *args: Any, **kwargs: Any) -> dict[str, Any] | str:
+        return {"bool": {"must_not": self.expr.to_elasticsearch(*args, **kwargs)}}

corekit/data/record.py

@@ -0,0 +1,147 @@
+import functools
+import keyword
+import logging
+from typing import Any, Callable, Iterator
+
+logger = logging.getLogger(__name__)
+
+
+def is_valid_key(key: Any) -> bool:
+    return isinstance(key, str) and key.isidentifier() and not keyword.iskeyword(key)
+
+
+def return_constant(value: Any) -> Any:
+    return value
+
+
+def resolve_default(default: Any, default_factory: Callable[[], Any] | None) -> Callable[[], Any]:
+    """
+    Normalize (default, default_factory) into a single zero-arg factory.
+
+    Raises on a raw mutable default (list/dict/set/bytearray), since that
+    object would otherwise be shared by reference across every record;
+    use default_factory instead. The non-factory path returns
+    functools.partial(_return_constant, default) rather than a lambda,
+    since a local lambda can't be pickled.
+    """
+    if default_factory is not None:
+        if default is not None:
+            logger.warning("Both default and default_factory were provided. Prioritizing default_factory.")
+        return default_factory
+
+    if isinstance(default, (list, dict, set, bytearray)):
+        raise TypeError(
+            f"mutable default {default!r} would be shared by reference across every "
+            f"record; use default_factory instead (e.g. default_factory=list)"
+        )
+    return functools.partial(return_constant, default)
+
+
+def reconstruct_record(fields: tuple, values: tuple) -> "BaseRecord":
+    """
+    Rebuild a record on unpickling. Module-level so pickle can reference
+    it by import path -- the record's actual class is generated
+    dynamically and has no module path of its own.
+    """
+    cls = BaseRecord.create_new(fields)
+    instance = cls()
+    for key, value in zip(fields, values):
+        instance[key] = value
+    return instance
+
+
+class BaseRecord:
+    """
+    Base class for dynamically generated, schema-specific record types.
+
+    Subclasses are built per-dataset by create_new() with __slots__ for
+    each field, so instances carry no per-record __dict__ overhead.
+    __slots__ = () here means this base itself adds nothing on top of
+    that.
+    """
+
+    __slots__ = ()
+    __fieldmap__ = {}
+
+    @staticmethod
+    def create_new(fields: tuple) -> type:
+        """
+        Build a record class for the given field names.
+
+        Fields that aren't valid Python identifiers get a synthetic slot
+        name (_slot_0, _slot_1, ...) instead, tracked via __fieldmap__
+        so dict-style access (record["weird field"]) still works.
+        Synthetic names are checked against real field names so a field
+        literally named "_slot_0" can't collide with one.
+        """
+        fieldmap: dict[Any, str] = {}
+        slot_names: list[str] = []
+        reserved = {key for key in fields if is_valid_key(key)}
+        used: set[str] = set()
+        counter = 0
+        for key in fields:
+            if is_valid_key(key):
+                slot = key
+            else:
+                candidate = f"_slot_{counter}"
+                counter += 1
+                while candidate in reserved or candidate in used:
+                    candidate = f"_slot_{counter}"
+                    counter += 1
+                slot = candidate
+            used.add(slot)
+            fieldmap[key] = slot
+            slot_names.append(slot)
+        return type("Record", (BaseRecord,), {"__slots__": tuple(slot_names), "__fieldmap__": fieldmap})
+
+    def __getitem__(self, key: Any) -> Any:
+        slot = self.__fieldmap__.get(key, key)
+        try:
+            return getattr(self, slot)
+        except AttributeError:
+            raise KeyError(key) from None
+
+    def __setitem__(self, key: Any, value: Any) -> Any:
+        slot = self.__fieldmap__.get(key)
+        if slot is None:
+            raise KeyError(f"{key!r} does not exist for record: {self}")
+        setattr(self, slot, value)
+
+    def __contains__(self, key: Any) -> bool:
+        return key in self.__fieldmap__
+
+    def __iter__(self) -> Iterator[Any]:
+        return iter(self.__fieldmap__)
+
+    def __len__(self) -> int:
+        return len(self.__fieldmap__)
+
+    def __eq__(self, other: Any) -> bool:
+        """
+        Value equality: same fields and values, not same object.
+
+        Records are mutable, so __hash__ is implicitly disabled once
+        __eq__ is defined (Python does this automatically) -- that's
+        intentional, not an oversight, since a hashable object whose
+        hash can change under mutation is unsafe to use as a dict/set key.
+        """
+        if isinstance(other, BaseRecord):
+            return self.to_dict() == other.to_dict()
+        if isinstance(other, dict):
+            return self.to_dict() == other
+        return NotImplemented
+
+    def __repr__(self) -> str:
+        fields = ", ".join(f"{key}={self[key]!r}" for key in self.__fieldmap__)
+        return f"{type(self).__name__}({fields})"
+
+    def __reduce__(self) -> tuple:
+        """
+        Pickle as (reconstruct_fn, (fields, values)); see _reconstruct_record
+        """
+        fields = tuple(self.__fieldmap__.keys())
+        values = tuple(self[k] for k in fields)
+        return reconstruct_record, (fields, values)
+
+    def to_dict(self) -> dict[Any, Any]:
+        return {k: self[k] for k in self.__fieldmap__}

corekit/data/stats.py

@@ -0,0 +1,157 @@
+import statistics
+from collections import Counter
+from dataclasses import dataclass
+from dataclasses import field as dataclass_field
+from typing import Any, Iterator
+
+
+@dataclass(slots=True)
+class FieldStats:
+    """
+    Common shape shared by every field's statistics
+    """
+
+    field: Any
+    count: int
+    missing: int
+
+
+@dataclass(slots=True)
+class NumericFieldStats(FieldStats):
+    """
+    Stats for a field where every non-missing value is int/float (not bool)
+    """
+
+    mean: float
+    min: Any
+    max: Any
+    stdev: float
+
+
+@dataclass(slots=True)
+class CategoricalFieldStats(FieldStats):
+    """
+    Stats for any field that isn't purely numeric
+    """
+
+    unique: int
+    top: Any
+    freq: int
+
+
+@dataclass(slots=True)
+class ValueCounts:
+    """
+    How often each distinct value of a field occurs, most frequent first
+    """
+
+    field: Any
+    counts: dict[Any, int]
+
+    def most_common(self, n: int | None = None) -> list[tuple[Any, int]]:
+        items = list(self.counts.items())
+        return items[:n] if n is not None else items
+
+    def top(self) -> tuple[Any, int] | None:
+        return next(iter(self.counts.items()), None)
+
+    def __iter__(self) -> Iterator[tuple[Any, int]]:
+        return iter(self.counts.items())
+
+    def __len__(self) -> int:
+        return len(self.counts)
+
+    def __getitem__(self, value: Any) -> int:
+        return self.counts[value]
+
+
+@dataclass(slots=True)
+class FieldDescription:
+    field: Any
+    values: list[Any] = dataclass_field(default_factory=list)
+    non_missing: list[Any] = dataclass_field(default_factory=list)
+    num_values: int = dataclass_field(default=0)
+    num_non_missing: int = dataclass_field(default=0)
+
+    @classmethod
+    def from_data(cls, data: list[Any], field: Any) -> "FieldDescription":
+        instance = cls(field)
+        for record in data:
+            instance.add(record[field])
+        return instance
+
+    @property
+    def missing(self) -> int:
+        return self.num_values - self.num_non_missing
+
+    @property
+    def is_numeric(self) -> bool:
+        return all(isinstance(v, (int, float)) and not isinstance(v, bool) for v in self.non_missing)
+
+    def to_field_stats(self) -> FieldStats:
+        if self.is_numeric:
+            return NumericFieldStats(
+                field=self.field,
+                count=self.num_non_missing,
+                missing=self.missing,
+                mean=statistics.fmean(self.non_missing),
+                min=min(self.non_missing),
+                max=max(self.non_missing),
+                stdev=statistics.stdev(self.non_missing) if self.num_non_missing > 1 else 0.0,
+            )
+
+        counts = Counter(self.non_missing)
+        top_value, top_count = counts.most_common(1)[0] if counts else (None, 0)
+        return CategoricalFieldStats(
+            field=self.field,
+            count=self.num_non_missing,
+            missing=self.missing,
+            unique=len(counts),
+            top=top_value,
+            freq=top_count,
+        )
+
+    def add(self, value: Any) -> None:
+        self.values.append(value)
+        self.num_values += 1
+        if value is not None:
+            self.non_missing.append(value)
+            self.num_non_missing += 1
+
+
+class DatasetStats:
+    """
+    Read-only field statistics for a Dataset's current records.
+
+    Computed fresh on every call from the dataset's public interface (never
+    cached), so there's nothing here that can go stale after a mutation --
+    the same reasoning that ruled out persistent secondary indexes applies:
+    recomputing is cheap and always correct, caching is not free and can lie.
+    """
+
+    def __init__(self, data: list[Any], schema: tuple[Any, ...] | None = None) -> None:
+        self._data = data
+        self._schema = schema or ()
+
+    def value_counts(self, field: Any) -> ValueCounts:
+        """
+        How often each distinct value of `field` occurs, most frequent first
+        """
+        counts = dict(Counter(rec[field] for rec in self._data).most_common())
+        return ValueCounts(field=field, counts=counts)
+
+    def describe(self, field: Any | None = None) -> dict[Any, FieldStats]:
+        """
+        Summary statistics per field, pandas-.describe()-style.
+
+        Numeric fields (int/float, excluding bool) get a NumericFieldStats
+        (mean/min/max/stdev). Everything else gets a CategoricalFieldStats
+        (unique/top/freq). Pass `field` to describe just one; omit to
+        describe every field in the schema.
+        """
+        fields = (field,) if field is not None else self._schema
+        stats = {}
+        for f in fields:
+            field_description = FieldDescription.from_data(self._data, f)
+            stats[f] = field_description.to_field_stats()
+        return stats

corekit/decorators/__init__.py

@@ -0,0 +1,2 @@
+from .exception_handling import exception_handler
+from .warnings import deprecated

corekit/decorators/exception_handling.py

@@ -0,0 +1,43 @@
+import functools
+import logging
+from typing import Any, Callable
+
+from corekit.utils import raise_exc, void
+
+logger = logging.getLogger(__name__)
+
+
+def exception_handler(
+    ignore: list[type[Exception]] | None = None,
+    callback: Callable = raise_exc,
+    ignore_callback: Callable = void,
+) -> Any:
+    """
+    A decorator to handle exceptions in a class method or function.
+
+    Args:
+        ignore: exception classes to suppress. These do not propagate.
+        callback: called when an exception is raised that is not ignored.
+        ignore_callback: called when a suppressed exception is raised.
+    """
+    exceptions_to_ignore = tuple(ignore) if ignore else tuple()
+
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return func(*args, **kwargs)
+            except Exception as ex:
+                # If in ignore list, suppress and invoke the ignore_callback function
+                if isinstance(ex, exceptions_to_ignore):
+                    logger.warning(f"Suppressed exception in {func.__name__}: {ex}")
+                    logger.info(f"Invoking callback function: {ignore_callback.__name__}")
+                    return ignore_callback(ex, *args, **kwargs)
+
+                # Log the exception and invoke the callback function, returning its return value (if any)
+                logger.error(f"Exception in {func.__name__}: {ex}", exc_info=True)
+                return callback(ex, *args, **kwargs)
+
+        return wrapper
+
+    return decorator

corekit/decorators/warnings.py

@@ -0,0 +1,35 @@
+import functools
+import logging
+import warnings
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def deprecated(
+    message: str,
+    exception: type[Exception] | None = None,
+) -> Any:
+    """
+    A decorator to mark a function as deprecated
+
+    Args:
+        message (str): The message to display when the function is deprecated
+        exception (Exception | None): An optional exception to raise
+    """
+
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            if exception:
+                raise exception(message)
+            # A real warning, so linters, test runners and -W flags can see
+            # it; the log line alone is invisible to all of them. stacklevel=2
+            # points at the caller rather than at this wrapper.
+            warnings.warn(f"{func.__name__} is deprecated: {message}", DeprecationWarning, stacklevel=2)
+            logger.warning(f"[DEPRECATION WARNING]: {func.__name__} is deprecated: {message}")
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

corekit/docker/__init__.py

@@ -0,0 +1,7 @@
+"""
+Docker container control.
+"""
+
+from corekit.docker.watchdog import Watchdog
+
+__all__ = ["Watchdog"]