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

etlplus/file/tsv.py

@@ -1,80 +0,0 @@
-"""
-:mod:`etlplus.file.tsv` module.
-
-Helpers for reading/writing Tab-Separated Values (TSV) files.
-
-Notes
------
-- A TSV file is a plain text file that uses the tab character (``\t``) to
-    separate values.
-- Common cases:
-    - Each line in the file represents a single record.
-    - The first line often contains headers that define the column names.
-    - Values may be enclosed in quotes, especially if they contain tabs
-        or special characters.
-- Rule of thumb:
-    - If the file follows the TSV 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 ._io import read_delimited
-from ._io import write_delimited
-
-# SECTION: EXPORTS ========================================================== #
-
-
-__all__ = [
-    'read',
-    'write',
-]
-
-
-# SECTION: FUNCTIONS ======================================================== #
-
-
-def read(
-    path: Path,
-) -> JSONList:
-    """
-    Read TSV content from ``path``.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the TSV file on disk.
-
-    Returns
-    -------
-    JSONList
-        The list of dictionaries read from the TSV file.
-    """
-    return read_delimited(path, delimiter='\t')
-
-
-def write(
-    path: Path,
-    data: JSONData,
-) -> int:
-    """
-    Write ``data`` to TSV at ``path`` and return record count.
-
-    Parameters
-    ----------
-    path : Path
-        Path to the TSV file on disk.
-    data : JSONData
-        Data to write as TSV. Should be a list of dictionaries or a
-        single dictionary.
-
-    Returns
-    -------
-    int
-        The number of rows written to the TSV file.
-    """
-    return write_delimited(path, data, delimiter='\t')

etlplus/file/txt.py

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

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

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

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

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

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