etlplus 0.12.4__py3-none-any.whl → 0.12.9__py3-none-any.whl

etlplus/file/_imports.py

@@ -0,0 +1,141 @@
+"""
+:mod:`etlplus.file._imports` module.
+
+Shared helpers for optional dependency imports.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+# SECTION: INTERNAL CONSTANTS =============================================== #
+
+
+_MODULE_CACHE: dict[str, Any] = {}
+
+
+# SECTION: INTERNAL FUNCTIONS =============================================== #
+
+
+def _error_message(
+    module_name: str,
+    format_name: str,
+) -> str:
+    """
+    Build an import error message for an optional dependency.
+
+    Parameters
+    ----------
+    module_name : str
+        Module name to look up.
+    format_name : str
+        Human-readable format name for templated messages.
+
+    Returns
+    -------
+    str
+        Formatted error message.
+    """
+    return (
+        f'{format_name} support requires '
+        f'optional dependency "{module_name}".\n'
+        f'Install with: pip install {module_name}'
+    )
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def get_optional_module(
+    module_name: str,
+    *,
+    error_message: str,
+) -> Any:
+    """
+    Return an optional dependency module, caching on first import.
+
+    Parameters
+    ----------
+    module_name : str
+        Name of the module to import.
+    error_message : str
+        Error message to surface when the module is missing.
+
+    Returns
+    -------
+    Any
+        The imported module.
+
+    Raises
+    ------
+    ImportError
+        If the optional dependency is missing.
+    """
+    cached = _MODULE_CACHE.get(module_name)
+    if cached is not None:  # pragma: no cover - tiny branch
+        return cached
+    try:
+        module = import_module(module_name)
+    except ImportError as e:  # pragma: no cover
+        raise ImportError(error_message) from e
+    _MODULE_CACHE[module_name] = module
+    return module
+
+
+def get_fastavro() -> Any:
+    """
+    Return the fastavro module, importing it on first use.
+
+    Raises an informative ImportError if the optional dependency is missing.
+
+    Notes
+    -----
+    Prefer :func:`get_optional_module` for new call sites.
+    """
+    return get_optional_module(
+        'fastavro',
+        error_message=_error_message('fastavro', format_name='AVRO'),
+    )
+
+
+def get_pandas(
+    format_name: str,
+) -> Any:
+    """
+    Return the pandas module, importing it on first use.
+
+    Parameters
+    ----------
+    format_name : str
+        Human-readable format name for error messages.
+
+    Returns
+    -------
+    Any
+        The pandas module.
+
+    Notes
+    -----
+    Prefer :func:`get_optional_module` for new call sites.
+    """
+    return get_optional_module(
+        'pandas',
+        error_message=_error_message('pandas', format_name=format_name),
+    )
+
+
+def get_yaml() -> Any:
+    """
+    Return the PyYAML module, importing it on first use.
+
+    Raises an informative ImportError if the optional dependency is missing.
+
+    Notes
+    -----
+    Prefer :func:`get_optional_module` for new call sites.
+    """
+    return get_optional_module(
+        'yaml',
+        error_message=_error_message('PyYAML', format_name='YAML'),
+    )

etlplus/file/_io.py

@@ -107,6 +107,7 @@ def write_delimited(path: Path, data: JSONData, *, delimiter: str) -> int:
         return 0
 
     fieldnames = sorted({key for row in rows for key in row})
+    path.parent.mkdir(parents=True, exist_ok=True)
     with path.open('w', encoding='utf-8', newline='') as handle:
         writer = csv.DictWriter(
             handle,

etlplus/file/avro.py

@@ -10,6 +10,8 @@ from pathlib import Path
 from typing import Any
 from typing import cast
 
+from etlplus.file._imports import get_fastavro
+
 from ..types import JSONData
 from ..types import JSONDict
 from ..types import JSONList
@@ -27,9 +29,6 @@ __all__ = [
 # SECTION: INTERNAL CONSTANTS =============================================== #
 
 
-_FASTAVRO_CACHE: dict[str, Any] = {}
-
-
 _PRIMITIVE_TYPES: tuple[type, ...] = (
     bool,
     int,
@@ -43,27 +42,6 @@ _PRIMITIVE_TYPES: tuple[type, ...] = (
 # SECTION: INTERNAL FUNCTIONS =============================================== #
 
 
-def _get_fastavro() -> Any:
-    """
-    Return the fastavro module, importing it on first use.
-
-    Raises an informative ImportError if the optional dependency is missing.
-    """
-    mod = _FASTAVRO_CACHE.get('mod')
-    if mod is not None:  # pragma: no cover - tiny branch
-        return mod
-    try:
-        _fastavro = __import__('fastavro')  # type: ignore[assignment]
-    except ImportError as e:  # pragma: no cover
-        raise ImportError(
-            'AVRO support requires optional dependency "fastavro".\n'
-            'Install with: pip install fastavro',
-        ) from e
-    _FASTAVRO_CACHE['mod'] = _fastavro
-
-    return _fastavro
-
-
 def _infer_schema(records: JSONList) -> dict[str, Any]:
     """
     Infer a basic Avro schema from record payloads.
