etlplus 0.16.0__py3-none-any.whl → 0.16.7__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,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/file/README.md

@@ -4,7 +4,7 @@ Documentation for the `etlplus.file` subpackage: unified file format support and
 and writing data files.
 
 - Provides a consistent interface for reading and writing files in various formats
-- Supports all formats defined in `FileFormat` (see below)
+- Defines many formats in `FileFormat`; read/write support varies by format
 - Includes helpers for inferring file format and compression from filenames, extensions, or MIME
   types
 - Exposes a `File` class with instance methods for reading and writing data
@@ -23,7 +23,8 @@ Back to project overview: see the top-level [README](../../README.md).
 
 ## Supported File Formats
 
-The following formats are defined in `FileFormat` and supported for reading and writing:
+The following formats are implemented for reading/writing (unless noted). For the full support
+matrix across all `FileFormat` values, see the top-level [README](../../README.md).
 
 | Format    | Description                                 |
 |-----------|---------------------------------------------|
@@ -37,13 +38,14 @@ The following formats are defined in `FileFormat` and supported for reading and
 | parquet   | Apache Parquet columnar format              |
 | tsv       | Tab-separated values text files             |
 | txt       | Plain text files                            |
-| xls       | Microsoft Excel (legacy .xls)               |
+| xls       | Microsoft Excel (legacy .xls; read-only)    |
 | xlsx      | Microsoft Excel (modern .xlsx)              |
 | zip       | ZIP-compressed files (see Compression)      |
 | xml       | XML files                                   |
 | yaml      | YAML files                                  |
 
-Compression formats (gz, zip) are also supported as wrappers for other formats.
+Compression formats (gz, zip) are also supported as wrappers for other formats. Formats not listed
+here are currently stubbed and will raise `NotImplementedError` on read/write.
 
 ## Inferring File Format and Compression
 
