etlplus 0.9.2__py3-none-any.whl → 0.10.1__py3-none-any.whl

etlplus/file/fwf.py

@@ -1,77 +0,0 @@
-"""
-:mod:`etlplus.file.fwf` module.
-
-Helpers for reading/writing Fixed-Width Fields (FWF) files.
-
-Notes
------
-- An FWF file is a text file format where each field has a fixed width.
-- Common cases:
-    - Data files from legacy systems.
-    - Reports with aligned columns.
-    - Data exchange in mainframe environments.
-- Rule of thumb:
-    - If the file follows the FWF 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 FWF content from ``path``.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the FWF file on disk.
-
-    Returns
-    -------
-    JSONList
-        The list of dictionaries read from the FWF file.
-    """
-    return stub.read(path, format_name='FWF')
-
-
-def write(
-    path: Path,
-    data: JSONData,
-) -> int:
-    """
-    Write ``data`` to FWF file at ``path`` and return record count.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the FWF file on disk.
-    data : JSONData
-        Data to write as FWF file. Should be a list of dictionaries or a
-        single dictionary.
-
-    Returns
-    -------
-    int
-        The number of rows written to the FWF file.
-    """
-    return stub.write(path, data, format_name='FWF')

etlplus/file/gz.py

@@ -1,123 +0,0 @@
-"""
-:mod:`etlplus.file.gz` module.
-
-Helpers for reading/writing GZ files.
-"""
-
-from __future__ import annotations
-
-import gzip
-import tempfile
-from pathlib import Path
-
-from ..types import JSONData
-from .enums import CompressionFormat
-from .enums import FileFormat
-from .enums import infer_file_format_and_compression
-
-# SECTION: EXPORTS ========================================================== #
-
-
-__all__ = [
-    'read',
-    'write',
-]
-
-
-# SECTION: INTERNAL FUNCTIONS =============================================== #
-
-
-def _resolve_format(
-    path: Path,
-) -> FileFormat:
-    """
-    Resolve the inner file format from a .gz filename.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the GZ file on disk.
-
-    Returns
-    -------
-    FileFormat
-        The inferred inner file format.
-
-    Raises
-    ------
-    ValueError
-        If the file format cannot be inferred from the filename.
-    """
-    fmt, compression = infer_file_format_and_compression(path)
-    if compression is not CompressionFormat.GZ:
-        raise ValueError(f'Not a gzip file: {path}')
-    if fmt is None:
-        raise ValueError(
-            f'Cannot infer file format from compressed file {path!r}',
-        )
-    return fmt
-
-
-# SECTION: FUNCTIONS ======================================================== #
-
-
-def read(
-    path: Path,
-) -> JSONData:
-    """
-    Read GZ content from ``path`` and parse the inner payload.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the GZ file on disk.
-
-    Returns
-    -------
-    JSONData
-        Parsed payload.
-    """
-    fmt = _resolve_format(path)
-    with gzip.open(path, 'rb') as handle:
-        payload = handle.read()
-
-    with tempfile.TemporaryDirectory() as tmpdir:
-        tmp_path = Path(tmpdir) / f'payload.{fmt.value}'
-        tmp_path.write_bytes(payload)
-        from .core import File
-
-        return File(tmp_path, fmt).read()
-
-
-def write(
-    path: Path,
-    data: JSONData,
-) -> int:
-    """
-    Write ``data`` to GZ at ``path`` and return record count.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the GZ file on disk.
-    data : JSONData
-        Data to write.
-
-    Returns
-    -------
-    int
-        Number of records written.
-    """
-    fmt = _resolve_format(path)
-    with tempfile.TemporaryDirectory() as tmpdir:
-        tmp_path = Path(tmpdir) / f'payload.{fmt.value}'
-        from .core import File
-
-        count = File(tmp_path, fmt).write(data)
-        payload = tmp_path.read_bytes()
-
-    path.parent.mkdir(parents=True, exist_ok=True)
-    with gzip.open(path, 'wb') as handle:
-        handle.write(payload)
-
-    return count

etlplus/file/hbs.py

