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

etlplus/file/mdb.py

@@ -0,0 +1,78 @@
+"""
+:mod:`etlplus.file.mdb` module.
+
+Helpers for reading/writing newer Microsoft Access database (MDB) files.
+
+Notes
+-----
+- An MDB file is a proprietary database file format used by Microsoft Access
+    2003 and earlier.
+- 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 MDB 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 CSV content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the CSV file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the CSV file.
+    """
+    return stub.read(path, format_name='DAT')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to CSV at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the CSV file on disk.
+    data : JSONData
+        Data to write as CSV. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the CSV file.
+    """
+    return stub.write(path, data, format_name='DAT')

etlplus/file/msgpack.py

@@ -0,0 +1,78 @@
+"""
+:mod:`etlplus.file.msgpack` module.
+
+Helpers for reading/writing MessagePack (MSGPACK) files.
+
+Notes
+-----
+- A MsgPack file is a binary serialization format that is more compact than
+    JSON.
+- Common cases:
+    - Efficient data storage and transmission.
+    - Inter-process communication.
+    - Data serialization in performance-critical applications.
+- Rule of thumb:
+    - If the file follows the MsgPack 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 MsgPack content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the MsgPack file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the MsgPack file.
+    """
+    return stub.read(path, format_name='MSGPACK')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to MsgPack at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the MsgPack file on disk.
+    data : JSONData
+        Data to write as MsgPack. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the MsgPack file.
+    """
+    return stub.write(path, data, format_name='MSGPACK')

etlplus/file/mustache.py

@@ -0,0 +1,78 @@
+"""
+:mod:`etlplus.file.mustache` module.
+
+Helpers for reading/writing Mustache (MUSTACHE) template files.
+
+Notes
+-----
+- A MUSTACHE 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 Mustache 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 MUSTACHE content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the MUSTACHE file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the MUSTACHE file.
+    """
+    return stub.read(path, format_name='MUSTACHE')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to MUSTACHE file at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the MUSTACHE file on disk.
+    data : JSONData
+        Data to write as MUSTACHE file. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the MUSTACHE file.
+    """
+    return stub.write(path, data, format_name='MUSTACHE')

etlplus/file/nc.py

@@ -0,0 +1,78 @@
+"""
+:mod:`etlplus.file.nc` module.
+
+Helpers for reading/writing NetCDF (NC) data files.
+
+Notes
+-----
+- A NC file is a binary file format used for array-oriented scientific data,
+    particularly in meteorology, oceanography, and climate science.
+- Common cases:
+    - Storing multi-dimensional scientific data.
+    - Sharing large datasets in research communities.
+    - Efficient data access and manipulation.
+- Rule of thumb:
+    - If the file follows the NetCDF standard, 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 NC content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the NC file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the NC file.
+    """
+    return stub.read(path, format_name='NC')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to NC file at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the NC file on disk.
+    data : JSONData
+        Data to write as NC file. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the NC file.
+    """
+    return stub.write(path, data, format_name='NC')

etlplus/file/ndjson.py

@@ -0,0 +1,108 @@
+"""
+:mod:`etlplus.file.ndjson` module.
+
+Helpers for reading/writing Newline Delimited JSON (NDJSON) files.
+
+Notes
+-----
+- An NDJSON file is a format where each line is a separate JSON object.
+- Common cases:
+    - Streaming JSON data.
+    - Log files with JSON entries.
+    - Large datasets that are processed line-by-line.
+- Rule of thumb:
+    - If the file follows the NDJSON specification, use this module for
+        reading and writing.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import cast
+
+from ..types import JSONData
+from ..types import JSONDict
+from ..types import JSONList
+from ..utils import count_records
+from ._io import normalize_records
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    'read',
+    'write',
+]
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def read(
+    path: Path,
+) -> JSONList:
+    """
+    Read NDJSON content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the NDJSON file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the NDJSON file.
+
+    Raises
+    ------
+    TypeError
+        If any line in the NDJSON file is not a JSON object (dict).
+    """
+    rows: JSONList = []
+    with path.open('r', encoding='utf-8') as handle:
+        for idx, line in enumerate(handle, start=1):
+            text = line.strip()
+            if not text:
+                continue
+            payload = json.loads(text)
+            if not isinstance(payload, dict):
+                raise TypeError(
+                    f'NDJSON lines must be objects (dicts) (line {idx})',
+                )
+            rows.append(cast(JSONDict, payload))
+    return rows
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to NDJSON at ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the NDJSON file on disk.
+    data : JSONData
+        Data to write.
+
+    Returns
+    -------
+    int
+        Number of records written.
+    """
+    rows = normalize_records(data, 'NDJSON')
+
+    if not rows:
+        return 0
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open('w', encoding='utf-8') as handle:
+        for row in rows:
+            handle.write(json.dumps(row, ensure_ascii=False))
+            handle.write('\n')
+
+    return count_records(rows)

