etlplus 0.16.2__tar.gz → 0.16.3__tar.gz

{etlplus-0.16.2/etlplus.egg-info → etlplus-0.16.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: etlplus
-Version: 0.16.2
+Version: 0.16.3
 Summary: A Swiss Army knife for simple ETL operations
 Home-page: https://github.com/Dagitali/ETLPlus
 Author: ETLPlus Team

etlplus-0.16.3/etlplus/enums.py

@@ -0,0 +1,144 @@
+"""
+:mod:`etlplus.enums` module.
+
+Shared enumeration base class.
+"""
+
+from __future__ import annotations
+
+import enum
+from typing import Self
+
+from .types import StrStrMap
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    # Enums
+    'CoercibleStrEnum',
+]
+
+
+# SECTION: CLASSES ========================================================== #
+
+
+class CoercibleStrEnum(enum.StrEnum):
+    """
+    StrEnum with ergonomic helpers.
+
+    Provides a DRY, class-level :meth:`coerce` that normalizes inputs and
+    produces consistent, informative error messages. Also exposes
+    :meth:`choices` for UI/validation and :meth:`try_coerce` for soft parsing.
+
+    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.
+    """
+
+    # -- Class Methods -- #
+
+    @classmethod
+    def aliases(cls) -> StrStrMap:
+        """
+        Return a mapping of common aliases for each enum member.
+
+        Subclasses may override this method to provide custom aliases.
+
+        Returns
+        -------
+        StrStrMap
+            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 {}
+
+    @classmethod
+    def choices(cls) -> tuple[str, ...]:
+        """
+        Return the allowed string values for this enum.
+
+        Returns
+        -------
+        tuple[str, ...]
+            A tuple of allowed string values for this enum.
+        """
+        return tuple(member.value for member in cls)
+
+    @classmethod
+    def coerce(cls, value: Self | str | object) -> Self:
+        """
+        Convert an enum member or string-like input to a member of *cls*.
+
+        Parameters
+        ----------
+        value : Self | str | object
+            An existing enum member or a string-like value to normalize.
+
+        Returns
+        -------
+        Self
+            The corresponding enum member.
+
+        Raises
+        ------
+        ValueError
+            If the value cannot be coerced into a valid member.
+        """
+        if isinstance(value, cls):
+            return value
+        try:
+            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}',
+            ) from e
+
+    @classmethod
+    def try_coerce(
+        cls,
+        value: Self | str | object,
+    ) -> Self | None:
+        """
+        Attempt to coerce a value into the enum; return ``None`` on failure.
+
+        Parameters
+        ----------
+        value : Self | str | object
+            An existing enum member or a string-like value to normalize.
+
+        Returns
+        -------
+        Self | None
+            The corresponding enum member, or ``None`` if coercion fails.
+        """
+        try:
+            return cls.coerce(value)
+        except (ValueError, TypeError, KeyError):
+            return None

{etlplus-0.16.2 → etlplus-0.16.3}/etlplus/ops/__init__.py

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

{etlplus-0.16.2/etlplus → etlplus-0.16.3/etlplus/ops}/enums.py

@@ -1,133 +1,30 @@
 """
-:mod:`etlplus.enums` module.
+:mod:`etlplus.ops.enums` module.
 
