etlplus 0.11.11__py3-none-any.whl → 0.12.3__py3-none-any.whl

etlplus/file/parquet.py

@@ -1,21 +1,36 @@
 """
 :mod:`etlplus.file.parquet` module.
 
-Stub helpers for PARQUET read/write.
+Helpers for reading/writing Parquet files.
 """
 
 from __future__ import annotations
 
 from pathlib import Path
+from typing import cast
 
 from ..types import JSONData
+from ..types import JSONList
+from ._io import normalize_records
+from ._pandas import get_pandas
 
 # SECTION: EXPORTS ========================================================== #
 
 
-def read(path: Path) -> JSONData:
+__all__ = [
+    'read',
+    'write',
+]
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def read(
+    path: Path,
+) -> JSONList:
     """
-    Read PARQUET content from ``path``.
+    Read Parquet content from ``path``.
 
     Parameters
     ----------
@@ -24,20 +39,32 @@ def read(path: Path) -> JSONData:
 
     Returns
     -------
-    JSONData
-        Parsed payload.
+    JSONList
+        The list of dictionaries read from the Parquet file.
 
     Raises
     ------
-    NotImplementedError
-        PARQUET :func:`read` is not implemented yet.
+    ImportError
+        If optional dependencies for Parquet support are missing.
     """
-    raise NotImplementedError('PARQUET read is not implemented yet')
+    pandas = get_pandas('Parquet')
+    try:
+        frame = pandas.read_parquet(path)
+    except ImportError as e:  # pragma: no cover
+        raise ImportError(
+            'Parquet support requires optional dependency '
+            '"pyarrow" or "fastparquet".\n'
+            'Install with: pip install pyarrow',
+        ) from e
+    return cast(JSONList, frame.to_dict(orient='records'))
 
 
-def write(path: Path, data: JSONData) -> int:
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
     """
-    Write ``data`` to PARQUET at ``path``.
+    Write ``data`` to Parquet at ``path`` and return record count.
 
     Parameters
     ----------
@@ -53,7 +80,22 @@ def write(path: Path, data: JSONData) -> int:
 
     Raises
     ------
-    NotImplementedError
-        PARQUET :func:`write` is not implemented yet.
+    ImportError
+        If optional dependencies for Parquet support are missing.
     """
-    raise NotImplementedError('PARQUET write is not implemented yet')
+    records = normalize_records(data, 'Parquet')
+    if not records:
+        return 0
+
+    pandas = get_pandas('Parquet')
+    path.parent.mkdir(parents=True, exist_ok=True)
+    frame = pandas.DataFrame.from_records(records)
+    try:
+        frame.to_parquet(path, index=False)
+    except ImportError as e:  # pragma: no cover
+        raise ImportError(
+            'Parquet support requires optional dependency '
+            '"pyarrow" or "fastparquet".\n'
+            'Install with: pip install pyarrow',
+        ) from e
+    return len(records)

etlplus/file/tsv.py

@@ -1,7 +1,7 @@
 """
 :mod:`etlplus.file.tsv` module.
 
-Stub helpers for TSV read/write.
+Helpers for reading/writing TSV files.
 """
 
 from __future__ import annotations
@@ -9,11 +9,25 @@ 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 ========================================================== #
 
 
-def read(path: Path) -> JSONData:
+__all__ = [
+    'read',
+    'write',
+]
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def read(
+    path: Path,
+) -> JSONList:
     """
     Read TSV content from ``path``.
 
@@ -24,36 +38,30 @@ def read(path: Path) -> JSONData:
 
     Returns
     -------
-    JSONData
-        Parsed payload.
-
-    Raises
-    ------
-    NotImplementedError
-        TSV :func:`read` is not implemented yet.
+    JSONList
+        The list of dictionaries read from the TSV file.
     """
-    raise NotImplementedError('TSV read is not implemented yet')
+    return read_delimited(path, delimiter='\t')
 
 
-def write(path: Path, data: JSONData) -> int:
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
     """
-    Write ``data`` to TSV at ``path``.
+    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.
+        Data to write as TSV. Should be a list of dictionaries or a
+        single dictionary.
 
     Returns
     -------
     int
-        Number of records written.
-
-    Raises
-    ------
-    NotImplementedError
-        TSV :func:`write` is not implemented yet.
+        The number of rows written to the TSV file.
     """
-    raise NotImplementedError('TSV write is not implemented yet')
+    return write_delimited(path, data, delimiter='\t')

etlplus/file/txt.py

@@ -1,19 +1,34 @@
 """
 :mod:`etlplus.file.txt` module.
 
-Stub helpers for TXT read/write.
+Helpers for reading/writing text files.
 """
 
 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
 
 # SECTION: EXPORTS ========================================================== #
 
 
-def read(path: Path) -> JSONData:
+__all__ = [
+    'read',
+    'write',
+]
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def read(
+    path: Path,
+) -> JSONList:
     """
     Read TXT content from ``path``.
 
@@ -24,27 +39,32 @@ def read(path: Path) -> JSONData:
 
     Returns
     -------
-    JSONData
-        Parsed payload.
-
-    Raises
-    ------
-    NotImplementedError
-        TXT :func:`read` is not implemented yet.
+    JSONList
+        The list of dictionaries read from the TXT file.
     """
