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

etlplus/file/xml.py

@@ -1,185 +0,0 @@
-"""
-:mod:`etlplus.file.xml` module.
-
-Helpers for reading/writing Extensible Markup Language (XML) files.
-
-Notes
------
-- An XML file is a markup language file that uses tags to define elements.
-- Common cases:
-    - Configuration files.
-    - Data interchange between systems.
-    - Document formatting.
-- Rule of thumb:
-    - If the file follows the XML specification, use this module for
-        reading and writing.
-"""
-
-from __future__ import annotations
-
-import xml.etree.ElementTree as ET
-from pathlib import Path
-from typing import Any
-
-from ..types import JSONData
-from ..types import JSONDict
-from ..utils import count_records
-
-# SECTION: EXPORTS ========================================================== #
-
-
-__all__ = [
-    'read',
-    'write',
-]
-
-
-# SECTION: CONSTANTS ======================================================== #
-
-
-DEFAULT_XML_ROOT = 'root'
-
-
-# SECTION: INTERNAL FUNCTIONS =============================================== #
-
-
-def _dict_to_element(
-    name: str,
-    payload: Any,
-) -> ET.Element:
-    """
-    Convert a dictionary-like payload into an XML element.
-
-    Parameters
-    ----------
-    name : str
-        Name of the XML element.
-    payload : Any
-        The data to include in the XML element.
-
-    Returns
-    -------
-    ET.Element
-        The constructed XML element.
-    """
-    element = ET.Element(name)
-
-    if isinstance(payload, dict):
-        text = payload.get('text')
-        if text is not None:
-            element.text = str(text)
-
-        for key, value in payload.items():
-            if key == 'text':
-                continue
-            if key.startswith('@'):
-                element.set(key[1:], str(value))
-                continue
-            if isinstance(value, list):
-                for item in value:
-                    element.append(_dict_to_element(key, item))
-            else:
-                element.append(_dict_to_element(key, value))
-    elif isinstance(payload, list):
-        for item in payload:
-            element.append(_dict_to_element('item', item))
-    elif payload is not None:
-        element.text = str(payload)
-
-    return element
-
-
-def _element_to_dict(
-    element: ET.Element,
-) -> JSONDict:
-    """
-    Convert an XML element into a nested dictionary.
-
-    Parameters
-    ----------
-    element : ET.Element
-        XML element to convert.
-
-    Returns
-    -------
-    JSONDict
-        Nested dictionary representation of the XML element.
-    """
-    result: JSONDict = {}
-    text = (element.text or '').strip()
-    if text:
-        result['text'] = text
-
-    for child in element:
-        child_data = _element_to_dict(child)
-        tag = child.tag
-        if tag in result:
-            existing = result[tag]
-            if isinstance(existing, list):
-                existing.append(child_data)
-            else:
-                result[tag] = [existing, child_data]
-        else:
-            result[tag] = child_data
-
-    for key, value in element.attrib.items():
-        if key in result:
-            result[f'@{key}'] = value
-        else:
-            result[key] = value
-    return result
-
-
-# SECTION: FUNCTIONS ======================================================== #
-
-
-def read(
-    path: Path,
-) -> JSONDict:
-    """
-    Read XML content from ``path``.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the XML file on disk.
-
-    Returns
-    -------
-    JSONDict
-        Nested dictionary representation of the XML file.
-    """
-    tree = ET.parse(path)
-    root = tree.getroot()
-
-    return {root.tag: _element_to_dict(root)}
-
-
-def write(path: Path, data: JSONData, *, root_tag: str) -> int:
-    """
-    Write ``data`` to XML at ``path`` and return record count.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the XML file on disk.
-    data : JSONData
-        Data to write as XML.
-    root_tag : str
-        Root tag name to use when writing XML files.
-
-    Returns
-    -------
-    int
-        The number of records written to the XML file.
-    """
-    if isinstance(data, dict) and len(data) == 1:
-        root_name, payload = next(iter(data.items()))
-        root_element = _dict_to_element(str(root_name), payload)
-    else:
-        root_element = _dict_to_element(root_tag, data)
-
-    tree = ET.ElementTree(root_element)
-    tree.write(path, encoding='utf-8', xml_declaration=True)
-
-    return count_records(data)

etlplus/file/xpt.py

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

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

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

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

@@ -1,50 +0,0 @@
-# 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)