etlplus 0.12.1__py3-none-any.whl → 0.12.10__py3-none-any.whl

etlplus/file/psv.py

@@ -0,0 +1,79 @@
+"""
+:mod:`etlplus.file.psv` module.
+
+Helpers for reading/writing Pipe-Separated Values (PSV) files.
+
+Notes
+-----
+- A PSV file is a plain text file that uses the pipe character (`|`) 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 pipes
+        or special characters.
+- Rule of thumb:
+    - If the file follows the PSV 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 . import stub
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    'read',
+    'write',
+]
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def read(
+    path: Path,
+) -> JSONList:
+    """
+    Read PSV content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the PSV file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the PSV file.
+    """
+    return stub.read(path, format_name='PSV')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to PSV file at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the PSV file on disk.
+    data : JSONData
+        Data to write as PSV file. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the PSV file.
+    """
+    return stub.write(path, data, format_name='PSV')

etlplus/file/sqlite.py

@@ -0,0 +1,78 @@
+"""
+:mod:`etlplus.file.sqlite` module.
+
+Helpers for reading/writing SQLite database (SQLITE) files.
+
+Notes
+-----
+- A SQLITE file is a self-contained, serverless database file format used by
+    SQLite.
+- Common cases:
+    - Lightweight database applications.
+    - Embedded database solutions.
+    - Mobile and desktop applications requiring local data storage.
+- Rule of thumb:
+    - If the file follows the SQLITE 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 . import stub
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    'read',
+    'write',
+]
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def read(
+    path: Path,
+) -> JSONList:
+    """
+    Read SQLITE content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the SQLITE file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the SQLITE file.
+    """
+    return stub.read(path, format_name='SQLITE')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to SQLITE at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the SQLITE file on disk.
+    data : JSONData
+        Data to write as SQLITE. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the SQLITE file.
+    """
+    return stub.write(path, data, format_name='SQLITE')

etlplus/file/stub.py

@@ -0,0 +1,84 @@
+"""
+:mod:`etlplus.file.stub` module.
+
+Helpers for reading/writing stubbed files.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..types import JSONData
+from ..types import JSONList
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    'read',
+    'write',
+]
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def read(
+    path: Path,
+    format_name: str = 'Stubbed',
+) -> JSONList:
+    """
+    Raises a :class:`NotImplementedError` for stubbed reads.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the stubbed file on disk.
+    format_name : str
+        Human-readable format name.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the stubbed file.
+
+    Raises
+    ------
+    NotImplementedError
+        Always, since this is a stub implementation.
+    """
+    _ = path
+    raise NotImplementedError(f'{format_name} read is not implemented yet')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+    format_name: str = 'Stubbed',
+) -> int:
+    """
+    Raises a :class:`NotImplementedError` for stubbed writes.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the stubbed file on disk.
+    data : JSONData
+        Data to write as stubbed file. Should be a list of dictionaries or a
+        single dictionary.
+    format_name : str
+        Human-readable format name.
+
+    Returns
+    -------
+    int
+        The number of rows written to the stubbed file.
+
+    Raises
+    ------
+    NotImplementedError
+        Always, since this is a stub implementation.
+    """
+    _ = path
+    _ = data
+    raise NotImplementedError(f'{format_name} write is not implemented yet')

etlplus/file/tab.py

@@ -0,0 +1,81 @@
+"""
+:mod:`etlplus.file.tab` module.
+
+Helpers for reading/writing "tab"-formatted (TAB) files.
+
+Notes
+-----
+- A TAB file is not necessarily a TSV file when tabs aren’t actually the
+    delimiter that defines the fields, even if the text looks column-aligned.
+- Common cases:
+    - Fixed-width text (FWF) that uses tabs for alignment.
+    - Mixed whitespace (tabs + spaces) as “pretty printing”.
+    - Tabs embedded inside quoted fields (or unescaped tabs in free text).
+    - Header/metadata lines or multi-line records that break TSV assumptions.
+    - Not actually tab-delimited despite the name.
+- Rule of thumb:
+    - If the file is truly tab-delimited, use :mod:`etlplus.file.tsv`.
+    - If the file has fixed-width fields, use :mod:`etlplus.file.fwf`.
+    - Otherwise, use :mod:`etlplus.file.tab` (i.e., this module).
+"""
+
+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 TAB content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the TAB file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the TAB file.
+    """
+    return stub.read(path, format_name='TAB')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to TAB file at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the TAB file on disk.
+    data : JSONData
+        Data to write as TAB file. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the TAB file.
+    """
+    return stub.write(path, data, format_name='TAB')

etlplus/file/toml.py

@@ -0,0 +1,78 @@
+"""
+:mod:`etlplus.file.toml` module.
+
+Helpers for reading/writing Tom's Obvious Minimal Language (TOML) files.
+
+Notes
+-----
+- A “TOML-formatted” file is a configuration file that uses the TOML syntax.
+- Common cases:
+    - Simple key-value pairs.
+    - Nested tables and arrays.
+    - Data types such as strings, integers, floats, booleans, dates, and
+        arrays.
+- Rule of thumb:
+    - If the file follows the TOML 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 . import stub
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    'read',
+    'write',
+]
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def read(
+    path: Path,
+) -> JSONList:
+    """
+    Read TOML content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the TOML file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the TOML file.
+    """
+    return stub.read(path, format_name='TOML')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to TOML at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the TOML file on disk.
+    data : JSONData
+        Data to write as TOML. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the TOML file.
+    """
+    return stub.write(path, data, format_name='TOML')

etlplus/file/tsv.py

@@ -1,18 +1,30 @@
 """
 :mod:`etlplus.file.tsv` module.
 
