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

etlplus/file/xpt.py

@@ -0,0 +1,78 @@
+"""
+:mod:`etlplus.file.xpt` module.
+
+Helpers for reading/writing SAS Transport (XPT) files.
+
+Notes
+-----
+- A SAS Transport (XPT) file is a standardized file format used to transfer
+    SAS datasets between different systems.
+- Common cases:
+    - Sharing datasets between different SAS installations.
+    - Archiving datasets in a platform-independent format.
+    - Importing/exporting data to/from statistical software that supports XPT.
+- Rule of thumb:
+    - If you need to work with XPT 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 XPT content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the XPT file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the XPT file.
+    """
+    return stub.read(path, format_name='XPT')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to XPT file at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the XPT file on disk.
+    data : JSONData
+        Data to write as XPT file. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the XPT file.
+    """
+    return stub.write(path, data, format_name='XPT')

etlplus/file/yaml.py

@@ -0,0 +1,95 @@
+"""
+:mod:`etlplus.file.yaml` module.
+
+Helpers for reading/writing YAML Ain't Markup Language (YAML) files.
+
+Notes
+-----
+- A YAML file is a human-readable data serialization format.
+- Common cases:
+    - Configuration files.
+    - Data exchange between languages with different data structures.
+    - Complex data storage.
+- Rule of thumb:
+    - If the file follows the YAML specification, use this module for
+        reading and writing.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..types import JSONData
+from ..utils import count_records
+from ._imports import get_yaml
+from ._io import coerce_record_payload
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    'read',
+    'write',
+]
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def read(
+    path: Path,
+) -> JSONData:
+    """
+    Read YAML content from ``path``.
+
+    Validates that the YAML root is a dict or a list of dicts.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the YAML file on disk.
+
+    Returns
+    -------
+    JSONData
+        The structured data read from the YAML file.
+
+    Raises
+    ------
+    TypeError
+        If the YAML root is not an object or an array of objects.
+    """
+    with path.open('r', encoding='utf-8') as handle:
+        loaded = get_yaml().safe_load(handle)
+
+    return coerce_record_payload(loaded, format_name='YAML')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` as YAML to ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the YAML file on disk.
+    data : JSONData
+        Data to write as YAML.
+
+    Returns
+    -------
+    int
+        The number of records written.
+    """
+    with path.open('w', encoding='utf-8') as handle:
+        get_yaml().safe_dump(
+            data,
+            handle,
+            sort_keys=False,
+            allow_unicode=True,
+            default_flow_style=False,
+        )
+    return count_records(data)

etlplus/file/zip.py

@@ -0,0 +1,175 @@
+"""
+:mod:`etlplus.file.zip` module.
+
+Helpers for reading/writing ZIP files.
+"""
+
+from __future__ import annotations
+
+import tempfile
+import zipfile
+from pathlib import Path
+
+from ..types import JSONData
+from ..types import JSONDict
+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(
+    filename: str,
+) -> FileFormat:
+    """
+    Resolve the inner file format from a filename.
+
+    Parameters
+    ----------
+    filename : str
+        The name of the file inside the ZIP archive.
+
+    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(filename)
+    if compression is not None and compression is not CompressionFormat.ZIP:
+        raise ValueError(f'Unexpected compression in archive: {filename}')
+    if fmt is None:
+        raise ValueError(
+            f'Cannot infer file format from compressed file {filename!r}',
+        )
+    return fmt
+
+
+def _extract_payload(
+    entry: zipfile.ZipInfo,
+    archive: zipfile.ZipFile,
+) -> bytes:
+    """
+    Extract an archive entry into memory.
+
+    Parameters
+    ----------
+    entry : zipfile.ZipInfo
+        The ZIP archive entry.
+    archive : zipfile.ZipFile
+        The opened ZIP archive.
+
+    Returns
+    -------
+    bytes
+        The raw payload.
+    """
+    with archive.open(entry, 'r') as handle:
+        return handle.read()
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def read(
+    path: Path,
+) -> JSONData:
+    """
+    Read ZIP content from ``path`` and parse the inner payload(s).
+
+    Parameters
+    ----------
+    path : Path
+        Path to the ZIP file on disk.
+
+    Returns
+    -------
+    JSONData
+        Parsed payload.
+
+    Raises
+    ------
+    ValueError
+        If the ZIP archive is empty.
+    """
+    with zipfile.ZipFile(path, 'r') as archive:
+        entries = [entry for entry in archive.infolist() if not entry.is_dir()]
+        if not entries:
+            raise ValueError(f'ZIP archive is empty: {path}')
+
+        if len(entries) == 1:
+            entry = entries[0]
+            fmt = _resolve_format(entry.filename)
+            payload = _extract_payload(entry, archive)
+            with tempfile.TemporaryDirectory() as tmpdir:
+                tmp_path = Path(tmpdir) / Path(entry.filename).name
+                tmp_path.write_bytes(payload)
+                from .core import File
+
+                return File(tmp_path, fmt).read()
+
+        results: JSONDict = {}
+        for entry in entries:
+            fmt = _resolve_format(entry.filename)
+            payload = _extract_payload(entry, archive)
+            with tempfile.TemporaryDirectory() as tmpdir:
+                tmp_path = Path(tmpdir) / Path(entry.filename).name
+                tmp_path.write_bytes(payload)
+                from .core import File
+
+                results[entry.filename] = File(tmp_path, fmt).read()
+        return results
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to ZIP at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the ZIP file on disk.
+    data : JSONData
+        Data to write.
+
+    Returns
+    -------
+    int
+        Number of records written.
+    """
+    fmt = _resolve_format(path.name)
+    inner_name = Path(path.name).with_suffix('').name
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmp_path = Path(tmpdir) / inner_name
+        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 zipfile.ZipFile(
+        path,
+        'w',
+        compression=zipfile.ZIP_DEFLATED,
+    ) as archive:
+        archive.writestr(inner_name, payload)
+
+    return count

etlplus/file/zsav.py

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

etlplus/ops/README.md

@@ -0,0 +1,50 @@
+# etlplus.ops subpackage
+
+Documentation for the `etlplus.validation` subpackage: data validation utilities and helpers.
+
+- Provides flexible data validation for ETL pipelines
+- Supports type checking, required fields, and custom rules
+- Includes utilities for rule definition and validation logic
+
+Back to project overview: see the top-level [README](../../README.md).
+
+- [etlplus.ops subpackage](#etlplusops-subpackage)
+  - [Validation Features](#validation-features)
+  - [Defining Validation Rules](#defining-validation-rules)
+  - [Example: Validating Data](#example-validating-data)
+  - [See Also](#see-also)
+
+## Validation Features
+
+- Type checking (string, number, boolean, etc.)
+- Required/optional fields
+- Enum and pattern validation
+- Custom rule support
+
+## Defining Validation Rules
+
+Validation rules are defined as dictionaries specifying field types, requirements, and constraints:
+
+```python
+rules = {
+    "name": {"type": "string", "required": True},
+    "age": {"type": "number", "min": 0, "max": 120},
+}
+```
+
+## Example: Validating Data
+
+```python
+from etlplus.validation import validate
+
+result = validate({"name": "Alice", "age": 30}, rules)
+if result["valid"]:
+    print("Data is valid!")
+else:
+    print(result["errors"])
+```
+
+## See Also
+
+- Top-level CLI and library usage in the main [README](../../README.md)
+- Validation utilities in [utils.py](utils.py)

etlplus/ops/__init__.py

@@ -0,0 +1,61 @@
+"""
+:mod:`etlplus.ops` package.
+
+Data operations helpers.
+
+Importing :mod:`etlplus.ops` exposes the coarse-grained helpers most users care
+about: ``extract``, ``transform``, ``load``, ``validate``, ``run``, and
+``run_pipeline``. Each helper delegates to the richer modules under
+``etlplus.ops.*`` while presenting a compact public API surface. Conditional
+validation orchestration is available via
+:func:`etlplus.ops.utils.maybe_validate`. The legacy compatibility module
+:mod:`etlplus.ops.__init__validation` is deprecated in favor of this package.
+
+Examples
+--------
+>>> from etlplus.ops import extract, transform
+>>> raw = extract('file', 'input.json')
+>>> curated = transform(raw, {'select': ['id', 'name']})
+
+>>> from etlplus.ops.utils import maybe_validate
+>>> payload = {'name': 'Alice'}
+>>> rules = {'required': ['name']}
+>>> def validator(data, config):
+...     missing = [field for field in config['required'] if field not in data]
+...     return {'valid': not missing, 'errors': missing, 'data': data}
+>>> maybe_validate(
+...     payload,
+...     when='both',
+...     enabled=True,
+...     rules=rules,
+...     phase='before_transform',
+...     severity='warn',
+...     validate_fn=validator,
+...     print_json_fn=lambda message: message,
+... )
+{'name': 'Alice'}
+
+See Also
+--------
+:mod:`etlplus.ops.run`
+:mod:`etlplus.ops.utils`
+"""
+
+from .extract import extract
+from .load import load
+from .run import run
+from .run import run_pipeline
+from .transform import transform
+from .validate import validate
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    'extract',
+    'load',
+    'run',
+    'run_pipeline',
+    'transform',
+    'validate',
+]