python-corekit 0.1.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

corekit/data/record.py

@@ -1,147 +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__}
+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

@@ -1,157 +1,162 @@
-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
+import statistics
+from collections import Counter
+from dataclasses import dataclass
+from dataclasses import field as dataclass_field
+from typing import Any, Iterator
+
+from corekit.utils.coercion import safe_tuple
+
+
+@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:
+        # all([]) is True, which would then call statistics.fmean([]) and crash.
+        if not self.non_missing:
+            return False
+        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 = safe_tuple(schema)
+
+    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

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