etlplus 0.10.4__py3-none-any.whl → 0.12.2__py3-none-any.whl

etlplus/file/xlsx.py

@@ -0,0 +1,142 @@
+"""
+:mod:`etlplus.file.xlsx` module.
+
+Helpers for reading/writing Excel XLSX files.
+"""
+
+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
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    'read',
+    'write',
+]
+
+
+# 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(
+            'XLSX 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('XLSX payloads must contain only objects (dicts)')
+        return cast(JSONList, data)
+    return [cast(JSONDict, data)]
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def read(
+    path: Path,
+) -> JSONList:
+    """
+    Read XLSX content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the XLSX file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the XLSX file.
+
+    Raises
+    ------
+    ImportError
+        If optional dependencies for XLSX support are missing.
+    """
+    pandas = _get_pandas()
+    try:
+        frame = pandas.read_excel(path)
+    except ImportError as e:  # pragma: no cover
+        raise ImportError(
+            'XLSX support requires optional dependency "openpyxl".\n'
+            'Install with: pip install openpyxl',
+        ) from e
+    return cast(JSONList, frame.to_dict(orient='records'))
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to XLSX at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the XLSX file on disk.
+    data : JSONData
+        Data to write.
+
+    Returns
+    -------
+    int
+        Number of records written.
+
+    Raises
+    ------
+    ImportError
+        If optional dependencies for XLSX support are missing.
+    """
+    records = _normalize_records(data)
+    if not records:
+        return 0
+
+    pandas = _get_pandas()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    frame = pandas.DataFrame.from_records(records)
+    try:
+        frame.to_excel(path, index=False)
+    except ImportError as e:  # pragma: no cover
+        raise ImportError(
+            'XLSX support requires optional dependency "openpyxl".\n'
+            'Install with: pip install openpyxl',
+        ) from e
+    return len(records)

etlplus/file/xml.py

@@ -0,0 +1,174 @@
+"""
+:mod:`etlplus.file.xml` module.
+
+Helpers for reading/writing XML files.
+"""
+
+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/yaml.py

@@ -0,0 +1,136 @@
+"""
+:mod:`etlplus.file.yaml` module.
+
+Helpers for reading/writing YAML files.
+"""
+
+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 ..utils import count_records
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    'read',
+    'write',
+]
+
+
+# SECTION: INTERNAL CONSTANTS =============================================== #
+
+
+# Optional YAML support (lazy-loaded to avoid hard dependency)
+# Cached access function to avoid global statements.
+_YAML_CACHE: dict[str, Any] = {}
+
+
+# SECTION: INTERNAL FUNCTIONS =============================================== #
+
+
+def _get_yaml() -> Any:
+    """
+    Return the PyYAML module, importing it on first use.
+
+    Raises an informative ImportError if the optional dependency is missing.
+    """
+    mod = _YAML_CACHE.get('mod')
+    if mod is not None:  # pragma: no cover - tiny branch
+        return mod
+    try:
+        _yaml_mod = __import__('yaml')  # type: ignore[assignment]
+    except ImportError as e:  # pragma: no cover
+        raise ImportError(
+            'YAML support requires optional dependency "PyYAML".\n'
+            'Install with: pip install PyYAML',
+        ) from e
+    _YAML_CACHE['mod'] = _yaml_mod
+
+    return _yaml_mod
+
+
+def _require_yaml() -> None:
+    """Ensure PyYAML is available or raise an informative error."""
+    _get_yaml()
+
+
+# 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.
+    """
+    _require_yaml()
+
+    with path.open('r', encoding='utf-8') as handle:
+        loaded = _get_yaml().safe_load(handle)
+
+    if isinstance(loaded, dict):
+        return cast(JSONDict, loaded)
+    if isinstance(loaded, list):
+        if all(isinstance(item, dict) for item in loaded):
+            return cast(JSONList, loaded)
+        raise TypeError(
+            'YAML array must contain only objects (dicts) when loading',
+        )
+    raise TypeError(
+        'YAML root must be an object or an array of objects when loading',
+    )
+
+
+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.
+    """
+    _require_yaml()
+    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/load.py

@@ -15,12 +15,9 @@ from typing import cast
 import requests  # type: ignore[import]
 
 from .enums import DataConnectorType
-from .enums import FileFormat
 from .enums import HttpMethod
-from .enums import coerce_data_connector_type
-from .enums import coerce_file_format
-from .enums import coerce_http_method
 from .file import File
+from .file import FileFormat
 from .types import JSONData
 from .types import JSONDict
 from .types import JSONList
@@ -101,7 +98,7 @@ def load_data(
         return cast(JSONData, source)
 
     if isinstance(source, Path):
-        return File(source, FileFormat.JSON).read_json()
+        return File(source, FileFormat.JSON).read()
 
     if isinstance(source, str):
         # Special case: '-' means read JSON from STDIN (Unix convention).
@@ -111,7 +108,7 @@ def load_data(
         candidate = Path(source)
         if candidate.exists():
             try:
-                return File(candidate, FileFormat.JSON).read_json()
+                return File(candidate, FileFormat.JSON).read()
             except (OSError, json.JSONDecodeError, ValueError):
                 # Fall back to treating the string as raw JSON content.
                 pass
@@ -155,9 +152,9 @@ def load_to_file(
     if file_format is None:
         records = File(path).write(data)
         ext = path.suffix.lstrip('.').lower()
-        fmt = coerce_file_format(ext) if ext else FileFormat.JSON
+        fmt = FileFormat.coerce(ext) if ext else FileFormat.JSON
     else:
-        fmt = coerce_file_format(file_format)
+        fmt = FileFormat.coerce(file_format)
         records = File(path, fmt).write(data)
     if fmt is FileFormat.CSV and records == 0:
         message = 'No data to write'
@@ -242,7 +239,7 @@ def load_to_api(
     TypeError
         If the session object is not valid.
     """
-    http_method = coerce_http_method(method)
+    http_method = HttpMethod.coerce(method)
 
     # Apply a conservative timeout to guard against hanging requests.
     timeout = kwargs.pop('timeout', 10.0)
@@ -316,7 +313,7 @@ def load(
     """
     data = load_data(source)
 
-    match coerce_data_connector_type(target_type):
+    match DataConnectorType.coerce(target_type):
         case DataConnectorType.FILE:
             # Prefer explicit format if provided, else infer from filename.
             return load_to_file(data, target, file_format)
@@ -331,6 +328,6 @@ def load(
                 **kwargs,
             )
         case _:
-            # `coerce_data_connector_type` covers invalid entries, but keep
-            # explicit guard.
+            # :meth:`coerce` already raises for invalid connector types, but
+            # keep explicit guard for defensive programming.
             raise ValueError(f'Invalid target type: {target_type}')