etlplus/file/numbers.py

@@ -0,0 +1,75 @@
+"""
+:mod:`etlplus.file.numbers` module.
+
+Helpers for reading/writing Apple Numbers (NUMBERS) spreadsheet files.
+
+Notes
+-----
+- A NUMBERS file is a spreadsheet file created by Apple Numbers.
+- Common cases:
+    - Spreadsheet files created by Apple Numbers.
+- Rule of thumb:
+    - If you need to read/write NUMBERS files, consider converting them to
+        more common formats like CSV or XLSX for better compatibility.
+"""
+
+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 NUMBERS content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the NUMBERS file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the NUMBERS file.
+    """
+    return stub.read(path, format_name='NUMBERS')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to NUMBERS file at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the NUMBERS file on disk.
+    data : JSONData
+        Data to write as NUMBERS file. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the NUMBERS file.
+    """
+    return stub.write(path, data, format_name='NUMBERS')

etlplus/file/ods.py

@@ -0,0 +1,79 @@
+"""
+:mod:`etlplus.file.ods` module.
+
+Helpers for reading/writing OpenDocument (ODS) spreadsheet files.
+
+Notes
+-----
+- An ODS file is a spreadsheet file created using the OpenDocument format.
+- Common cases:
+    - Spreadsheet files created by LibreOffice Calc, Apache OpenOffice Calc, or
+        other applications that support the OpenDocument format.
+    - Spreadsheet files exchanged in open standards environments.
+    - Spreadsheet files used in government or educational institutions
+        promoting open formats.
+- Rule of thumb:
+    - If the file follows the OpenDocument 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 ODS content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the ODS file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the ODS file.
+    """
+    return stub.read(path, format_name='ODS')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to ODS file at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the ODS file on disk.
+    data : JSONData
+        Data to write as ODS file. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the ODS file.
+    """
+    return stub.write(path, data, format_name='ODS')

etlplus/file/orc.py

@@ -0,0 +1,111 @@
+"""
+:mod:`etlplus.file.orc` module.
+
+Helpers for reading/writing Optimized Row Columnar (ORC) files.
+
+Notes
+-----
+- An ORC file is a columnar storage file format optimized for Big Data
+    processing.
+- Common cases:
+    - Efficient storage and retrieval of large datasets.
+    - Integration with big data frameworks like Apache Hive and Apache Spark.
+    - Compression and performance optimization for analytical queries.
+- Rule of thumb:
+    - If the file follows the ORC specification, use this module for reading
+        and writing.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import cast
+
+from ..types import JSONData
+from ..types import JSONList
+from ._imports import get_pandas
+from ._io import normalize_records
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    'read',
+    'write',
+]
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def read(
+    path: Path,
+) -> JSONList:
+    """
+    Read ORC content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the ORC file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the ORC file.
+
+    Raises
+    ------
+    ImportError
+        When optional dependency "pyarrow" is missing.
+    """
+    pandas = get_pandas('ORC')
+    try:
+        frame = pandas.read_orc(path)
+    except ImportError as e:  # pragma: no cover
+        raise ImportError(
+            'ORC support requires optional dependency "pyarrow".\n'
+            'Install with: pip install pyarrow',
+        ) from e
+    return cast(JSONList, frame.to_dict(orient='records'))
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to ORC at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the ORC file on disk.
+    data : JSONData
+        Data to write.
+
+    Returns
+    -------
+    int
+        Number of records written.
+
+    Raises
+    ------
+    ImportError
+        When optional dependency "pyarrow" is missing.
+    """
+    records = normalize_records(data, 'ORC')
+    if not records:
+        return 0
+
+    pandas = get_pandas('ORC')
+    path.parent.mkdir(parents=True, exist_ok=True)
+    frame = pandas.DataFrame.from_records(records)
+    try:
+        frame.to_orc(path, index=False)
+    except ImportError as e:  # pragma: no cover
+        raise ImportError(
+            'ORC support requires optional dependency "pyarrow".\n'
+            'Install with: pip install pyarrow',
+        ) from e
+    return len(records)