@@ -1,78 +0,0 @@
-"""
-:mod:`etlplus.file.hbs` module.
-
-Helpers for reading/writing Handlebars (HBS) template files.
-
-Notes
------
-- A Handlebars (HBS) template file is a text file used for generating HTML or
-    other text formats by combining templates with data.
-- Common cases:
-    - HTML templates.
-    - Email templates.
-    - Configuration files.
-- Rule of thumb:
-    - If you need to work with Handlebars template files, 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 ZSAV content from ``path``.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the HBS file on disk.
-
-    Returns
-    -------
-    JSONList
-        The list of dictionaries read from the HBS file.
-    """
-    return stub.read(path, format_name='HBS')
-
-
-def write(
-    path: Path,
-    data: JSONData,
-) -> int:
-    """
-    Write ``data`` to HBS file at ``path`` and return record count.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the HBS file on disk.
-    data : JSONData
-        Data to write as HBS file. Should be a list of dictionaries or a
-        single dictionary.
-
-    Returns
-    -------
-    int
-        The number of rows written to the HBS file.
-    """
-    return stub.write(path, data, format_name='HBS')

etlplus/file/hdf5.py

@@ -1,78 +0,0 @@
-"""
-:mod:`etlplus.file.hdf5` module.
-
-Helpers for reading/writing Hierarchical Data Format (HDF5) files.
-
-Notes
------
-- A HDF5 file is a binary file format designed to store and organize large
-    amounts of data.
-- Common cases:
-    - Scientific data storage and sharing.
-    - Large-scale data analysis.
-    - Hierarchical data organization.
-- Rule of thumb:
-    - If the file follows the HDF5 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 HDF5 content from ``path``.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the HDF5 file on disk.
-
-    Returns
-    -------
-    JSONList
-        The list of dictionaries read from the HDF5 file.
-    """
-    return stub.read(path, format_name='HDF5')
-
-
-def write(
-    path: Path,
-    data: JSONData,
-) -> int:
-    """
-    Write ``data`` to HDF5 file at ``path`` and return record count.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the HDF5 file on disk.
-    data : JSONData
-        Data to write as HDF5 file. Should be a list of dictionaries or a
-        single dictionary.
-
-    Returns
-    -------
-    int
-        The number of rows written to the HDF5 file.
-    """
-    return stub.write(path, data, format_name='HDF5')

etlplus/file/ini.py

@@ -1,79 +0,0 @@
-"""
-:mod:`etlplus.file.ini` module.
-
-Helpers for reading/writing initialization (INI) files.
-
-Notes
------
-- An INI file is a simple configuration file format that uses sections,
-    properties, and values.
-- Common cases:
-    - Sections are denoted by square brackets (e.g., ``[section]``).
-    - Properties are key-value pairs (e.g., ``key=value``).
-    - Comments are often indicated by semicolons (``;``) or hash symbols
-        (``#``).
-- Rule of thumb:
-    - If the file follows the INI 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 INI content from ``path``.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the INI file on disk.
-
-    Returns
-    -------
-    JSONList
-        The list of dictionaries read from the INI file.
-    """
-    return stub.read(path, format_name='INI')
-
-
-def write(
-    path: Path,
-    data: JSONData,
-) -> int:
-    """
-    Write ``data`` to INI at ``path`` and return record count.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the INI file on disk.
-    data : JSONData
-        Data to write as INI. Should be a list of dictionaries or a
-        single dictionary.
-
-    Returns
-    -------
-    int
-        The number of rows written to the INI file.
-    """
-    return stub.write(path, data, format_name='INI')

etlplus/file/ion.py