-    raise NotImplementedError('TXT read is not implemented yet')
+    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:
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
     """
-    Write ``data`` to TXT at ``path``.
+    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.
+        Data to write. Expects ``{'text': '...'} `` or a list of those.
 
     Returns
     -------
@@ -53,7 +73,27 @@ def write(path: Path, data: JSONData) -> int:
 
     Raises
     ------
-    NotImplementedError
-        TXT :func:`write` is not implemented yet.
+    TypeError
+        If any item in ``data`` is not a dictionary or if any dictionary
+        does not contain a ``'text'`` key.
     """
-    raise NotImplementedError('TXT write is not implemented yet')
+    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)]
+
+    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/xls.py

@@ -1,19 +1,33 @@
 """
 :mod:`etlplus.file.xls` module.
 
-Stub helpers for XLS read/write.
+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 ._pandas import get_pandas
 
 # SECTION: EXPORTS ========================================================== #
 
 
-def read(path: Path) -> JSONData:
+__all__ = [
+    'read',
+    'write',
+]
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def read(
+    path: Path,
+) -> JSONList:
     """
     Read XLS content from ``path``.
 
@@ -24,20 +38,35 @@ def read(path: Path) -> JSONData:
 
     Returns
     -------
-    JSONData
-        Parsed payload.
+    JSONList
+        The list of dictionaries read from the XLS file.
 
     Raises
     ------
-    NotImplementedError
-        XLS :func:`read` is not implemented yet.
+    ImportError
+        If the optional dependency "xlrd" is not installed.
     """
-    raise NotImplementedError('XLS read is not implemented yet')
+    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:
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
     """
-    Write ``data`` to XLS at ``path``.
+    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
     ----------
@@ -53,7 +82,7 @@ def write(path: Path, data: JSONData) -> int:
 
     Raises
     ------
-    NotImplementedError
-        XLS :func:`write` is not implemented yet.
+    RuntimeError
+        If XLS writing is attempted.
     """
-    raise NotImplementedError('XLS write is not implemented yet')
+    raise RuntimeError('XLS write is not supported; use XLSX instead')

etlplus/file/xlsx.py

@@ -1,19 +1,34 @@
 """
 :mod:`etlplus.file.xlsx` module.
 
-Stub helpers for XLSX read/write.
+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 ._io import normalize_records
+from ._pandas import get_pandas
 
 # SECTION: EXPORTS ========================================================== #
 
 
-def read(path: Path) -> JSONData:
+__all__ = [
+    'read',
+    'write',
+]
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def read(
+    path: Path,
+) -> JSONList:
     """
     Read XLSX content from ``path``.
 
@@ -24,20 +39,31 @@ def read(path: Path) -> JSONData:
 
     Returns
     -------
-    JSONData
-        Parsed payload.
+    JSONList
+        The list of dictionaries read from the XLSX file.
 
     Raises
     ------
-    NotImplementedError
-        XLSX :func:`read` is not implemented yet.
+    ImportError
+        If optional dependencies for XLSX support are missing.
     """
-    raise NotImplementedError('XLSX read is not implemented yet')
+    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:
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
     """
-    Write ``data`` to XLSX at ``path``.
+    Write ``data`` to XLSX at ``path`` and return record count.
 
     Parameters
     ----------
@@ -53,7 +79,21 @@ def write(path: Path, data: JSONData) -> int:
 
     Raises
     ------
-    NotImplementedError
-        XLSX :func:`write` is not implemented yet.
+    ImportError
+        If optional dependencies for XLSX support are missing.
     """
-    raise NotImplementedError('XLSX write is not implemented yet')
+    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

@@ -1,7 +1,7 @@
 """
 :mod:`etlplus.file.xml` module.
 
-XML read/write helpers.
+Helpers for reading/writing XML files.
 """
 
 from __future__ import annotations
@@ -14,6 +14,15 @@ from ..types import JSONData
 from ..types import JSONDict
 from ..utils import count_records
 
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    'read',
+    'write',
+]
+
+
 # SECTION: CONSTANTS ======================================================== #
 
 
@@ -117,7 +126,7 @@ def read(
     path: Path,
 ) -> JSONDict:
     """
-    Parse XML document at ``path`` into a nested dictionary.
+    Read XML content from ``path``.
 
     Parameters
     ----------
@@ -137,7 +146,7 @@ def read(
 
 def write(path: Path, data: JSONData, *, root_tag: str) -> int:
     """
-    Write ``data`` as XML to ``path`` and return record count.
+    Write ``data`` to XML at ``path`` and return record count.
 
     Parameters
     ----------

etlplus/file/yaml.py

@@ -1,7 +1,7 @@
 """
 :mod:`etlplus.file.yaml` module.
 
-Optional YAML read/write helpers.
+Helpers for reading/writing YAML files.
 """
 
 from __future__ import annotations
@@ -15,6 +15,15 @@ from ..types import JSONDict
 from ..types import JSONList
 from ..utils import count_records
 
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    'read',
+    'write',
+]
+
+
 # SECTION: INTERNAL CONSTANTS =============================================== #
 
 
@@ -59,7 +68,9 @@ def read(
     path: Path,
 ) -> JSONData:
     """
-    Load and validate YAML payloads from ``path``.
+    Read YAML content from ``path``.
+
+    Validates that the YAML root is a dict or a list of dicts.
 
     Parameters
     ----------