etlplus 0.15.0__py3-none-any.whl → 0.16.6__py3-none-any.whl

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,11 +16,7 @@ from .types import StrStrMap
 
 __all__ = [
     # Enums
-    'AggregateName',
     'CoercibleStrEnum',
-    'DataConnectorType',
-    'OperatorName',
-    'PipelineStep',
 ]
 
 
@@ -42,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.
     """
 
@@ -57,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 {}
 
@@ -76,12 +75,12 @@ class CoercibleStrEnum(enum.StrEnum):
     @classmethod
     def coerce(cls, value: Self | str | object) -> Self:
         """
-        Convert an enum member or string-like input to a member of ``cls``.
+        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.
+            An existing enum member or a string-like value to normalize.
 
         Returns
         -------
@@ -96,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}',
@@ -108,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
         -------
@@ -125,184 +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 DataConnectorType(CoercibleStrEnum):
-    """Supported data connector types."""
-
-    # -- Constants -- #
-
-    API = 'api'
-    DATABASE = 'database'
-    FILE = 'file'
-
-    # -- 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 {
-            'http': 'api',
-            'https': 'api',
-            'rest': 'api',
-            'db': 'database',
-            'filesystem': 'file',
-            'fs': 'file',
-        }
-
-
-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/file/_imports.py

@@ -12,6 +12,7 @@ from typing import Any
 # SECTION: INTERNAL CONSTANTS =============================================== #
 
 
+# Optional Python module support (lazy-loaded to avoid hard dependency)
 _MODULE_CACHE: dict[str, Any] = {}
 
 

etlplus/file/_io.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 
 import csv
 from pathlib import Path
+from typing import Any
 from typing import cast
 
 from ..types import JSONData
@@ -17,6 +18,44 @@ from ..types import JSONList
 # SECTION: FUNCTIONS ======================================================== #
 
 