-Shared enumeration types used across ETLPlus modules.
+Operation-specific enums and helpers.
 """
 
 from __future__ import annotations
 
-import enum
 import operator as _op
 from statistics import fmean
-from typing import Self
 
+from ..enums import CoercibleStrEnum
+from ..types import StrStrMap
 from .types import AggregateFunc
 from .types import OperatorFunc
-from .types import StrStrMap
 
-# SECTION: EXPORTS ========================================================== #
+# SECTION: EXPORTS ========================================================= #
 
 
 __all__ = [
     # Enums
     'AggregateName',
-    'CoercibleStrEnum',
     'OperatorName',
     'PipelineStep',
 ]
 
 
-# SECTION: CLASSES ========================================================== #
-
-
-class CoercibleStrEnum(enum.StrEnum):
-    """
-    StrEnum with ergonomic helpers.
-
-    Provides a DRY, class-level :meth:`coerce` that normalizes inputs and
-    produces consistent, informative error messages. Also exposes
-    :meth:`choices` for UI/validation and :meth:`try_coerce` for soft parsing.
-
-    Notes
-    -----
-    - Values are normalized via ``str(value).strip().casefold()``.
-    - Error messages enumerate allowed values for easier debugging.
-    """
-
-    # -- Class Methods -- #
-
-    @classmethod
-    def aliases(cls) -> StrStrMap:
-        """
-        Return a mapping of common aliases for each enum member.
-
-        Subclasses may override this method to provide custom aliases.
-
-        Returns
-        -------
-        StrStrMap
-            A mapping of alias names to their corresponding enum member names.
-        """
-        return {}
-
-    @classmethod
-    def choices(cls) -> tuple[str, ...]:
-        """
-        Return the allowed string values for this enum.
-
-        Returns
-        -------
-        tuple[str, ...]
-            A tuple of allowed string values for this enum.
-        """
-        return tuple(member.value for member in cls)
-
-    @classmethod
-    def coerce(cls, value: Self | str | object) -> Self:
-        """
-        Convert an enum member or string-like input to a member of *cls*.
-
-        Parameters
-        ----------
-        value : Self | str | object
-            An existing enum member or a text value to normalize.
-
-        Returns
-        -------
-        Self
-            The corresponding enum member.
-
-        Raises
-        ------
-        ValueError
-            If the value cannot be coerced into a valid member.
-        """
-        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:
-            allowed = ', '.join(cls.choices())
-            raise ValueError(
-                f'Invalid {cls.__name__} value: {value!r}. Allowed: {allowed}',
-            ) from e
-
-    @classmethod
-    def try_coerce(
-        cls,
-        value: object,
-    ) -> Self | None:
-        """
-        Best-effort parse; return ``None`` on failure instead of raising.
-
-        Parameters
-        ----------
-        value : object
-            An existing enum member or a text value to normalize.
-
-        Returns
-        -------
-        Self | None
-            The corresponding enum member, or ``None`` if coercion fails.
-        """
-        try:
-            return cls.coerce(value)
-        except ValueError:
-            return None
-
-
 # SECTION: ENUMS ============================================================ #
 
 

{etlplus-0.16.2 → etlplus-0.16.3}/etlplus/ops/run.py

@@ -13,9 +13,9 @@ from typing import cast
 from ..api import HttpMethod
 from ..connector import DataConnectorType
 from ..file import FileFormat
+from ..ops.types import PipelineConfig
 from ..types import JSONData
 from ..types import JSONDict
-from ..types import PipelineConfig
 from ..types import StrPath
 from ..utils import print_json
 from ..workflow import load_pipeline_config

{etlplus-0.16.2 → etlplus-0.16.3}/etlplus/ops/transform.py

@@ -44,28 +44,28 @@ from collections.abc import Sequence
 from typing import Any
 from typing import cast
 
-from ..enums import AggregateName
-from ..enums import OperatorName
-from ..enums import PipelineStep
-from ..types import AggregateFunc
-from ..types import AggregateSpec
-from ..types import FieldName
-from ..types import Fields
-from ..types import FilterSpec
+from ..ops.types import PipelineConfig
 from ..types import JSONData
 from ..types import JSONDict
 from ..types import JSONList
-from ..types import MapSpec
-from ..types import OperatorFunc
-from ..types import PipelineConfig
-from ..types import PipelineStepName
-from ..types import SortKey
-from ..types import StepApplier
-from ..types import StepOrSteps
-from ..types import StepSpec
 from ..types import StrPath
 from ..utils import to_number
+from .enums import AggregateName
+from .enums import OperatorName
+from .enums import PipelineStep
 from .load import load_data
+from .types import AggregateFunc
+from .types import AggregateSpec
+from .types import FieldName
+from .types import Fields
+from .types import FilterSpec
+from .types import MapSpec
+from .types import OperatorFunc
+from .types import PipelineStepName
+from .types import SortKey
+from .types import StepApplier
+from .types import StepOrSteps
+from .types import StepSpec
 
 # SECTION: EXPORTS ========================================================== #
 

etlplus-0.16.3/etlplus/ops/types.py

@@ -0,0 +1,147 @@
+"""
+:mod:`etlplus.ops.types` module.
+
+Shared type aliases leveraged across :mod:`etlplus.ops` modules.
+
+Notes
+-----
+- Centralizes ops-focused aliases (functions, specs, and pipeline helpers).
+- Relies on Python 3.13 ``type`` statements for readability and IDE support.
+
+Examples
+--------
+>>> from etlplus.ops.types import AggregateFunc, OperatorFunc
+>>> def total(xs: list[float], _: int) -> float:
+...     return sum(xs)
+>>> agg: AggregateFunc = total
+>>> op: OperatorFunc = lambda a, b: a == b
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from collections.abc import Mapping
+from collections.abc import Sequence
+from typing import Any
+from typing import Literal
+
+from ..types import JSONList
+from ..types import StrAnyMap
+from ..types import StrSeqMap
+from ..types import StrStrMap
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    # Type Aliases (Functions)
+    'AggregateFunc',
+    'OperatorFunc',
+    # Type Aliases (Records & Fields)
+    'FieldName',
+    'Fields',
+    # Type Aliases (Transform Specs)
+    'AggregateSpec',
+    'FilterSpec',
+    'MapSpec',
+    'SelectSpec',
+    'SortSpec',
+    # Type Aliases (Pipelines)
+    'StepOrSteps',
+    'StepSeq',
+    'StepSpec',
+    'PipelineConfig',
+    'PipelineStepName',
+    # Type Aliases (Helpers)
+    'StepApplier',
+    'SortKey',
+]
+
+
+# SECTION: TYPE ALIASES ===================================================== #
+
+
+# -- Functions -- #
+
+
+# TODO: Consider redefining to use `functools.reduce` signature.
+# TODO: Consider adding `**kwargs` to support richer aggregation functions.
+# TODO: Consider constraining first argument to `Sequence[float]`.
+# TODO: Consider constraining return type to `float | int | None`.
+# Callable reducing numeric collections into a summary value.
+type AggregateFunc = Callable[[list[float], int], Any]
+
+# Binary predicate consumed by filter operations.
+type OperatorFunc = Callable[[Any, Any], bool]
+
+# -- Records & Fields -- #
+
+# Individual field identifier referenced inside specs.
+type FieldName = str
+
+# Ordered list of :data:`FieldName` entries preserving projection order.
+type Fields = list[FieldName]
+
+# -- Transform Specs -- #
+
+# Filtering spec expecting ``field``, ``op``, and ``value`` keys.
+type FilterSpec = StrAnyMap
+
+# Field renaming instructions mapping old keys to new ones.
+type MapSpec = StrStrMap
+
+# Projection spec as a field list or mapping with metadata.
+#
+# Examples
+# --------
+# >>> from etlplus.ops.types import SelectSpec
+# >>> spec1: SelectSpec = ['a','b']
+# >>> spec2: SelectSpec = {'fields': [...]}
+type SelectSpec = Fields | StrSeqMap
+
+# Sort directive expressed as a field string or mapping with flags.
+#
+# Examples
+# --------
+# >>> from etlplus.ops.types import SortSpec
+# >>> spec1: SortSpec = 'field'
+# >>> spec2: SortSpec = {'field': 'x', 'reverse': True}
+type SortSpec = str | StrAnyMap
+
+# Aggregate instruction covering ``field``, ``func``, and optional alias.
+#
+# Supported functions: ``avg``, ``count``, ``max``, ``min``, and ``sum``.
+# Examples
+# --------
+# >>> from etlplus.ops.types import AggregateSpec
+# >>> spec: AggregateSpec = \
+# ...   {'field': 'x', 'func': 'sum' | 'avg' | ..., 'alias'?: '...'}
+type AggregateSpec = StrAnyMap
+
+# -- Pipelines-- #
+
+# Unified pipeline step spec consumed by :mod:`etlplus.ops.transform`.
+type StepSpec = AggregateSpec | FilterSpec | MapSpec | SelectSpec | SortSpec
+
+# Collections of steps
+
+# Ordered collection of :data:`StepSpec` entries.
+type StepSeq = Sequence[StepSpec]
+
+# Accepts either a single :data:`StepSpec` or a sequence of them.
+type StepOrSteps = StepSpec | StepSeq
+
+# Canonical literal names for supported transform stages.
+type PipelineStepName = Literal['aggregate', 'filter', 'map', 'select', 'sort']
+
+# Mapping from step name to its associated specification payload.
+# TODO: Consider replacing with etlplus.workflow.types.PipelineConfig.
+type PipelineConfig = Mapping[PipelineStepName, StepOrSteps]
+
+# -- Helpers -- #
+
+# Callable that applies step configuration to a batch of records.
+type StepApplier = Callable[[JSONList, Any], JSONList]
+
+# Tuple combining stable sort index and computed sort value.
+type SortKey = tuple[int, Any]

