etlplus 0.16.0__py3-none-any.whl → 0.16.3__py3-none-any.whl

etlplus/api/types.py

@@ -53,7 +53,31 @@ __all__ = [
 # SECTION: CONSTANTS ======================================================== #
 
 
-_UNSET = object()
+_UNSET: object = object()
+
+
+# SECTION: INTERNAL FUNCTIONS =============================================== #
+
+
+def _to_dict(
+    value: Mapping[str, Any] | object | None,
+) -> dict[str, Any] | None:
+    """
+    Return a defensive ``dict`` copy for mapping inputs.
+
+    Parameters
+    ----------
+    value : Mapping[str, Any] | object | None
+        Mapping to copy, or ``None``.
+
+    Returns
+    -------
+    dict[str, Any] | None
+        New ``dict`` instance or ``None`` when the input is ``None``.
+    """
+    if value is None:
+        return None
+    return cast(dict[str, Any], value)
 
 
 # SECTION: TYPED DICTS ====================================================== #
@@ -176,9 +200,9 @@ class RequestOptions:
 
     def __post_init__(self) -> None:
         if self.params is not None:
-            object.__setattr__(self, 'params', dict(self.params))
+            object.__setattr__(self, 'params', _to_dict(self.params))
         if self.headers is not None:
-            object.__setattr__(self, 'headers', dict(self.headers))
+            object.__setattr__(self, 'headers', _to_dict(self.headers))
 
     # -- Instance Methods -- #
 
@@ -224,23 +248,20 @@ class RequestOptions:
 
         Returns
         -------
-        RequestOptions
+        Self
             New snapshot reflecting the provided overrides.
         """
         if params is _UNSET:
             next_params = self.params
-        elif params is None:
-            next_params = None
         else:
-            next_params = cast(dict, params)
+            # next_params = _to_dict(params) if params is not None else None
+            next_params = _to_dict(params)
 
         if headers is _UNSET:
             next_headers = self.headers
-        elif headers is None:
-            next_headers = None
         else:
-            next_headers = cast(dict, headers)
-
+            # next_headers = _to_dict(headers) if headers is not None else None
+            next_headers = _to_dict(headers)
         if timeout is _UNSET:
             next_timeout = self.timeout
         else:

etlplus/enums.py

@@ -1,18 +1,14 @@
 """
 :mod:`etlplus.enums` module.
 
-Shared enumeration types used across ETLPlus modules.
+Shared enumeration base class.
 """
 
 from __future__ import annotations
 
 import enum
-import operator as _op
-from statistics import fmean
 from typing import Self
 
-from .types import AggregateFunc
-from .types import OperatorFunc
 from .types import StrStrMap
 
 # SECTION: EXPORTS ========================================================== #
@@ -20,10 +16,7 @@ from .types import StrStrMap
 
 __all__ = [
     # Enums
-    'AggregateName',
     'CoercibleStrEnum',
-    'OperatorName',
-    'PipelineStep',
 ]
 
 
@@ -41,6 +34,7 @@ class CoercibleStrEnum(enum.StrEnum):
     Notes
     -----
     - Values are normalized via ``str(value).strip().casefold()``.
+    - If value matching fails, the raw string is tried as a member name.
     - Error messages enumerate allowed values for easier debugging.
     """
 
@@ -56,7 +50,13 @@ class CoercibleStrEnum(enum.StrEnum):
         Returns
         -------
         StrStrMap
-            A mapping of alias names to their corresponding enum member names.
+            A mapping of alias strings to their corresponding enum member
+            values or names.
+
+        Notes
+        -----
+        - Alias keys are normalized via ``str(key).strip().casefold()``.
+        - Alias values should be member values or member names.
         """
         return {}
 
@@ -80,7 +80,7 @@ class CoercibleStrEnum(enum.StrEnum):
         Parameters
         ----------
         value : Self | str | object
-            An existing enum member or a text value to normalize.
+            An existing enum member or a string-like value to normalize.
 
         Returns
         -------
@@ -95,10 +95,26 @@ class CoercibleStrEnum(enum.StrEnum):
         if isinstance(value, cls):
             return value
         try:
-            normalized = str(value).strip().casefold()
-            resolved = cls.aliases().get(normalized, normalized)
-            return cls(resolved)  # type: ignore[arg-type]
-        except (ValueError, TypeError) as e:
+            raw = str(value).strip()
+            normalized = raw.casefold()
+            aliases = {
+                str(key).strip().casefold(): alias
+                for key, alias in cls.aliases().items()
+            }
+            resolved = aliases.get(normalized)
+            if resolved is None:
+                try:
+                    return cls(normalized)  # type: ignore[arg-type]
+                except (ValueError, TypeError):
+                    return cls[raw]  # type: ignore[index]
+            if isinstance(resolved, cls):
+                return resolved
+            try:
+                return cls(resolved)  # type: ignore[arg-type]
+            except (ValueError, TypeError):
+                # Allow aliases to reference member names.
+                return cls[resolved]  # type: ignore[index]
+        except (ValueError, TypeError, KeyError) as e:
             allowed = ', '.join(cls.choices())
             raise ValueError(
                 f'Invalid {cls.__name__} value: {value!r}. Allowed: {allowed}',
@@ -107,15 +123,15 @@ class CoercibleStrEnum(enum.StrEnum):
     @classmethod
     def try_coerce(
         cls,
-        value: object,
+        value: Self | str | object,
     ) -> Self | None:
         """
-        Best-effort parse; return ``None`` on failure instead of raising.
+        Attempt to coerce a value into the enum; return ``None`` on failure.
 
         Parameters
         ----------
-        value : object
-            An existing enum member or a text value to normalize.
+        value : Self | str | object
+            An existing enum member or a string-like value to normalize.
 
         Returns
         -------
@@ -124,153 +140,5 @@ class CoercibleStrEnum(enum.StrEnum):
         """
         try:
             return cls.coerce(value)
-        except ValueError:
+        except (ValueError, TypeError, KeyError):
             return None
-
-
-# SECTION: ENUMS ============================================================ #
-
-
-class AggregateName(CoercibleStrEnum):
-    """Supported aggregations with helpers."""
-
-    # -- Constants -- #
-
-    AVG = 'avg'
-    COUNT = 'count'
-    MAX = 'max'
-    MIN = 'min'
-    SUM = 'sum'
-
-    # -- Class Methods -- #
-
-    @property
-    def func(self) -> AggregateFunc:
-        """
-        Get the aggregation function for this aggregation type.
-
-        Returns
-        -------
-        AggregateFunc
-            The aggregation function corresponding to this aggregation type.
-        """
-        if self is AggregateName.COUNT:
-            return lambda xs, n: n
-        if self is AggregateName.MAX:
-            return lambda xs, n: (max(xs) if xs else None)
-        if self is AggregateName.MIN:
-            return lambda xs, n: (min(xs) if xs else None)
-        if self is AggregateName.SUM:
-            return lambda xs, n: sum(xs)
-
-        # AVG
-        return lambda xs, n: (fmean(xs) if xs else 0.0)
-
-
-class OperatorName(CoercibleStrEnum):
-    """Supported comparison operators with helpers."""
-
-    # -- Constants -- #
-
-    EQ = 'eq'
-    NE = 'ne'
-    GT = 'gt'
-    GTE = 'gte'
-    LT = 'lt'
-    LTE = 'lte'
-    IN = 'in'
-    CONTAINS = 'contains'
-
-    # -- Getters -- #
-
-    @property
-    def func(self) -> OperatorFunc:
-        """
-        Get the comparison function for this operator.
-
-        Returns
-        -------
-        OperatorFunc
-            The comparison function corresponding to this operator.
-        """
-        match self:
-            case OperatorName.EQ:
-                return _op.eq
-            case OperatorName.NE:
-                return _op.ne
-            case OperatorName.GT:
-                return _op.gt
-            case OperatorName.GTE:
-                return _op.ge
-            case OperatorName.LT:
-                return _op.lt
-            case OperatorName.LTE:
-                return _op.le
-            case OperatorName.IN:
-                return lambda a, b: a in b
-            case OperatorName.CONTAINS:
-                return lambda a, b: b in a
-
-    # -- Class Methods -- #
-
-    @classmethod
-    def aliases(cls) -> StrStrMap:
-        """
-        Return a mapping of common aliases for each enum member.
-
-        Returns
-        -------
-        StrStrMap
-            A mapping of alias names to their corresponding enum member names.
-        """
-        return {
-            '==': 'eq',
-            '=': 'eq',
-            '!=': 'ne',
-            '<>': 'ne',
-            '>=': 'gte',
-            '≥': 'gte',
-            '<=': 'lte',
-            '≤': 'lte',
-            '>': 'gt',
-            '<': 'lt',
-        }
-
-
-class PipelineStep(CoercibleStrEnum):
-    """Pipeline step names as an enum for internal orchestration."""
-
-    # -- Constants -- #
-
-    FILTER = 'filter'
-    MAP = 'map'
-    SELECT = 'select'
-    SORT = 'sort'
-    AGGREGATE = 'aggregate'
-
-    # -- Getters -- #
-
-    @property
-    def order(self) -> int:
-        """
-        Get the execution order of this pipeline step.
-
-        Returns
-        -------
-        int
-            The execution order of this pipeline step.
-        """
-        return _PIPELINE_ORDER_INDEX[self]
-
-
-# SECTION: INTERNAL CONSTANTS ============================================== #
-
-
-# Precomputed order index for PipelineStep; avoids recomputing on each access.
-_PIPELINE_ORDER_INDEX: dict[PipelineStep, int] = {
-    PipelineStep.FILTER: 0,
-    PipelineStep.MAP: 1,
-    PipelineStep.SELECT: 2,
-    PipelineStep.SORT: 3,
-    PipelineStep.AGGREGATE: 4,
-}

etlplus/ops/__init__.py

@@ -52,6 +52,7 @@ from .validate import validate
 
 
 __all__ = [
+    # Functions
     'extract',
     'load',
     'run',

etlplus/ops/enums.py

@@ -0,0 +1,173 @@
+"""
+:mod:`etlplus.ops.enums` module.
+
+Operation-specific enums and helpers.
+"""
+
+from __future__ import annotations
+
+import operator as _op
+from statistics import fmean
+
+from ..enums import CoercibleStrEnum
+from ..types import StrStrMap
+from .types import AggregateFunc
+from .types import OperatorFunc
+
+# SECTION: EXPORTS ========================================================= #
+
+
+__all__ = [
+    # Enums
+    'AggregateName',
+    'OperatorName',
+    'PipelineStep',
+]
+
+
+# SECTION: ENUMS ============================================================ #
+
+
+class AggregateName(CoercibleStrEnum):
+    """Supported aggregations with helpers."""
+
+    # -- Constants -- #
+
+    AVG = 'avg'
+    COUNT = 'count'
+    MAX = 'max'
+    MIN = 'min'
+    SUM = 'sum'
+
+    # -- Class Methods -- #
+
+    @property
+    def func(self) -> AggregateFunc:
+        """
+        Get the aggregation function for this aggregation type.
+
+        Returns
+        -------
+        AggregateFunc
+            The aggregation function corresponding to this aggregation type.
+        """
+        if self is AggregateName.COUNT:
+            return lambda xs, n: n
+        if self is AggregateName.MAX:
+            return lambda xs, n: (max(xs) if xs else None)
+        if self is AggregateName.MIN:
+            return lambda xs, n: (min(xs) if xs else None)
+        if self is AggregateName.SUM:
+            return lambda xs, n: sum(xs)
+
+        # AVG
+        return lambda xs, n: (fmean(xs) if xs else 0.0)
+
+
+class OperatorName(CoercibleStrEnum):
+    """Supported comparison operators with helpers."""
+
+    # -- Constants -- #
+
+    EQ = 'eq'
+    NE = 'ne'
+    GT = 'gt'
+    GTE = 'gte'
+    LT = 'lt'
+    LTE = 'lte'
+    IN = 'in'
+    CONTAINS = 'contains'
+
+    # -- Getters -- #
+
+    @property
+    def func(self) -> OperatorFunc:
+        """
+        Get the comparison function for this operator.
+
+        Returns
+        -------
+        OperatorFunc
+            The comparison function corresponding to this operator.
+        """
+        match self:
+            case OperatorName.EQ:
+                return _op.eq
+            case OperatorName.NE:
+                return _op.ne
+            case OperatorName.GT:
+                return _op.gt
+            case OperatorName.GTE:
+                return _op.ge
+            case OperatorName.LT:
+                return _op.lt
+            case OperatorName.LTE:
+                return _op.le
+            case OperatorName.IN:
+                return lambda a, b: a in b
+            case OperatorName.CONTAINS:
+                return lambda a, b: b in a
+
+    # -- Class Methods -- #
+
+    @classmethod
+    def aliases(cls) -> StrStrMap:
+        """
+        Return a mapping of common aliases for each enum member.
+
+        Returns
+        -------
+        StrStrMap
+            A mapping of alias names to their corresponding enum member names.
+        """
+        return {
+            '==': 'eq',
+            '=': 'eq',
+            '!=': 'ne',
+            '<>': 'ne',
+            '>=': 'gte',
+            '≥': 'gte',
+            '<=': 'lte',
+            '≤': 'lte',
+            '>': 'gt',
+            '<': 'lt',
+        }
+
+
+class PipelineStep(CoercibleStrEnum):
+    """Pipeline step names as an enum for internal orchestration."""
+
+    # -- Constants -- #
+
+    FILTER = 'filter'
+    MAP = 'map'
+    SELECT = 'select'
+    SORT = 'sort'
+    AGGREGATE = 'aggregate'
+
+    # -- Getters -- #
+
+    @property
+    def order(self) -> int:
+        """
+        Get the execution order of this pipeline step.
+
+        Returns
+        -------
+        int
+            The execution order of this pipeline step.
+        """
+        return _PIPELINE_ORDER_INDEX[self]
+
+
+# SECTION: INTERNAL CONSTANTS ============================================== #
+
+
+# Precomputed order index for PipelineStep; avoids recomputing on each access.
+_PIPELINE_ORDER_INDEX: dict[PipelineStep, int] = {
+    PipelineStep.FILTER: 0,
+    PipelineStep.MAP: 1,
+    PipelineStep.SELECT: 2,
+    PipelineStep.SORT: 3,
+    PipelineStep.AGGREGATE: 4,
+}