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

etlplus/file/txt.py

@@ -0,0 +1,102 @@
+"""
+:mod:`etlplus.file.txt` module.
+
+Helpers for reading/writing text (TXT) files.
+
+Notes
+-----
+- A TXT file is a plain text file that contains unformatted text.
+- Common cases:
+    - Each line in the file represents a single piece of text.
+    - Lines may vary in length and content.
+- Rule of thumb:
+    - If the file is a simple text file without specific formatting
+        requirements, use this module for reading and writing.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..types import JSONData
+from ..types import JSONList
+from ..utils import count_records
+from ._io import normalize_records
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    'read',
+    'write',
+]
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def read(
+    path: Path,
+) -> JSONList:
+    """
+    Read TXT content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the TXT file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the TXT file.
+    """
+    rows: JSONList = []
+    with path.open('r', encoding='utf-8') as handle:
+        for line in handle:
+            text = line.rstrip('\n')
+            if text == '':
+                continue
+            rows.append({'text': text})
+    return rows
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to TXT at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the TXT file on disk.
+    data : JSONData
+        Data to write. Expects ``{'text': '...'} `` or a list of those.
+
+    Returns
+    -------
+    int
+        Number of records written.
+
+    Raises
+    ------
+    TypeError
+        If any item in ``data`` is not a dictionary or if any dictionary
+        does not contain a ``'text'`` key.
+    """
+    rows = normalize_records(data, 'TXT')
+
+    if not rows:
+        return 0
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open('w', encoding='utf-8') as handle:
+        for row in rows:
+            if 'text' not in row:
+                raise TypeError('TXT payloads must include a "text" key')
+            handle.write(str(row['text']))
+            handle.write('\n')
+
+    return count_records(rows)

etlplus/file/vm.py

@@ -0,0 +1,78 @@
+"""
+:mod:`etlplus.file.vm` module.
+
+Helpers for reading/writing Apache Velocity (VM) template files.
+
+Notes
+-----
+- A VM 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 Apache Velocity 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 VM content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the VM file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the VM file.
+    """
+    return stub.read(path, format_name='VM')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to VM file at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the VM file on disk.
+    data : JSONData
+        Data to write as VM file. Should be a list of dictionaries or a single
+        dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the VM file.
+    """
+    return stub.write(path, data, format_name='VM')

etlplus/file/wks.py

@@ -0,0 +1,77 @@
+"""
+:mod:`etlplus.file.wks` module.
+
+Helpers for reading/writing Lotus 1-2-3 (WKS) spreadsheet files.
+
+Notes
+-----
+- A WKS file is a spreadsheet file created using the Lotus 1-2-3 format.
+- Common cases:
+    - Reading data from legacy Lotus 1-2-3 spreadsheets.
+    - Writing data to Lotus 1-2-3 format for compatibility.
+    - Converting WKS files to more modern formats.
+- Rule of thumb:
+    - If you need to work with Lotus 1-2-3 spreadsheet 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 WKS content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the WKS file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the WKS file.
+    """
+    return stub.read(path, format_name='WKS')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to WKS file at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the WKS file on disk.
+    data : JSONData
+        Data to write as WKS file. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the WKS file.
+    """
+    return stub.write(path, data, format_name='WKS')

etlplus/file/xls.py

@@ -0,0 +1,88 @@
+"""
+:mod:`etlplus.file.xls` module.
+
+Helpers for reading/writing Excel XLS files.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import cast
+
+from ..types import JSONData
+from ..types import JSONList
+from ._imports import get_pandas
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    'read',
+    'write',
+]
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def read(
+    path: Path,
+) -> JSONList:
+    """
+    Read XLS content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the XLS file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the XLS file.
+
+    Raises
+    ------
+    ImportError
+        If the optional dependency "xlrd" is not installed.
+    """
+    pandas = get_pandas('XLS')
+    try:
+        frame = pandas.read_excel(path, engine='xlrd')
+    except ImportError as e:  # pragma: no cover
+        raise ImportError(
+            'XLS support requires optional dependency "xlrd".\n'
+            'Install with: pip install xlrd',
+        ) from e
+    return cast(JSONList, frame.to_dict(orient='records'))
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to XLS at ``path`` and return record count.
+
+    Notes
+    -----
+    XLS writing is not supported by pandas 2.x. Use XLSX for writes.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the XLS file on disk.
+    data : JSONData
+        Data to write.
+
+    Returns
+    -------
+    int
+        Number of records written.
+
+    Raises
+    ------
+    RuntimeError
+        If XLS writing is attempted.
+    """
+    raise RuntimeError('XLS write is not supported; use XLSX instead')

etlplus/file/xlsm.py

@@ -0,0 +1,79 @@
+"""
+:mod:`etlplus.file.xlsm` module.
+
+Helpers for reading/writing Microsoft Excel Macro-Enabled (XLSM) spreadsheet
+files.
+
+Notes
+-----
+- An XLSM file is a spreadsheet file created using the Microsoft Excel Macro-
+    Enabled (Open XML) format.
+- Common cases:
+    - Reading data from Excel Macro-Enabled spreadsheets.
+    - Writing data to Excel Macro-Enabled format for compatibility.
+    - Converting XLSM files to more modern formats.
+- Rule of thumb:
+    - If you need to work with Excel Macro-Enabled spreadsheet 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 XLSM content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the XLSM file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the XLSM file.
+    """
+    return stub.read(path, format_name='XLSM')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to XLSM file at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the XLSM file on disk.
+    data : JSONData
+        Data to write as XLSM file. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the XLSM file.
+    """
+    return stub.write(path, data, format_name='XLSM')

etlplus/file/xlsx.py

@@ -0,0 +1,99 @@
+"""
+:mod:`etlplus.file.xlsx` module.
+
+Helpers for reading/writing Excel XLSX files.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import cast
+
+from ..types import JSONData
+from ..types import JSONList
+from ._imports import get_pandas
+from ._io import normalize_records
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    'read',
+    'write',
+]
+
+
+# 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('XLSX')
+    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, 'XLSX')
+    if not records:
+        return 0
+
+    pandas = get_pandas('XLSX')
+    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,185 @@
+"""
+: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)