{etlplus-0.16.2 → etlplus-0.16.3}/etlplus/types.py

@@ -53,30 +53,10 @@ __all__ = [
     'JSONRecords',
     # Type Aliases (File System)
     'StrPath',
-    # Type Aliases (Functions)
-    'AggregateFunc',
-    'OperatorFunc',
-    # Type Aliases (Records & Fields)
-    'FieldName',
-    'Fields',
     # Type Aliases (Transform Specs)
     'StrAnyMap',
     'StrSeqMap',
     'StrStrMap',
-    'AggregateSpec',
-    'FilterSpec',
-    'MapSpec',
-    'SelectSpec',
-    'SortSpec',
-    # Type Aliases (Pipelines)
-    'StepOrSteps',
-    'StepSeq',
-    'StepSpec',
-    'PipelineStepName',
-    'PipelineConfig',
-    # Type Aliases (Helpers)
-    'StepApplier',
-    'SortKey',
     # Type Aliases (Networking / Runtime)
     'Sleeper',
     'Timeout',
@@ -126,22 +106,6 @@ type JSONRecords = list[JSONRecord]
 # Path-like inputs accepted by file helpers.
 type StrPath = str | Path | PathLike[str]
 
-# -- Functions -- #
-
-# Callable reducing numeric collections into a summary value.
-type AggregateFunc = Callable[[list[float], int], Any]
-
-# Binary predicate consumed by filter operations.
-type OperatorFunc = Callable[[Any, Any], bool]
-
-# -- Records & Fields -- #
-
-# Individual field identifier referenced inside specs.
-type FieldName = str
-
-# Ordered list of :data:`FieldName` entries preserving projection order.
-type Fields = list[FieldName]
-
 # -- Transform Specs -- #
 
 # Kept intentionally broad for runtime-friendly validation in transform.py.
@@ -157,69 +121,6 @@ type StrStrMap = Mapping[str, str]
 # Mapping whose values are homogeneous sequences.
 type StrSeqMap = Mapping[str, Sequence[Any]]
 
-# Transform step specifications
-
-# Filtering spec expecting ``field``, ``op``, and ``value`` keys.
-type FilterSpec = StrAnyMap
-
-# Field renaming instructions mapping old keys to new ones.
-type MapSpec = StrStrMap
-
-# Projection spec as a field list or mapping with metadata.
-#
-# Examples
-# --------
-# >>> from etlplus.types import SelectSpec
-# >>> spec1: SelectSpec = ['a','b']
-# >>> spec2: SelectSpec = {'fields': [...]}
-type SelectSpec = Fields | StrSeqMap
-
-# Sort directive expressed as a field string or mapping with flags.
-#
-# Examples
-# --------
-# >>> from etlplus.types import SortSpec
-# >>> spec1: SortSpec = 'field'
-# >>> spec2: SortSpec = {'field': 'x', 'reverse': True}
-type SortSpec = str | StrAnyMap
-
-# Aggregate instruction covering ``field``, ``func``, and optional alias.
-#
-# Supported functions: ``avg``, ``count``, ``max``, ``min``, and ``sum``.
-# Examples
-# --------
-# >>> from etlplus.types import AggregateSpec
-# >>> spec: AggregateSpec = \
-# ...   {'field': 'x', 'func': 'sum' | 'avg' | ..., 'alias'?: '...'}
-type AggregateSpec = StrAnyMap
-
-# -- Pipelines-- #
-
-# Unified pipeline step spec consumed by :mod:`etlplus.ops.transform`.
-type StepSpec = AggregateSpec | FilterSpec | MapSpec | SelectSpec | SortSpec
-
-# Collections of steps
-
-# Ordered collection of :data:`StepSpec` entries.
-type StepSeq = Sequence[StepSpec]
-
-# Accepts either a single :data:`StepSpec` or a sequence of them.
-type StepOrSteps = StepSpec | StepSeq
-
-# Canonical literal names for supported transform stages.
-type PipelineStepName = Literal['filter', 'map', 'select', 'sort', 'aggregate']
-
-# Mapping from step name to its associated specification payload.
-type PipelineConfig = Mapping[PipelineStepName, StepOrSteps]
-
-# -- Helpers -- #
-
-# Callable that applies step configuration to a batch of records.
-type StepApplier = Callable[[JSONList, Any], JSONList]
-
-# Tuple combining stable sort index and computed sort value.
-type SortKey = tuple[int, Any]
-
 # -- Networking / Runtime -- #
 
 # Sleep function used by retry helpers.

{etlplus-0.16.2 → etlplus-0.16.3/etlplus.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: etlplus
-Version: 0.16.2
+Version: 0.16.3
 Summary: A Swiss Army knife for simple ETL operations
 Home-page: https://github.com/Dagitali/ETLPlus
 Author: ETLPlus Team

{etlplus-0.16.2 → etlplus-0.16.3}/etlplus.egg-info/SOURCES.txt

@@ -147,10 +147,12 @@ etlplus/file/zip.py
 etlplus/file/zsav.py
 etlplus/ops/README.md
 etlplus/ops/__init__.py
+etlplus/ops/enums.py
 etlplus/ops/extract.py
 etlplus/ops/load.py
 etlplus/ops/run.py
 etlplus/ops/transform.py
+etlplus/ops/types.py
 etlplus/ops/utils.py
 etlplus/ops/validate.py
 etlplus/templates/README.md
@@ -164,7 +166,7 @@ etlplus/workflow/jobs.py
 etlplus/workflow/pipeline.py
 etlplus/workflow/profile.py
 examples/README.md
-examples/quickstart_python.py
+examples/quickstart.py
 examples/configs/ddl_spec.yml
 examples/configs/pipeline.yml
 examples/data/sample.csv
@@ -184,7 +186,6 @@ tests/integration/test_i_run.py
 tests/integration/test_i_run_profile_pagination_defaults.py
 tests/integration/test_i_run_profile_rate_limit_defaults.py
 tests/unit/conftest.py
-tests/unit/test_u_enums.py
 tests/unit/test_u_main.py
 tests/unit/test_u_mixins.py
 tests/unit/test_u_utils.py
@@ -219,6 +220,7 @@ tests/unit/database/test_u_database_schema.py
 tests/unit/file/test_u_file_core.py
 tests/unit/file/test_u_file_enums.py
 tests/unit/file/test_u_file_yaml.py
+tests/unit/ops/test_u_ops_enums.py
 tests/unit/ops/test_u_ops_extract.py
 tests/unit/ops/test_u_ops_load.py
 tests/unit/ops/test_u_ops_run.py

{etlplus-0.16.2 → etlplus-0.16.3}/examples/README.md

@@ -7,7 +7,7 @@ A few self-contained examples to get you started quickly.
 Run a tiny ETL in Python using the sample data shipped in this repo.
 
 ```bash
-python examples/quickstart_python.py
+python examples/quickstart.py
 ```
 
 What it does: