etlplus 0.12.3__py3-none-any.whl → 0.12.12__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/accdb.py

@@ -0,0 +1,78 @@
+"""
+:mod:`etlplus.file.accdb` module.
+
+Helpers for reading/writing newer Microsoft Access database (ACCDB) files.
+
+Notes
+-----
+- An ACCDB file is a proprietary database file format used by Microsoft Access
+    2007 and later.
+- Common cases:
+    - Storing relational data for small to medium-sized applications.
+    - Desktop database applications.
+    - Data management for non-enterprise solutions.
+- Rule of thumb:
+    - If the file follows the ACCDB 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 ACCDB content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the ACCDB file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the ACCDB file.
+    """
+    return stub.read(path, format_name='ACCDB')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to ACCDB at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the ACCDB file on disk.
+    data : JSONData
+        Data to write as ACCDB. Should be a list of dictionaries or a single
+        dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the ACCDB file.
+    """
+    return stub.write(path, data, format_name='ACCDB')

etlplus/file/arrow.py

@@ -0,0 +1,78 @@
+"""
+:mod:`etlplus.file.arrow` module.
+
+Helpers for reading/writing Apache Arrow (ARROW) files.
+
+Notes
+-----
+- An ARROW file is a binary file format designed for efficient
+    columnar data storage and processing.
+- Common cases:
+    - High-performance data analytics.
+    - Interoperability between different data processing systems.
+    - In-memory data representation for fast computations.
+- Rule of thumb:
+    - If the file follows the Apache Arrow 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 ARROW content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the Apache Arrow file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the Apache Arrow file.
+    """
+    return stub.read(path, format_name='ARROW')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to ARROW at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the ARROW file on disk.
+    data : JSONData
+        Data to write as ARROW. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the ARROW file.
+    """
+    return stub.write(path, data, format_name='ARROW')

etlplus/file/avro.py

@@ -1,7 +1,19 @@
 """
 :mod:`etlplus.file.avro` module.
 
-Helpers for reading/writing Avro files.
+Helpers for reading/writing Apache Avro (AVRO) files.
+
+Notes
+-----
+- An AVRO file is a binary file format designed for efficient
+    on-disk storage of data, with a schema definition.
+- Common cases:
+    - Data serialization for distributed systems.
+    - Interoperability between different programming languages.
+    - Storage of large datasets with schema evolution support.
+- Rule of thumb:
+    - If the file follows the Apache Avro specification, use this module for
+        reading and writing.
 """
 
 from __future__ import annotations
@@ -10,6 +22,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 +41,6 @@ __all__ = [
 # SECTION: INTERNAL CONSTANTS =============================================== #
 
 
-_FASTAVRO_CACHE: dict[str, Any] = {}
-
-
 _PRIMITIVE_TYPES: tuple[type, ...] = (
     bool,
     int,
@@ -43,27 +54,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 +136,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 +165,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/bson.py

@@ -0,0 +1,77 @@
+"""
+:mod:`etlplus.file.bson` module.
+
+Helpers for reading/writing Binary JSON (BSON) files.
+
+Notes
+-----
+- A BSON file is a binary-encoded serialization of JSON-like documents.
+- Common cases:
+    - Data storage in MongoDB.
+    - Efficient data interchange between systems.
+    - Handling of complex data types not supported in standard JSON.
+- Rule of thumb:
+    - If the file follows the BSON 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 BSON content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the BSON file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the BSON file.
+    """
+    return stub.read(path, format_name='BSON')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to BSON at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the BSON file on disk.
+    data : JSONData
+        Data to write as BSON. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the BSON file.
+    """
+    return stub.write(path, data, format_name='BSON')

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 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 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')