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

etlplus/file/sas7bdat.py

@@ -0,0 +1,78 @@
+"""
+:mod:`etlplus.file.sas7bdat` module.
+
+Helpers for reading/writing SAS (SAS7BDAT) data files.
+
+Notes
+-----
+- A SAS7BDAT file is a binary file format used by SAS to store datasets,
+    including variables, labels, and data types.
+- Common cases:
+    - Delimited text files (e.g., CSV, TSV).
+    - Fixed-width formatted files.
+    - Custom formats specific to certain applications.
+- Rule of thumb:
+    - If the file does not follow a specific standard format, 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 DAT content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the SAS7BDAT file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the SAS7BDAT file.
+    """
+    return stub.read(path, format_name='SAS7BDAT')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to SAS7BDAT file at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the SAS7BDAT file on disk.
+    data : JSONData
+        Data to write as SAS7BDAT file. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the SAS7BDAT file.
+    """
+    return stub.write(path, data, format_name='SAS7BDAT')

etlplus/file/sav.py

@@ -0,0 +1,77 @@
+"""
+:mod:`etlplus.file.sav` module.
+
+Helpers for reading/writing SPSS (SAV) data files.
+
+Notes
+-----
+- A SAV file is a binary file format used by SPSS to store datasets, including
+    variables, labels, and data types.
+- Common cases:
+    - Reading data for analysis in Python.
+    - Writing processed data back to SPSS format.
+- Rule of thumb:
+    - If you need to work with SPSS data 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 SAV content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the SAV file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the SAV file.
+    """
+    return stub.read(path, format_name='SAV')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to SAV file at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the SAV file on disk.
+    data : JSONData
+        Data to write as SAV file. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the SAV file.
+    """
+    return stub.write(path, data, format_name='SAV')

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/sylk.py

@@ -0,0 +1,77 @@
+"""
+:mod:`etlplus.file.sylk` module.
+
+Helpers for reading/writing Symbolic Link (SYLK) data files.
+
+Notes
+-----
+- A SYLK file is a text-based file format used to represent spreadsheet
+    data, including cell values, formulas, and formatting.
+- Common cases:
+    - Storing spreadsheet data in a human-readable format.
+    - Exchanging data between different spreadsheet applications.
+- Rule of thumb:
+    - If you need to work with SYLK 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 SYLK content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the SYLK file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the SYLK file.
+    """
+    return stub.read(path, format_name='SYLK')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to SYLK file at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the SYLK file on disk.
+    data : JSONData
+        Data to write as SYLK file. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the SYLK file.
+    """
+    return stub.write(path, data, format_name='SYLK')

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 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

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