-Helpers for reading/writing TSV files.
+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
 
-import csv
 from pathlib import Path
-from typing import cast
 
 from ..types import JSONData
-from ..types import JSONDict
 from ..types import JSONList
+from ._io import read_delimited
+from ._io import write_delimited
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -42,14 +54,7 @@ def read(
     JSONList
         The list of dictionaries read from the TSV file.
     """
-    with path.open('r', encoding='utf-8', newline='') as handle:
-        reader: csv.DictReader[str] = csv.DictReader(handle, delimiter='\t')
-        rows: JSONList = []
-        for row in reader:
-            if not any(row.values()):
-                continue
-            rows.append(cast(JSONDict, dict(row)))
-    return rows
+    return read_delimited(path, delimiter='\t')
 
 
 def write(
@@ -72,20 +77,4 @@ def write(
     int
         The number of rows written to the TSV file.
     """
-    rows: list[JSONDict]
-    if isinstance(data, list):
-        rows = [row for row in data if isinstance(row, dict)]
-    else:
-        rows = [data]
-
-    if not rows:
-        return 0
-
-    fieldnames = sorted({key for row in rows for key in row})
-    with path.open('w', encoding='utf-8', newline='') as handle:
-        writer = csv.DictWriter(handle, fieldnames=fieldnames, delimiter='\t')
-        writer.writeheader()
-        for row in rows:
-            writer.writerow({field: row.get(field) for field in fieldnames})
-
-    return len(rows)
+    return write_delimited(path, data, delimiter='\t')

etlplus/file/txt.py

@@ -1,18 +1,27 @@
 """
 :mod:`etlplus.file.txt` module.
 
-Helpers for reading/writing text files.
+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 typing import cast
 
 from ..types import JSONData
-from ..types import JSONDict
 from ..types import JSONList
 from ..utils import count_records
+from ._io import normalize_records
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -77,13 +86,7 @@ def write(
         If any item in ``data`` is not a dictionary or if any dictionary
         does not contain a ``'text'`` key.
     """
-    rows: JSONList
-    if isinstance(data, list):
-        if not all(isinstance(item, dict) for item in data):
-            raise TypeError('TXT payloads must contain only objects (dicts)')
-        rows = cast(JSONList, data)
-    else:
-        rows = [cast(JSONDict, data)]
+    rows = normalize_records(data, 'TXT')
 
     if not rows:
         return 0

etlplus/file/xls.py

@@ -7,12 +7,11 @@ Helpers for reading/writing Excel XLS 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 ._imports import get_pandas
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -23,49 +22,6 @@ __all__ = [
 ]
 
 
-# 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(
-            'XLS 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('XLS payloads must contain only objects (dicts)')
-        return cast(JSONList, data)
-    return [cast(JSONDict, data)]
-
-
 # SECTION: FUNCTIONS ======================================================== #
 
 
@@ -90,7 +46,7 @@ def read(
     ImportError
         If the optional dependency "xlrd" is not installed.
     """
-    pandas = _get_pandas()
+    pandas = get_pandas('XLS')
     try:
         frame = pandas.read_excel(path, engine='xlrd')
     except ImportError as e:  # pragma: no cover
@@ -126,7 +82,7 @@ def write(
 
     Raises
     ------
-    ImportError
-        If the optional dependency "xlwt" is not installed.
+    RuntimeError
+        If XLS writing is attempted.
     """
     raise RuntimeError('XLS write is not supported; use XLSX instead')

etlplus/file/xlsx.py

@@ -7,12 +7,12 @@ 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
+from ._imports import get_pandas
+from ._io import normalize_records
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -23,49 +23,6 @@ __all__ = [
 ]
 
 
-# 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 ======================================================== #
 
 
@@ -90,7 +47,7 @@ def read(
     ImportError
         If optional dependencies for XLSX support are missing.
     """
-    pandas = _get_pandas()
+    pandas = get_pandas('XLSX')
     try:
         frame = pandas.read_excel(path)
     except ImportError as e:  # pragma: no cover
@@ -125,11 +82,11 @@ def write(
     ImportError
         If optional dependencies for XLSX support are missing.
     """
-    records = _normalize_records(data)
+    records = normalize_records(data, 'XLSX')
     if not records:
         return 0
 
-    pandas = _get_pandas()
+    pandas = get_pandas('XLSX')
     path.parent.mkdir(parents=True, exist_ok=True)
     frame = pandas.DataFrame.from_records(records)
     try:

etlplus/file/xml.py

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