etlplus 0.12.1__py3-none-any.whl → 0.12.10__py3-none-any.whl

etlplus/file/cbor.py

@@ -0,0 +1,78 @@
+"""
+:mod:`etlplus.file.cbor` module.
+
+Helpers for reading/writing Concise Binary Object Representation (CBOR) files.
+
+Notes
+-----
+- A CBOR file is a binary data format designed for small code size and message
+    size, suitable for constrained environments.
+- Common cases:
+    - IoT data interchange.
+    - Efficient data serialization.
+    - Storage of structured data in a compact binary form.
+- Rule of thumb:
+    - If the file follows the CBOR specification, use this module for reading
+        and writing.
+"""
+
+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 CBOR content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the CBOR file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the CBOR file.
+    """
+    return stub.read(path, format_name='CBOR')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to CBOR at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the CBOR file on disk.
+    data : JSONData
+        Data to write as CBOR. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the CBOR file.
+    """
+    return stub.write(path, data, format_name='CBOR')

etlplus/file/cfg.py

@@ -0,0 +1,79 @@
+"""
+:mod:`etlplus.file.cfg` module.
+
+Helpers for reading/writing config (CFG) files.
+
+Notes
+-----
+- A “CFG-formatted” file is a configuration file that may use various
+    syntaxes, such as INI, YAML, or custom formats.
+- Common cases:
+    - INI-style key-value pairs with sections (such as in Python ecosystems,
+        using ``configparser``).
+    - YAML-like structures with indentation.
+    - Custom formats specific to certain applications.
+- Rule of thumb:
+    - If the file follows a standard format like INI or YAML, consider using
+        dedicated parsers.
+"""
+
+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 CFG content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the CFG file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the CFG file.
+    """
+    return stub.read(path, format_name='CFG')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to CFG file at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the CFG file on disk.
+    data : JSONData
+        Data to write as CFG file. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the CFG file.
+    """
+    return stub.write(path, data, format_name='CFG')

etlplus/file/conf.py

@@ -0,0 +1,80 @@
+"""
+:mod:`etlplus.file.conf` module.
+
+Helpers for reading/writing config (CONF) files.
+
+Notes
+-----
+- A “CONF-formatted” file is a configuration file that may use various
+    syntaxes, such as INI, YAML, or custom formats.
+- Common cases:
+    - INI-style key-value pairs with sections.
+    - YAML-like structures with indentation.
+    - Custom formats specific to certain applications (such as Unix-like
+        systems, where ``.conf`` is a strong convention for "This is a
+        configuration file").
+- Rule of thumb:
+    - If the file follows a standard format like INI or YAML, consider using
+        dedicated parsers.
+"""
+
+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 CONF content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the CONF file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the CONF file.
+    """
+    return stub.read(path, format_name='CONF')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to CONF at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the CONF file on disk.
+    data : JSONData
+        Data to write as CONF. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the CONF file.
+    """
+    return stub.write(path, data, format_name='CONF')

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
 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/csv.py

@@ -1,18 +1,29 @@
 """
 :mod:`etlplus.file.csv` module.
 
-Helpers for reading/writing CSV files.
+Helpers for reading/writing Comma-Separated Values (CSV) files.
+
+Notes
+-----
+- A CSV file is a plain text file that uses commas to separate values.
+- Common cases:
+    - Each line in the file represents a single record.
+    - The first line often contains headers that define the column names.
+    - Values may be enclosed in quotes, especially if they contain commas
+        or special characters.
+- Rule of thumb:
+    - If the file follows the CSV specification, use this module for
+        reading and writing.
 """
 
 from __future__ import annotations
 
-import csv
 from pathlib import Path
-from typing import cast
 
 from ..types import JSONData
-from ..types import JSONDict
 from ..types import JSONList
+from ._io import read_delimited
+from ._io import write_delimited
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -42,14 +53,7 @@ def read(
     JSONList
         The list of dictionaries read from the CSV file.
     """
-    with path.open('r', encoding='utf-8', newline='') as handle:
-        reader: csv.DictReader[str] = csv.DictReader(handle)
-        rows: JSONList = []
-        for row in reader:
-            if not any(row.values()):
-                continue
-            rows.append(cast(JSONDict, dict(row)))
-    return rows
+    return read_delimited(path, delimiter=',')
 
 
 def write(
@@ -72,20 +76,4 @@ def write(
     int
         The number of rows written to the CSV file.
     """
-    rows: list[JSONDict]
-    if isinstance(data, list):
-        rows = [row for row in data if isinstance(row, dict)]
-    else:
-        rows = [data]
-
-    if not rows:
-        return 0
-
-    fieldnames = sorted({key for row in rows for key in row})
-    with path.open('w', encoding='utf-8', newline='') as handle:
-        writer = csv.DictWriter(handle, fieldnames=fieldnames)
-        writer.writeheader()
-        for row in rows:
-            writer.writerow({field: row.get(field) for field in fieldnames})
-
-    return len(rows)
+    return write_delimited(path, data, delimiter=',')

etlplus/file/dat.py

@@ -0,0 +1,78 @@
+"""
+:mod:`etlplus.file.dat` module.
+
+Helpers for reading/writing data (DAT) files.
+
+Notes
+-----
+- A “DAT-formatted” file is a generic data file that may use various
+    delimiters or fixed-width formats.
+- Common cases:
+    - Delimited text files (e.g., CSV, TSV).
+    - Fixed-width formatted files.
+    - Custom formats specific to certain applications.
+- Rule of thumb:
+    - If the file does not follow a specific standard format, use this module
+        for reading and writing.
+"""
+
+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/duckdb.py

@@ -0,0 +1,78 @@
+"""
+:mod:`etlplus.file.duckdb` module.
+
+Helpers for reading/writing DuckDB database (DUCKDB) files.
+
+Notes
+-----
+- A DUCKDB file is a self-contained, serverless database file format used by
+    DuckDB.
+- Common cases:
+    - Analytical data storage and processing.
+    - Embedded database applications.
+    - Fast querying of large datasets.
+- Rule of thumb:
+    - If the file follows the DUCKDB specification, use this module for reading
+        and writing.
+"""
+
+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 DUCKDB content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the DUCKDB file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the DUCKDB file.
+    """
+    return stub.read(path, format_name='DUCKDB')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to DUCKDB at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the DUCKDB file on disk.
+    data : JSONData
+        Data to write as DUCKDB. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the DUCKDB file.
+    """
+    return stub.write(path, data, format_name='DUCKDB')