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

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

@@ -1,7 +1,18 @@
 """
 :mod:`etlplus.file.ndjson` module.
 
-Helpers for reading/writing NDJSON files.
+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
@@ -14,6 +25,7 @@ from ..types import JSONData
 from ..types import JSONDict
 from ..types import JSONList
 from ..utils import count_records
+from ._io import normalize_records
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -81,21 +93,8 @@ def write(
     -------
     int
         Number of records written.
-
-    Raises
-    ------
-    TypeError
-        If ``data`` is a list containing non-dict items.
     """
-    rows: JSONList
-    if isinstance(data, list):
-        if not all(isinstance(item, dict) for item in data):
-            raise TypeError(
-                'NDJSON payloads must contain only objects (dicts)',
-            )
-        rows = cast(JSONList, data)
-    else:
-        rows = [cast(JSONDict, data)]
+    rows = normalize_records(data, 'NDJSON')
 
     if not rows:
         return 0

etlplus/file/orc.py

@@ -1,18 +1,30 @@
 """
 :mod:`etlplus.file.orc` module.
 
-Helpers for reading/writing ORC files.
+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 Any
 from typing import cast
 
 from ..types import JSONData
-from ..types import JSONDict
 from ..types import JSONList
+from ._imports import get_pandas
+from ._io import normalize_records
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -23,49 +35,6 @@ __all__ = [
 ]
 
 
-# SECTION: INTERNAL CONSTANTS =============================================== #
-
-
-_PANDAS_CACHE: dict[str, Any] = {}
-
-
-# SECTION: INTERNAL FUNCTIONS =============================================== #
-
-
-def _get_pandas() -> Any:
-    """
-    Return the pandas module, importing it on first use.
-
-    Raises an informative ImportError if the optional dependency is missing.
-    """
-    mod = _PANDAS_CACHE.get('mod')
-    if mod is not None:  # pragma: no cover - tiny branch
-        return mod
-    try:
-        _pd = __import__('pandas')  # type: ignore[assignment]
-    except ImportError as e:  # pragma: no cover
-        raise ImportError(
-            'ORC support requires optional dependency "pandas".\n'
-            'Install with: pip install pandas',
-        ) from e
-    _PANDAS_CACHE['mod'] = _pd
-
-    return _pd
-
-
-def _normalize_records(data: JSONData) -> JSONList:
-    """
-    Normalize JSON payloads into a list of dictionaries.
-
-    Raises TypeError when payloads contain non-dict items.
-    """
-    if isinstance(data, list):
-        if not all(isinstance(item, dict) for item in data):
-            raise TypeError('ORC payloads must contain only objects (dicts)')
-        return cast(JSONList, data)
-    return [cast(JSONDict, data)]
-
-
 # SECTION: FUNCTIONS ======================================================== #
 
 
@@ -90,7 +59,7 @@ def read(
     ImportError
         When optional dependency "pyarrow" is missing.
     """
-    pandas = _get_pandas()
+    pandas = get_pandas('ORC')
     try:
         frame = pandas.read_orc(path)
     except ImportError as e:  # pragma: no cover