+def coerce_record_payload(
+    payload: Any,
+    *,
+    format_name: str,
+) -> JSONData:
+    """
+    Validate that *payload* is an object or list of objects.
+
+    Parameters
+    ----------
+    payload : Any
+        Parsed payload to validate.
+    format_name : str
+        Human-readable format name for error messages.
+
+    Returns
+    -------
+    JSONData
+        *payload* when it is a dict or a list of dicts.
+
+    Raises
+    ------
+    TypeError
+        If the payload is not a dict or list of dicts.
+    """
+    if isinstance(payload, dict):
+        return cast(JSONDict, payload)
+    if isinstance(payload, list):
+        if all(isinstance(item, dict) for item in payload):
+            return cast(JSONList, payload)
+        raise TypeError(
+            f'{format_name} array must contain only objects (dicts)',
+        )
+    raise TypeError(
+        f'{format_name} root must be an object or an array of objects',
+    )
+
+
 def normalize_records(
     data: JSONData,
     format_name: str,
@@ -50,9 +89,13 @@ def normalize_records(
     return [cast(JSONDict, data)]
 
 
-def read_delimited(path: Path, *, delimiter: str) -> JSONList:
+def read_delimited(
+    path: Path,
+    *,
+    delimiter: str,
+) -> JSONList:
     """
-    Read delimited content from ``path``.
+    Read delimited content from *path*.
 
     Parameters
     ----------
@@ -79,9 +122,14 @@ def read_delimited(path: Path, *, delimiter: str) -> JSONList:
     return rows
 
 
-def write_delimited(path: Path, data: JSONData, *, delimiter: str) -> int:
+def write_delimited(
+    path: Path,
+    data: JSONData,
+    *,
+    delimiter: str,
+) -> int:
     """
-    Write ``data`` to a delimited file and return record count.
+    Write *data* to a delimited file and return record count.
 
     Parameters
     ----------

etlplus/file/accdb.py

@@ -28,6 +28,7 @@ from . import stub
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -40,7 +41,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read ACCDB content from ``path``.
+    Read ACCDB content from *path*.
 
     Parameters
     ----------
@@ -60,7 +61,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to ACCDB at ``path`` and return record count.
+    Write *data* to ACCDB at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/arrow.py

@@ -28,6 +28,7 @@ from . import stub
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -40,7 +41,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read ARROW content from ``path``.
+    Read ARROW content from *path*.
 
     Parameters
     ----------
@@ -60,7 +61,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to ARROW at ``path`` and return record count.
+    Write *data* to ARROW at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/avro.py

@@ -33,6 +33,7 @@ from ._io import normalize_records
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -124,7 +125,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read AVRO content from ``path``.
+    Read AVRO content from *path*.
 
     Parameters
     ----------
@@ -147,7 +148,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to AVRO at ``path`` and return record count.
+    Write *data* to AVRO at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/bson.py

@@ -27,6 +27,7 @@ from . import stub
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -39,7 +40,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read BSON content from ``path``.
+    Read BSON content from *path*.
 
     Parameters
     ----------
@@ -59,7 +60,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to BSON at ``path`` and return record count.
+    Write *data* to BSON at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/cbor.py

@@ -28,6 +28,7 @@ from . import stub
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -40,7 +41,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read CBOR content from ``path``.
+    Read CBOR content from *path*.
 
     Parameters
     ----------
@@ -60,7 +61,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to CBOR at ``path`` and return record count.
+    Write *data* to CBOR at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/cfg.py

@@ -29,6 +29,7 @@ from . import stub
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -41,7 +42,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read CFG content from ``path``.
+    Read CFG content from *path*.
 
     Parameters
     ----------
@@ -61,7 +62,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to CFG file at ``path`` and return record count.
+    Write *data* to CFG file at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/conf.py

@@ -30,6 +30,7 @@ from . import stub
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -42,7 +43,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read CONF content from ``path``.
+    Read CONF content from *path*.
 
     Parameters
     ----------
@@ -62,7 +63,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to CONF at ``path`` and return record count.
+    Write *data* to CONF at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/core.py

@@ -22,7 +22,10 @@ from .enums import infer_file_format_and_compression
 # SECTION: EXPORTS ========================================================== #
 
 
-__all__ = ['File']
+__all__ = [
+    # Classes
+    'File',
+]
 
 
 # SECTION: INTERNAL FUNCTIONS =============================================== #
@@ -30,7 +33,7 @@ __all__ = ['File']
 
 def _accepts_root_tag(handler: object) -> bool:
     """
-    Return True when ``handler`` supports a ``root_tag`` argument.
+    Return True when *handler* supports a ``root_tag`` argument.
 
     Parameters
     ----------
@@ -57,7 +60,7 @@ def _accepts_root_tag(handler: object) -> bool:
 @cache
 def _module_for_format(file_format: FileFormat) -> ModuleType:
     """
-    Import and return the module for ``file_format``.
+    Import and return the module for *file_format*.
 
     Parameters
     ----------
@@ -112,8 +115,8 @@ class File:
         """
         Auto-detect and set the file format on initialization.
 
-        If no explicit ``file_format`` is provided, attempt to infer it from
-        the file path's extension and update :attr:`file_format`. If the
+        If no explicit :attr:`file_format` is provided, attempt to infer it
+        from the file path's extension and update :attr:`file_format`. If the
         extension is unknown, the attribute is left as ``None`` and will be
         validated later by :meth:`_ensure_format`.
         """
@@ -262,7 +265,7 @@ class File:
 
     def read(self) -> JSONData:
         """
-        Read structured data from :attr:`path` using :attr:`file_format`.
+        Read structured data from :attr:path` using :attr:`file_format`.
 
         Returns
         -------
@@ -291,7 +294,7 @@ class File:
         root_tag: str = xml.DEFAULT_XML_ROOT,
     ) -> int:
         """
-        Write ``data`` to :attr:`path` using :attr:`file_format`.
+        Write *data* to *path* using :attr:`file_format`.
 
         Parameters
         ----------
@@ -299,7 +302,7 @@ class File:
             Data to write to the file.
         root_tag : str, optional
             Root tag name to use when writing XML files. Defaults to
-            ``'root'``.
+            ``xml.DEFAULT_XML_ROOT``.
 
         Returns
         -------

etlplus/file/csv.py

@@ -29,6 +29,7 @@ from ._io import write_delimited
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -41,7 +42,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read CSV content from ``path``.
+    Read CSV content from *path*.
 
     Parameters
     ----------
@@ -61,7 +62,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to CSV at ``path`` and return record count.
+    Write *data* to CSV at *path* and return record count.
 
     Parameters
     ----------

etlplus/file/dat.py

@@ -28,6 +28,7 @@ from . import stub
 
 
 __all__ = [
+    # Functions
     'read',
     'write',
 ]
@@ -40,7 +41,7 @@ def read(
     path: Path,
 ) -> JSONList:
     """
-    Read DAT content from ``path``.
+    Read DAT content from *path*.
 
     Parameters
     ----------
@@ -60,7 +61,7 @@ def write(
     data: JSONData,
 ) -> int:
     """
-    Write ``data`` to DAT file at ``path`` and return record count.
+    Write *data* to DAT file at *path* and return record count.
 
     Parameters
     ----------