@@ -1,78 +0,0 @@
-"""
-:mod:`etlplus.file.ion` module.
-
-Helpers for reading/writing Amazon Ion (ION) files.
-
-Notes
------
-- An ION file is a richly-typed, self-describing data format developed by
-    Amazon, designed for efficient data interchange and storage.
-- Common cases:
-    - Data serialization for distributed systems.
-    - Interoperability between different programming languages.
-    - Handling of complex data types beyond standard JSON capabilities.
-- Rule of thumb:
-    - If the file follows the Amazon Ion 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 ION content from ``path``.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the ION file on disk.
-
-    Returns
-    -------
-    JSONList
-        The list of dictionaries read from the ION file.
-    """
-    return stub.read(path, format_name='ION')
-
-
-def write(
-    path: Path,
-    data: JSONData,
-) -> int:
-    """
-    Write ``data`` to ION at ``path`` and return record count.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the ION file on disk.
-    data : JSONData
-        Data to write as ION. Should be a list of dictionaries or a
-        single dictionary.
-
-    Returns
-    -------
-    int
-        The number of rows written to the ION file.
-    """
-    return stub.write(path, data, format_name='ION')

etlplus/file/jinja2.py

@@ -1,78 +0,0 @@
-"""
-:mod:`etlplus.file.jinja2` module.
-
-Helpers for reading/writing compressed Jinja2 (JINJA2) template files.
-
-Notes
------
-- A JINJA2 file is a text file used for generating HTML or other text formats
-    by combining templates with data.
-- Common cases:
-    - HTML templates.
-    - Email templates.
-    - Configuration files.
-- Rule of thumb:
-    - If you need to work with Jinja2 template files, 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 JINJA2 content from ``path``.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the JINJA2 file on disk.
-
-    Returns
-    -------
-    JSONList
-        The list of dictionaries read from the JINJA2 file.
-    """
-    return stub.read(path, format_name='JINJA2')
-
-
-def write(
-    path: Path,
-    data: JSONData,
-) -> int:
-    """
-    Write ``data`` to JINJA2 file at ``path`` and return record count.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the JINJA2 file on disk.
-    data : JSONData
-        Data to write as JINJA2 file. Should be a list of dictionaries or a
-        single dictionary.
-
-    Returns
-    -------
-    int
-        The number of rows written to the JINJA2 file.
-    """
-    return stub.write(path, data, format_name='JINJA2')

etlplus/file/json.py

@@ -1,98 +0,0 @@
-"""
-:mod:`etlplus.file.json` module.
-
-Helpers for reading/writing JavaScript Object Notation (JSON) files.
-
-Notes
------
-- A JSON file is a widely used data interchange format that uses
-    human-readable text to represent structured data.
-- Common cases:
-    - Data interchange between web applications and servers.
-    - Configuration files for applications.
-    - Data storage for NoSQL databases.
-- Rule of thumb:
-    - If the file follows the JSON specification, use this module for
-        reading and writing.
-"""
-
-from __future__ import annotations
-
-import json
-from pathlib import Path
-
-from ..types import JSONData
-from ..utils import count_records
-from ._io import coerce_record_payload
-
-# SECTION: EXPORTS ========================================================== #
-
-
-__all__ = [
-    'read',
-    'write',
-]
-
-
-# SECTION: FUNCTIONS ======================================================== #
-
-
-def read(
-    path: Path,
-) -> JSONData:
-    """
-    Read JSON content from ``path``.
-
-    Validates that the JSON root is a dict or a list of dicts.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the JSON file on disk.
-
-    Returns
-    -------
-    JSONData
-        The structured data read from the JSON file.
-
-    Raises
-    ------
-    TypeError
-        If the JSON root is not an object or an array of objects.
-    """
-    with path.open('r', encoding='utf-8') as handle:
-        loaded = json.load(handle)
-
-    return coerce_record_payload(loaded, format_name='JSON')
-
-
-def write(
-    path: Path,
-    data: JSONData,
-) -> int:
-    """
-    Write ``data`` as formatted JSON to ``path``.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the JSON file on disk.
-    data : JSONData
-        Data to serialize as JSON.
-
-    Returns
-    -------
-    int
-        The number of records written to the JSON file.
-    """
-    path.parent.mkdir(parents=True, exist_ok=True)
-    with path.open('w', encoding='utf-8') as handle:
-        json.dump(
-            data,
-            handle,
-            indent=2,
-            ensure_ascii=False,
-        )
-        handle.write('\n')
-
-    return count_records(data)