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

etlplus/dag.py

@@ -0,0 +1,103 @@
+"""
+:mod:`etlplus.dag` module.
+
+Lightweight directed acyclic graph (DAG) helpers for ordering jobs based on
+``depends_on``.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+
+from .config.jobs import JobConfig
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    'DagError',
+    'topological_sort_jobs',
+]
+
+
+# SECTION: ERRORS =========================================================== #
+
+
+@dataclass(slots=True)
+class DagError(ValueError):
+    """
+    Raised when the job dependency graph is invalid.
+
+    Attributes
+    ----------
+    message : str
+        Error message.
+    """
+
+    # -- Attributes -- #
+
+    message: str
+
+    # -- Magic Methods (Object Representation) -- #
+
+    def __str__(self) -> str:
+        return self.message
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def topological_sort_jobs(
+    jobs: list[JobConfig],
+) -> list[JobConfig]:
+    """
+    Return jobs in topological order based on ``depends_on``.
+
+    Parameters
+    ----------
+    jobs : list[JobConfig]
+        List of job configurations to sort.
+
+    Returns
+    -------
+    list[JobConfig]
+        Jobs sorted in topological order.
+
+    Raises
+    ------
+    DagError
+        If a dependency is missing, self-referential, or when a cycle is
+        detected.
+    """
+    index = {job.name: job for job in jobs}
+    edges: dict[str, set[str]] = {name: set() for name in index}
+    indegree: dict[str, int] = {name: 0 for name in index}
+
+    for job in jobs:
+        for dep in job.depends_on:
+            if dep not in index:
+                raise DagError(
+                    f'Unknown dependency "{dep}" in job "{job.name}"',
+                )
+            if dep == job.name:
+                raise DagError(f'Job "{job.name}" depends on itself')
+            if job.name not in edges[dep]:
+                edges[dep].add(job.name)
+                indegree[job.name] += 1
+
+    queue = deque(sorted(name for name, deg in indegree.items() if deg == 0))
+    ordered: list[str] = []
+
+    while queue:
+        name = queue.popleft()
+        ordered.append(name)
+        for child in sorted(edges[name]):
+            indegree[child] -= 1
+            if indegree[child] == 0:
+                queue.append(child)
+
+    if len(ordered) != len(jobs):
+        raise DagError('Dependency cycle detected')
+
+    return [index[name] for name in ordered]

etlplus/enums.py

@@ -23,7 +23,6 @@ __all__ = [
     'AggregateName',
     'CoercibleStrEnum',
     'DataConnectorType',
-    'HttpMethod',
     'OperatorName',
     'PipelineStep',
 ]
@@ -200,37 +199,6 @@ class DataConnectorType(CoercibleStrEnum):
         }
 
 
-class HttpMethod(CoercibleStrEnum):
-    """Supported HTTP verbs that accept JSON payloads."""
-
-    # -- Constants -- #
-
-    CONNECT = 'connect'
-    DELETE = 'delete'
-    GET = 'get'
-    HEAD = 'head'
-    OPTIONS = 'options'
-    PATCH = 'patch'
-    POST = 'post'
-    PUT = 'put'
-    TRACE = 'trace'
-
-    # -- Getters -- #
-
-    @property
-    def allows_body(self) -> bool:
-        """
-        Whether the method typically allows a request body.
-
-        Notes
-        -----
-        - RFCs do not strictly forbid bodies on some other methods (e.g.,
-            ``DELETE``), but many servers/clients do not expect them. We mark
-            ``POST``, ``PUT``, and ``PATCH`` as True.
-        """
-        return self in {HttpMethod.POST, HttpMethod.PUT, HttpMethod.PATCH}
-
-
 class OperatorName(CoercibleStrEnum):
     """Supported comparison operators with helpers."""
 

etlplus/file/cfg.py

@@ -5,8 +5,8 @@ Helpers for reading/writing config (CFG) files.
 
 Notes
 -----
-- A “CFG-formatted” file is a configuration file that may use various
-    syntaxes, such as INI, YAML, or custom formats.
+- 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``).

etlplus/file/conf.py

@@ -5,8 +5,8 @@ Helpers for reading/writing config (CONF) files.
 
 Notes
 -----
-- A “CONF-formatted” file is a configuration file that may use various
-    syntaxes, such as INI, YAML, or custom formats.
+- 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.

etlplus/file/dta.py

@@ -0,0 +1,77 @@
+"""
+:mod:`etlplus.file.dta` module.
+
+Helpers for reading/writing Stata (DTA) data files.
+
+Notes
+-----
+- Stata DTA files are binary files used by Stata statistical software that
+    store datasets with variables, labels, and data types.
+- Common cases:
+    - Reading data for analysis in Python.
+    - Writing processed data back to Stata format.
+- Rule of thumb:
+    - If you need to work with Stata data 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 DTA content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the DTA file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the DTA file.
+    """
+    return stub.read(path, format_name='DTA')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to DTA file at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the DTA file on disk.
+    data : JSONData
+        Data to write as DTA file. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the DTA file.
+    """
+    return stub.write(path, data, format_name='DTA')

etlplus/file/enums.py

@@ -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,14 +116,14 @@ 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
     RDS = 'rds'  # R data file
     SAS7BDAT = 'sas7bdat'  # SAS data file
     SAV = 'sav'  # SPSS data file
-    SYLK = 'sylk'  # Symbolic Link (SYmbolic LinK)
+    SYLK = 'sylk'  # Symbolic Link
     XPT = 'xpt'  # SAS Transport file
     ZSAV = 'zsav'  # Compressed SPSS data file
 
@@ -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/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/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/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')

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