@@ -77,7 +79,7 @@ f.write(data)
 ```
 
 - The `write()` method serializes and writes data in the appropriate format.
-- Supports all formats listed above.
+- Supports the implemented formats listed above.
 
 ## File Instance Methods
 

etlplus/file/accdb.py

@@ -1,7 +1,8 @@
 """
 :mod:`etlplus.file.accdb` module.
 
-Helpers for reading/writing newer Microsoft Access database (ACCDB) files.
+Stub helpers for reading/writing newer Microsoft Access database (ACCDB) files
+(not implemented yet).
 
 Notes
 -----

etlplus/file/arrow.py

@@ -1,7 +1,8 @@
 """
 :mod:`etlplus.file.arrow` module.
 
-Helpers for reading/writing Apache Arrow (ARROW) files.
+Stub helpers for reading/writing Apache Arrow (ARROW) files (not implemented
+yet).
 
 Notes
 -----

etlplus/file/bson.py

@@ -1,7 +1,8 @@
 """
 :mod:`etlplus.file.bson` module.
 
-Helpers for reading/writing Binary JSON (BSON) files.
+Stub helpers for reading/writing Binary JSON (BSON) files (not implemented
+yet).
 
 Notes
 -----

etlplus/file/cbor.py

@@ -1,7 +1,8 @@
 """
 :mod:`etlplus.file.cbor` module.
 
-Helpers for reading/writing Concise Binary Object Representation (CBOR) files.
+Stub helpers for reading/writing Concise Binary Object Representation (CBOR)
+files (not implemented yet).
 
 Notes
 -----

etlplus/file/cfg.py

@@ -1,7 +1,7 @@
 """
 :mod:`etlplus.file.cfg` module.
 
-Helpers for reading/writing config (CFG) files.
+Stub helpers for reading/writing config (CFG) files (not implemented yet).
 
 Notes
 -----

etlplus/file/conf.py

@@ -1,7 +1,7 @@
 """
 :mod:`etlplus.file.conf` module.
 
-Helpers for reading/writing config (CONF) files.
+Stub helpers for reading/writing config (CONF) files (not implemented yet).
 
 Notes
 -----

etlplus/file/dat.py

@@ -1,7 +1,7 @@
 """
 :mod:`etlplus.file.dat` module.
 
-Helpers for reading/writing data (DAT) files.
+Stub helpers for reading/writing data (DAT) files (not implemented yet).
 
 Notes
 -----

etlplus/file/dta.py

@@ -1,7 +1,7 @@
 """
 :mod:`etlplus.file.dta` module.
 
-Helpers for reading/writing Stata (DTA) data files.
+Stub helpers for reading/writing Stata (DTA) data files (not implemented yet).
 
 Notes
 -----

etlplus/file/duckdb.py

@@ -1,7 +1,8 @@
 """
 :mod:`etlplus.file.duckdb` module.
 
-Helpers for reading/writing DuckDB database (DUCKDB) files.
+Stub helpers for reading/writing DuckDB database (DUCKDB) files (not
+implemented yet).
 
 Notes
 -----

etlplus/file/enums.py

@@ -57,7 +57,7 @@ class CompressionFormat(CoercibleStrEnum):
 
 
 class FileFormat(CoercibleStrEnum):
-    """Supported file formats for extraction."""
+    """Defined file formats (read/write support varies by format)."""
 
     # -- Constants -- #
 

etlplus/file/fwf.py

@@ -1,7 +1,8 @@
 """
 :mod:`etlplus.file.fwf` module.
 
-Helpers for reading/writing Fixed-Width Fields (FWF) files.
+Stub helpers for reading/writing Fixed-Width Fields (FWF) files (not
+implemented yet).
 
 Notes
 -----

etlplus/file/hbs.py

@@ -1,7 +1,8 @@
 """
 :mod:`etlplus.file.hbs` module.
 
-Helpers for reading/writing Handlebars (HBS) template files.
+Stub helpers for reading/writing Handlebars (HBS) template files (not
+implemented yet).
 
 Notes
 -----

etlplus/file/hdf5.py

@@ -1,7 +1,8 @@
 """
 :mod:`etlplus.file.hdf5` module.
 
-Helpers for reading/writing Hierarchical Data Format (HDF5) files.
+Stub helpers for reading/writing Hierarchical Data Format (HDF5) files (not
+implemented yet).
 
 Notes
 -----

etlplus/file/ini.py

@@ -1,7 +1,8 @@
 """
 :mod:`etlplus.file.ini` module.
 
-Helpers for reading/writing initialization (INI) files.
+Stub helpers for reading/writing initialization (INI) files (not implemented
+yet).
 
 Notes
 -----

etlplus/file/ion.py

@@ -1,7 +1,7 @@
 """
 :mod:`etlplus.file.ion` module.
 
-Helpers for reading/writing Amazon Ion (ION) files.
+Stub helpers for reading/writing Amazon Ion (ION) files (not implemented yet).
 
 Notes
 -----

etlplus/file/jinja2.py

@@ -1,7 +1,8 @@
 """
 :mod:`etlplus.file.jinja2` module.
 
-Helpers for reading/writing compressed Jinja2 (JINJA2) template files.
+Stub helpers for reading/writing compressed Jinja2 (JINJA2) template files (not
+implemented yet).
 
 Notes
 -----

etlplus/file/log.py

@@ -1,7 +1,7 @@
 """
 :mod:`etlplus.file.log` module.
 
-Helpers for reading/writing generic log (LOG) files.
+Stub helpers for reading/writing generic log (LOG) files (not implemented yet).
 
 Notes
 -----

etlplus/file/mat.py

@@ -1,7 +1,7 @@
 """
 :mod:`etlplus.file.mat` module.
 
-Helpers for reading/writing MATLAB (MAT) data files.
+Stub helpers for reading/writing MATLAB (MAT) data files (not implemented yet).
 
 Notes
 -----

etlplus/file/mdb.py

@@ -1,7 +1,8 @@
 """
 :mod:`etlplus.file.mdb` module.
 
-Helpers for reading/writing newer Microsoft Access database (MDB) files.
+Stub helpers for reading/writing newer Microsoft Access database (MDB) files
+(not implemented yet).
 
 Notes
 -----

etlplus/file/msgpack.py

@@ -1,7 +1,8 @@
 """
 :mod:`etlplus.file.msgpack` module.
 
-Helpers for reading/writing MessagePack (MSGPACK) files.
+Stub helpers for reading/writing MessagePack (MSGPACK) files (not implemented
+yet).
 
 Notes
 -----

etlplus/file/mustache.py

@@ -1,7 +1,8 @@
 """
 :mod:`etlplus.file.mustache` module.
 
-Helpers for reading/writing Mustache (MUSTACHE) template files.
+Stub helpers for reading/writing Mustache (MUSTACHE) template files (not
+implemented yet).
 
 Notes
 -----

etlplus/file/nc.py

@@ -1,7 +1,7 @@
 """
 :mod:`etlplus.file.nc` module.
 
-Helpers for reading/writing NetCDF (NC) data files.
+Stub helpers for reading/writing NetCDF (NC) data files (not implemented yet).
 
 Notes
 -----

etlplus/file/numbers.py

@@ -1,7 +1,8 @@
 """
 :mod:`etlplus.file.numbers` module.
 
-Helpers for reading/writing Apple Numbers (NUMBERS) spreadsheet files.
+Stub helpers for reading/writing Apple Numbers (NUMBERS) spreadsheet files (not
+implemented yet).
 
 Notes
 -----

etlplus/file/ods.py

@@ -1,7 +1,8 @@
 """
 :mod:`etlplus.file.ods` module.
 
-Helpers for reading/writing OpenDocument (ODS) spreadsheet files.
+Stub helpers for reading/writing OpenDocument (ODS) spreadsheet files (not
+implemented yet).
 
 Notes
 -----

etlplus/file/pb.py

@@ -1,7 +1,8 @@
 """
 :mod:`etlplus.file.pb` module.
 
-Helpers for reading/writing Protocol Buffer (PB) files.
+Stub helpers for reading/writing Protocol Buffer (PB) files (not implemented
+yet).
 
 Notes
 -----

etlplus/file/pbf.py

@@ -1,7 +1,8 @@
 """
 :mod:`etlplus.file.pbf` module.
 
-Helpers for reading/writing Protocolbuffer Binary Format (PBF) files.
+Stub helpers for reading/writing Protocolbuffer Binary Format (PBF) files (not
+implemented yet).
 
 Notes
 -----

etlplus/file/properties.py

@@ -1,7 +1,8 @@
 """
 :mod:`etlplus.file.properties` module.
 
-Helpers for reading/writing properties (PROPERTIES) files.
+Stub helpers for reading/writing properties (PROPERTIES) files (not implemented
+yet).
 
 Notes
 -----

etlplus/file/proto.py

@@ -1,7 +1,8 @@
 """
 :mod:`etlplus.file.proto` module.
 
-Helpers for reading/writing Protocol Buffers schema (PROTO) files.
+Stub helpers for reading/writing Protocol Buffers schema (PROTO) files (not
+implemented yet).
 
 Notes
 -----

etlplus/file/psv.py

@@ -1,7 +1,8 @@
 """
 :mod:`etlplus.file.psv` module.
 
-Helpers for reading/writing Pipe-Separated Values (PSV) files.
+Stub helpers for reading/writing Pipe-Separated Values (PSV) files (not
+implemented yet).
 
 Notes
 -----

etlplus/file/rda.py

@@ -1,7 +1,8 @@
 """
 :mod:`etlplus.file.rda` module.
 
-Helpers for reading/writing RData workspace/object bundle (RDA) files.
+Stub helpers for reading/writing RData workspace/object bundle (RDA) files (not
+implemented yet).
 
 Notes
 -----

etlplus/file/rds.py

@@ -1,7 +1,7 @@
 """
 :mod:`etlplus.file.rds` module.
 
-Helpers for reading/writing R (RDS) data files.
+Stub helpers for reading/writing R (RDS) data files (not implemented yet).
 
 Notes
 -----

etlplus/file/sas7bdat.py

@@ -1,7 +1,8 @@
 """
 :mod:`etlplus.file.sas7bdat` module.
 
-Helpers for reading/writing SAS (SAS7BDAT) data files.
+Stub helpers for reading/writing SAS (SAS7BDAT) data files (not implemented
+yet).
 
 Notes
 -----

etlplus/file/sav.py

@@ -1,7 +1,7 @@
 """
 :mod:`etlplus.file.sav` module.
 
-Helpers for reading/writing SPSS (SAV) data files.
+Stub helpers for reading/writing SPSS (SAV) data files (not implemented yet).
 
 Notes
 -----