@@ -125,11 +94,11 @@ def write(
     ImportError
         When optional dependency "pyarrow" is missing.
     """
-    records = _normalize_records(data)
+    records = normalize_records(data, 'ORC')
     if not records:
         return 0
 
-    pandas = _get_pandas()
+    pandas = get_pandas('ORC')
     path.parent.mkdir(parents=True, exist_ok=True)
     frame = pandas.DataFrame.from_records(records)
     try:

etlplus/file/parquet.py

@@ -1,18 +1,30 @@
 """
 :mod:`etlplus.file.parquet` module.
 
-Helpers for reading/writing Parquet files.
+Helpers for reading/writing Apache Parquet (PARQUET) files.
+
+Notes
+-----
+- An Apache Parquet 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 Apache Parquet specification, use this module for
+        reading and writing.
 """
 
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any
 from typing import cast
 
 from ..types import JSONData
-from ..types import JSONDict
 from ..types import JSONList
+from ._imports import get_pandas
+from ._io import normalize_records
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -23,51 +35,6 @@ __all__ = [
 ]
 
 
-# SECTION: INTERNAL CONSTANTS =============================================== #
-
-
-_PANDAS_CACHE: dict[str, Any] = {}
-
-
-# SECTION: INTERNAL FUNCTIONS =============================================== #
-
-
-def _get_pandas() -> Any:
-    """
-    Return the pandas module, importing it on first use.
-
-    Raises an informative ImportError if the optional dependency is missing.
-    """
-    mod = _PANDAS_CACHE.get('mod')
-    if mod is not None:  # pragma: no cover - tiny branch
-        return mod
-    try:
-        _pd = __import__('pandas')  # type: ignore[assignment]
-    except ImportError as e:  # pragma: no cover
-        raise ImportError(
-            'Parquet support requires optional dependency "pandas".\n'
-            'Install with: pip install pandas',
-        ) from e
-    _PANDAS_CACHE['mod'] = _pd
-
-    return _pd
-
-
-def _normalize_records(data: JSONData) -> JSONList:
-    """
-    Normalize JSON payloads into a list of dictionaries.
-
-    Raises TypeError when payloads contain non-dict items.
-    """
-    if isinstance(data, list):
-        if not all(isinstance(item, dict) for item in data):
-            raise TypeError(
-                'Parquet payloads must contain only objects (dicts)',
-            )
-        return cast(JSONList, data)
-    return [cast(JSONDict, data)]
-
-
 # SECTION: FUNCTIONS ======================================================== #
 
 
@@ -92,7 +59,7 @@ def read(
     ImportError
         If optional dependencies for Parquet support are missing.
     """
-    pandas = _get_pandas()
+    pandas = get_pandas('Parquet')
     try:
         frame = pandas.read_parquet(path)
     except ImportError as e:  # pragma: no cover
@@ -128,11 +95,11 @@ def write(
     ImportError
         If optional dependencies for Parquet support are missing.
     """
-    records = _normalize_records(data)
+    records = normalize_records(data, 'Parquet')
     if not records:
         return 0
 
-    pandas = _get_pandas()
+    pandas = get_pandas('Parquet')
     path.parent.mkdir(parents=True, exist_ok=True)
     frame = pandas.DataFrame.from_records(records)
     try:

etlplus/file/pb.py

@@ -0,0 +1,78 @@
+"""
+:mod:`etlplus.file.pb` module.
+
+Helpers for reading/writing Protocol Buffer (PB) files.
+
+Notes
+-----
+- PB (a.k.a. Protobuff) is a binary serialization format developed by Google
+    for structured data.
+- Common cases:
+    - Data interchange between services.
+    - Efficient storage of structured data.
+    - Communication in distributed systems.
+- Rule of thumb:
+    - If the file follows the Protocol Buffer 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 PB content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the PB file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the PB file.
+    """
+    return stub.read(path, format_name='PB')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to PB at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the PB file on disk.
+    data : JSONData
+        Data to write as PB. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the PB file.
+    """
+    return stub.write(path, data, format_name='PB')

etlplus/file/pbf.py

@@ -0,0 +1,77 @@
+"""
+:mod:`etlplus.file.pbf` module.
+
+Helpers for reading/writing Protocolbuffer Binary Format (PBF) files.
+
+Notes
+-----
+- PBF is a binary format used primarily for OpenStreetMap (OSM) data.
+- Common cases:
+    - Efficient storage of large OSM datasets.
+    - Fast data interchange for mapping applications.
+    - Compression of OSM data for reduced file size.
+- Rule of thumb:
+    - If the file follows the PBF 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 PBF content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the PBF file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the PBF file.
+    """
+    return stub.read(path, format_name='PBF')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to PBF at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the PBF file on disk.
+    data : JSONData
+        Data to write as PBF. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the PBF file.
+    """
+    return stub.write(path, data, format_name='PBF')

etlplus/file/properties.py

@@ -0,0 +1,78 @@
+"""
+:mod:`etlplus.file.props` module.
+
+Helpers for reading/writing properties (PROPS) files.
+
+Notes
+-----
+- A “PROPS-formatted” file is a properties file that typically uses
+    key-value pairs, often with a simple syntax.
+- Common cases:
+    - Java-style properties files with ``key=value`` pairs.
+    - INI-style files without sections.
+    - Custom formats specific to certain applications.
+- Rule of thumb:
+    - If the file follows a standard format like INI, 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 PROPS content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the PROPS file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the PROPS file.
+    """
+    return stub.read(path, format_name='PROPS')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to PROPS at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the PROPS file on disk.
+    data : JSONData
+        Data to write as PROPS. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the PROPS file.
+    """
+    return stub.write(path, data, format_name='PROPS')

etlplus/file/proto.py

@@ -0,0 +1,77 @@
+"""
+:mod:`etlplus.file.proto` module.
+
+Helpers for reading/writing Protocol Buffers schema (PROTO) files.
+
+Notes
+-----
+- A PROTO file defines the structure of Protocol Buffers messages.
+- Common cases:
+    - Defining message formats for data interchange.
+    - Generating code for serialization/deserialization.
+    - Documenting data structures in distributed systems.
+- Rule of thumb:
+    - If the file follows the Protocol Buffers schema 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 PROTO content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the PROTO file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the PROTO file.
+    """
+    return stub.read(path, format_name='PROTO')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to PROTO at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the PROTO file on disk.
+    data : JSONData
+        Data to write as PROTO. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the PROTO file.
+    """
+    return stub.write(path, data, format_name='PROTO')