@@ -146,7 +124,7 @@ def read(
     JSONList
         The list of dictionaries read from the AVRO file.
     """
-    fastavro = _get_fastavro()
+    fastavro = get_fastavro()
     with path.open('rb') as handle:
         reader = fastavro.reader(handle)
         return [cast(JSONDict, record) for record in reader]
@@ -175,7 +153,7 @@ def write(
     if not records:
         return 0
 
-    fastavro = _get_fastavro()
+    fastavro = get_fastavro()
     schema = _infer_schema(records)
     parsed_schema = fastavro.parse_schema(schema)
 

etlplus/file/core.py

@@ -7,25 +7,15 @@ files.
 
 from __future__ import annotations
 
+import importlib
+import inspect
 from dataclasses import dataclass
+from functools import cache
 from pathlib import Path
+from types import ModuleType
 
 from ..types import JSONData
-from . import avro
-from . import csv
-from . import feather
-from . import gz
-from . import json
-from . import ndjson
-from . import orc
-from . import parquet
-from . import tsv
-from . import txt
-from . import xls
-from . import xlsx
 from . import xml
-from . import yaml
-from . import zip as zip_
 from .enums import FileFormat
 from .enums import infer_file_format_and_compression
 
@@ -35,6 +25,53 @@ from .enums import infer_file_format_and_compression
 __all__ = ['File']
 
 
+# SECTION: INTERNAL FUNCTIONS =============================================== #
+
+
+def _accepts_root_tag(handler: object) -> bool:
+    """
+    Return True when ``handler`` supports a ``root_tag`` argument.
+
+    Parameters
+    ----------
+    handler : object
+        Callable to inspect.
+
+    Returns
+    -------
+    bool
+        True if ``root_tag`` is accepted by the handler.
+    """
+    if not callable(handler):
+        return False
+    try:
+        signature = inspect.signature(handler)
+    except (TypeError, ValueError):
+        return False
+    for param in signature.parameters.values():
+        if param.kind is param.VAR_KEYWORD:
+            return True
+    return 'root_tag' in signature.parameters
+
+
+@cache
+def _module_for_format(file_format: FileFormat) -> ModuleType:
+    """
+    Import and return the module for ``file_format``.
+
+    Parameters
+    ----------
+    file_format : FileFormat
+        File format enum value.
+
+    Returns
+    -------
+    ModuleType
+        The module implementing IO for the format.
+    """
+    return importlib.import_module(f'{__package__}.{file_format.value}')
+
+
 # SECTION: CLASSES ========================================================== #
 
 
@@ -174,6 +211,53 @@ class File:
             # Leave as None; _ensure_format() will raise on use if needed.
             return None
 
+    def _resolve_handler(self, name: str) -> object:
+        """
+        Resolve a handler from the module for the active file format.
+
+        Parameters
+        ----------
+        name : str
+            Attribute name to resolve (``'read'`` or ``'write'``).
+
+        Returns
+        -------
+        object
+            Callable handler exported by the module.
+
+        Raises
+        ------
+        ValueError
+            If the resolved file format is unsupported.
+        """
+        module = self._resolve_module()
+        try:
+            return getattr(module, name)
+        except AttributeError as e:
+            raise ValueError(
+                f'Module {module.__name__} does not implement {name}()',
+            ) from e
+
+    def _resolve_module(self) -> ModuleType:
+        """
+        Resolve the IO module for the active file format.
+
+        Returns
+        -------
+        ModuleType
+            The module that implements read/write for the format.
+
+        Raises
+        ------
+        ValueError
+            If the resolved file format is unsupported.
+        """
+        fmt = self._ensure_format()
+        try:
+            return _module_for_format(fmt)
+        except ModuleNotFoundError as e:
+            raise ValueError(f'Unsupported format: {fmt}') from e
+
     # -- Instance Methods -- #
 
     def read(self) -> JSONData:
@@ -187,43 +271,18 @@ class File:
 
         Raises
         ------
-        ValueError
-            If the resolved file format is unsupported.
+        TypeError
+            If the resolved 'read' handler is not callable.
         """
         self._assert_exists()
-        fmt = self._ensure_format()
-        match fmt:
-            case FileFormat.AVRO:
-                return avro.read(self.path)
-            case FileFormat.CSV:
-                return csv.read(self.path)
-            case FileFormat.FEATHER:
-                return feather.read(self.path)
-            case FileFormat.GZ:
-                return gz.read(self.path)
-            case FileFormat.JSON:
-                return json.read(self.path)
-            case FileFormat.NDJSON:
-                return ndjson.read(self.path)
-            case FileFormat.ORC:
-                return orc.read(self.path)
-            case FileFormat.PARQUET:
-                return parquet.read(self.path)
-            case FileFormat.TSV:
-                return tsv.read(self.path)
-            case FileFormat.TXT:
-                return txt.read(self.path)
-            case FileFormat.XLS:
-                return xls.read(self.path)
-            case FileFormat.XLSX:
-                return xlsx.read(self.path)
-            case FileFormat.XML:
-                return xml.read(self.path)
-            case FileFormat.YAML:
-                return yaml.read(self.path)
-            case FileFormat.ZIP:
-                return zip_.read(self.path)
-        raise ValueError(f'Unsupported format: {fmt}')
+        reader = self._resolve_handler('read')
+        if callable(reader):
+            return reader(self.path)
+        else:
+            raise TypeError(
+                f"'read' handler for format {self.file_format} "
+                'is not callable',
+            )
 
     def write(
         self,
@@ -249,39 +308,15 @@ class File:
 
         Raises
         ------
-        ValueError
-            If the resolved file format is unsupported.
+        TypeError
+            If the resolved 'write' handler is not callable.
         """
-        fmt = self._ensure_format()
-        match fmt:
-            case FileFormat.AVRO:
-                return avro.write(self.path, data)
-            case FileFormat.CSV:
-                return csv.write(self.path, data)
-            case FileFormat.FEATHER:
-                return feather.write(self.path, data)
-            case FileFormat.GZ:
-                return gz.write(self.path, data)
-            case FileFormat.JSON:
-                return json.write(self.path, data)
-            case FileFormat.NDJSON:
-                return ndjson.write(self.path, data)
-            case FileFormat.ORC:
-                return orc.write(self.path, data)
-            case FileFormat.PARQUET:
-                return parquet.write(self.path, data)
-            case FileFormat.TSV:
-                return tsv.write(self.path, data)
-            case FileFormat.TXT:
-                return txt.write(self.path, data)
-            case FileFormat.XLS:
-                return xls.write(self.path, data)
-            case FileFormat.XLSX:
-                return xlsx.write(self.path, data)
-            case FileFormat.XML:
-                return xml.write(self.path, data, root_tag=root_tag)
-            case FileFormat.YAML:
-                return yaml.write(self.path, data)
-            case FileFormat.ZIP:
-                return zip_.write(self.path, data)
-        raise ValueError(f'Unsupported format: {fmt}')
+        writer = self._resolve_handler('write')
+        if not callable(writer):
+            raise TypeError(
+                f"'write' handler for format {self.file_format} "
+                'is not callable',
+            )
+        if _accepts_root_tag(writer):
+            return writer(self.path, data, root_tag=root_tag)
+        return writer(self.path, data)

etlplus/file/dat.py

@@ -0,0 +1,66 @@
+"""
+:mod:`etlplus.file.dat` module.
+
+Helpers for reading/writing DAT (data) files.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..types import JSONData
+from ..types import JSONList
+from . import stub
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    'read',
+    'write',
+]
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def read(
+    path: Path,
+) -> JSONList:
+    """
+    Read DAT content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the DAT file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the DAT file.
+    """
+    return stub.read(path, format_name='DAT')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to DAT file at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the DAT file on disk.
+    data : JSONData
+        Data to write as DAT file. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the DAT file.
+    """
+    return stub.write(path, data, format_name='DAT')

etlplus/file/enums.py

@@ -61,21 +61,119 @@ class FileFormat(CoercibleStrEnum):
 
     # -- Constants -- #
 
-    AVRO = 'avro'
-    CSV = 'csv'
-    FEATHER = 'feather'
-    GZ = 'gz'
-    JSON = 'json'
-    NDJSON = 'ndjson'
-    ORC = 'orc'
-    PARQUET = 'parquet'
-    TSV = 'tsv'
-    TXT = 'txt'
-    XLS = 'xls'
-    XLSX = 'xlsx'
-    ZIP = 'zip'
-    XML = 'xml'
-    YAML = 'yaml'
+    # Stubbed / placeholder
+    STUB = 'stub'  # Placeholder format for tests & future connectors
+
+    # Tabular & delimited text
+    CSV = 'csv'  # Comma-Separated Values
+    FWF = 'fwf'  # Fixed-Width Formatted
+    DAT = 'dat'  # Generic data file, often delimited or fixed-width
+    PSV = 'psv'  # Pipe-Separated Values
+    TAB = 'tab'  # Often synonymous with TSV
+    TSV = 'tsv'  # Tab-Separated Values
+    TXT = 'txt'  # Plain text, often delimited or fixed-width
+
+    # Semi-structured text
+    CFG = 'cfg'  # Config-style key-value pairs
+    CONF = 'conf'  # Config-style key-value pairs
+    INI = 'ini'  # INI-style key-value pairs
+    JSON = 'json'  # JavaScript Object Notation
+    NDJSON = 'ndjson'  # Newline-Delimited JSON
+    PROPS = 'properties'  # Java-style key-value pairs
+    TOML = 'toml'  # Tom's Obvious Minimal Language
+    XML = 'xml'  # Extensible Markup Language
+    YAML = 'yaml'  # YAML Ain't Markup Language
+
+    # Columnar / analytics-friendly
+    ARROW = 'arrow'  # Apache Arrow IPC
+    FEATHER = 'feather'  # Apache Arrow Feather
+    ORC = 'orc'  # Optimized Row Columnar; common in Hadoop
+    PARQUET = 'parquet'  # Apache Parquet; common in Big Data
+
+    # Binary serialization & interchange
+    AVRO = 'avro'  # Apache Avro
+    BSON = 'bson'  # Binary JSON; common with MongoDB exports/dumps
+    CBOR = 'cbor'  # Concise Binary Object Representation
+    ION = 'ion'  # Amazon Ion
+    MSGPACK = 'msgpack'  # MessagePack
+    PB = 'pb'  # Protocol Buffers (Google Protobuf)
+    PBF = 'pbf'  # Protocolbuffer Binary Format; often for GIS data
+    PROTO = 'proto'  # Protocol Buffers schema; often in .pb / .bin
+
+    # Databases & embedded storage
+    ACCDB = 'accdb'  # Microsoft Access database file (newer format)
+    DUCKDB = 'duckdb'  # DuckDB database file
+    MDB = 'mdb'  # Microsoft Access database file (older format)
+    SQLITE = 'sqlite'  # SQLite database file
+
+    # Spreadsheets
+    NUMBERS = 'numbers'  # Apple Numbers spreadsheet
+    ODS = 'ods'  # OpenDocument Spreadsheet
+    WKS = 'wks'  # Lotus 1-2-3 spreadsheet
+    XLS = 'xls'  # Microsoft Excel (BIFF); read-only
+    XLSM = 'xlsm'  # Microsoft Excel Macro-Enabled (Open XML)
+    XLSX = 'xlsx'  # Microsoft Excel (Open XML)
+
+    # Statistical / scientific / numeric computing
+    DTA = 'dta'  # Stata data file
+    H5 = 'h5'  # Hierarchical Data Format
+    MAT = 'mat'  # MATLAB data file
+    NC = 'nc'  # NetCDF data file
+    RDA = 'rda'  # RData workspace/object bundle
+    RDS = 'rds'  # R data file
+    SAS7BDAT = 'sas7bdat'  # SAS data file
+    SAV = 'sav'  # SPSS data file
+    SYLK = 'sylk'  # Symbolic Link (SYmbolic LinK)
+    XPT = 'xpt'  # SAS Transport file
+    ZSAV = 'zsav'  # Compressed SPSS data file
+
+    # Time series and financial data
+    CAMT = 'camt'  # ISO 20022 Cash Management messages
+    FXT = 'fxt'  # Forex time series data
+    MT940 = 'mt940'  # SWIFT MT940 bank statement format
+    MT942 = 'mt942'  # SWIFT MT942 interim transaction report format
+    OFX = 'ofx'  # Open Financial Exchange
+    QFX = 'qfx'  # Quicken Financial Exchange
+    QIF = 'qif'  # Quicken Interchange Format
+    QQQ = 'qqq'  # QuantQuote historical data
+    TRR = 'trr'  # Trade and transaction reports
+    TSDB = 'tsdb'  # Time series database export
+
+    # Geospatial data
+    GEOJSON = 'geojson'  # GeoJSON
+    GEOTIFF = 'geotiff'  # GeoTIFF
+    GML = 'gml'  # Geography Markup Language
+    GPKG = 'gpkg'  # GeoPackage
+    GPX = 'gpx'  # GPS Exchange Format
+    KML = 'kml'  # Keyhole Markup Language
+    LAS = 'las'  # LiDAR Aerial Survey
+    LAZ = 'laz'  # LASzip (compressed LAS)
+    OSM = 'osm'  # OpenStreetMap XML Data
+    SHP = 'shp'  # ESRI Shapefile
+    WKB = 'wkb'  # Well-Known Binary
+    WKT = 'wkt'  # Well-Known Text
+
+    # Logs & event streams
+    EVT = 'evt'  # Windows Event Trace Log (pre-Vista)
+    EVTX = 'evtx'  # Windows Event Trace Log (Vista and later)
+    LOG = 'log'  # Generic log file
+    PCAP = 'pcap'  # Packet Capture file
+    PCAPPNG = 'pcapng'  # Packet Capture Next Generation file
+    SLOG = 'slog'  # Structured log file
+    W3CLOG = 'w3clog'  # W3C Extended Log File Format
+
+    # “Data archives” & packaging
+    _7Z = '7z'  # 7-Zip archive
+    GZ = 'gz'  # Gzip-compressed file
+    JAR = 'jar'  # Java archive
+    RAR = 'rar'  # RAR archive
+    SIT = 'sit'  # StuffIt archive
+    SITX = 'sitx'  # StuffIt X archive
+    TAR = 'tar'  # TAR archive
+    TGZ = 'tgz'  # Gzip-compressed TAR archive
+    ZIP = 'zip'  # ZIP archive
+
+    # Domain-specific & less common
 
     # -- Class Methods -- #
 
@@ -104,6 +202,7 @@ class FileFormat(CoercibleStrEnum):
             '.orc': 'orc',
             '.parquet': 'parquet',
             '.pq': 'parquet',
+            '.stub': 'stub',
             '.tsv': 'tsv',
             '.txt': 'txt',
             '.xls': 'xls',

etlplus/file/feather.py

@@ -11,8 +11,8 @@ from typing import cast
 
 from ..types import JSONData
 from ..types import JSONList
+from ._imports import get_pandas
 from ._io import normalize_records
-from ._pandas import get_pandas
 
 # SECTION: EXPORTS ========================================================== #