etlplus 0.12.9__py3-none-any.whl → 0.12.11__py3-none-any.whl

etlplus/file/enums.py

@@ -66,8 +66,8 @@ class FileFormat(CoercibleStrEnum):
 
     # Tabular & delimited text
     CSV = 'csv'  # Comma-Separated Values
-    FWF = 'fwf'  # Fixed-Width Formatted
     DAT = 'dat'  # Generic data file, often delimited or fixed-width
+    FWF = 'fwf'  # Fixed-Width Formatted
     PSV = 'psv'  # Pipe-Separated Values
     TAB = 'tab'  # Often synonymous with TSV
     TSV = 'tsv'  # Tab-Separated Values
@@ -79,7 +79,7 @@ class FileFormat(CoercibleStrEnum):
     INI = 'ini'  # INI-style key-value pairs
     JSON = 'json'  # JavaScript Object Notation
     NDJSON = 'ndjson'  # Newline-Delimited JSON
-    PROPS = 'properties'  # Java-style key-value pairs
+    PROPERTIES = 'properties'  # Java-style key-value pairs
     TOML = 'toml'  # Tom's Obvious Minimal Language
     XML = 'xml'  # Extensible Markup Language
     YAML = 'yaml'  # YAML Ain't Markup Language
@@ -108,7 +108,7 @@ class FileFormat(CoercibleStrEnum):
 
     # Spreadsheets
     NUMBERS = 'numbers'  # Apple Numbers spreadsheet
-    ODS = 'ods'  # OpenDocument Spreadsheet
+    ODS = 'ods'  # OpenDocument spreadsheet
     WKS = 'wks'  # Lotus 1-2-3 spreadsheet
     XLS = 'xls'  # Microsoft Excel (BIFF); read-only
     XLSM = 'xlsm'  # Microsoft Excel Macro-Enabled (Open XML)
@@ -116,7 +116,7 @@ class FileFormat(CoercibleStrEnum):
 
     # Statistical / scientific / numeric computing
     DTA = 'dta'  # Stata data file
-    H5 = 'h5'  # Hierarchical Data Format
+    HDF5 = 'hdf5'  # Hierarchical Data Format
     MAT = 'mat'  # MATLAB data file
     NC = 'nc'  # NetCDF data file
     RDA = 'rda'  # RData workspace/object bundle
@@ -175,6 +175,12 @@ class FileFormat(CoercibleStrEnum):
 
     # Domain-specific & less common
 
+    # Templates
+    HBS = 'hbs'  # Handlebars
+    JINJA2 = 'jinja2'  # Jinja2
+    MUSTACHE = 'mustache'  # Mustache
+    VM = 'vm'  # Apache Velocity
+
     # -- Class Methods -- #
 
     @classmethod

etlplus/file/feather.py

@@ -1,7 +1,19 @@
 """
 :mod:`etlplus.file.feather` module.
 
-Helpers for reading/writing Feather files.
+Helpers for reading/writing Apache Arrow Feather (FEATHER) files.
+
+Notes
+-----
+- A FEATHER file is a binary file format designed for efficient
+    on-disk storage of data frames, built on top of Apache Arrow.
+- Common cases:
+    - Fast read/write operations for data frames.
+    - Interoperability between different data analysis tools.
+    - Storage of large datasets with efficient compression.
+- Rule of thumb:
+    - If the file follows the Apache Arrow Feather specification, use this
+        module for reading and writing.
 """
 
 from __future__ import annotations

etlplus/file/fwf.py

@@ -1,7 +1,18 @@
 """
 :mod:`etlplus.file.fwf` module.
 
-Helpers for reading/writing FWF (fixed-width fields) files.
+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

etlplus/file/hbs.py

@@ -0,0 +1,78 @@
+"""
+: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

@@ -0,0 +1,78 @@
+"""
+: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

@@ -0,0 +1,79 @@
+"""
+: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

@@ -0,0 +1,78 @@
+"""
+: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

@@ -0,0 +1,78 @@
+"""
+: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,7 +1,19 @@
 """
 :mod:`etlplus.file.json` module.
 
-Helpers for reading/writing JSON files.
+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

etlplus/file/log.py

@@ -0,0 +1,78 @@
+"""
+:mod:`etlplus.file.log` module.
+
+Helpers for reading/writing generic log (LOG) files.
+
+Notes
+-----
+- A LOG file is a plain text file that contains log messages generated by
+    applications or systems.
+- Common cases:
+    - Each line in the file represents a single log entry.
+    - Log entries may include timestamps, log levels, and messages.
+    - Formats may vary widely depending on the application generating the logs.
+- Rule of thumb:
+    - If the file is a generic log file, 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 LOG content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the LOG file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the LOG file.
+    """
+    return stub.read(path, format_name='LOG')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to LOG at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the LOG file on disk.
+    data : JSONData
+        Data to write as LOG. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the LOG file.
+    """
+    return stub.write(path, data, format_name='LOG')

etlplus/file/mat.py

@@ -0,0 +1,78 @@
+"""
+:mod:`etlplus.file.mat` module.
+
+Helpers for reading/writing MATLAB (MAT) data files.
+
+Notes
+-----
+- A MAT file is a binary file format used by MATLAB to store variables,
+    arrays, and other data structures.
+- Common cases:
+    - Storing numerical arrays and matrices.
+    - Saving workspace variables.
+    - Sharing data between MATLAB and other programming environments.
+- Rule of thumb:
+    - If the file follows the MAT-file 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 MAT content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the MAT file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the MAT file.
+    """
+    return stub.read(path, format_name='MAT')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to MAT file at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the MAT file on disk.
+    data : JSONData
+        Data to write as MAT file. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the MAT file.
+    """
+    return stub.write(path, data, format_name='MAT')