etlplus 0.12.9__py3-none-any.whl → 0.12.11__py3-none-any.whl

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

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

etlplus/file/txt.py

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

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

etlplus/file/xpt.py

@@ -0,0 +1,78 @@
+"""
+:mod:`etlplus.file.xpt` module.
+
+Helpers for reading/writing SAS Transport (XPT) files.
+
+Notes
+-----
+- A SAS Transport (XPT) file is a standardized file format used to transfer
+    SAS datasets between different systems.
+- Common cases:
+    - Sharing datasets between different SAS installations.
+    - Archiving datasets in a platform-independent format.
+    - Importing/exporting data to/from statistical software that supports XPT.
+- Rule of thumb:
+    - If you need to work with XPT 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 XPT content from ``path``.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the XPT file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the XPT file.
+    """
+    return stub.read(path, format_name='XPT')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write ``data`` to XPT file at ``path`` and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the XPT file on disk.
+    data : JSONData
+        Data to write as XPT file. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the XPT file.
+    """
+    return stub.write(path, data, format_name='XPT')

etlplus/file/yaml.py

@@ -1,7 +1,18 @@
 """
 :mod:`etlplus.file.yaml` module.
 
-Helpers for reading/writing YAML files.
+Helpers for reading/writing YAML Ain't Markup Language (YAML) files.
+
+Notes
+-----
+- A YAML file is a human-readable data serialization format.
+- Common cases:
+    - Configuration files.
+    - Data exchange between languages with different data structures.
+    - Complex data storage.
+- Rule of thumb:
+    - If the file follows the YAML specification, use this module for
+        reading and writing.
 """
 
 from __future__ import annotations

etlplus/file/zsav.py

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

{etlplus-0.12.9.dist-info → etlplus-0.12.11.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: etlplus
-Version: 0.12.9
+Version: 0.12.11
 Summary: A Swiss Army knife for simple ETL operations
 Home-page: https://github.com/Dagitali/ETLPlus
 Author: ETLPlus Team
@@ -77,8 +77,10 @@ package and command-line interface for data extraction, validation, transformati
       - [Semi-Structured Text](#semi-structured-text)
       - [Columnar / Analytics-Friendly](#columnar--analytics-friendly)
       - [Binary Serialization and Interchange](#binary-serialization-and-interchange)
+      - [Databases and Embedded Storage](#databases-and-embedded-storage)
       - [Spreadsheets](#spreadsheets)
       - [Data Archives](#data-archives)
+      - [Logs and Event Streams](#logs-and-event-streams)
   - [Usage](#usage)
     - [Command Line Interface](#command-line-interface)
       - [Argument Order and Required Options](#argument-order-and-required-options)
@@ -246,8 +248,13 @@ File formats are grouped as in `FileFormat`. Support is marked as:
 
 | Format | Supported | Description |
 | --- | --- | --- |
+| `cfg` | N | Config-style key-value pairs |
+| `conf` | N | Config-style key-value pairs |
+| `ini` | N | Config-style key-value pairs |
 | `json` | Y | JavaScript Object Notation |
 | `ndjson` | Y | Newline-Delimited JSON |
+| `properties` | N | Java-style key-value pairs |
+| `toml` | N | Tom's Obvious Minimal Language |
 | `xml` | Y | Extensible Markup Language |
 | `yaml` | Y | YAML Ain't Markup Language |
 
@@ -255,6 +262,7 @@ File formats are grouped as in `FileFormat`. Support is marked as:
 
 | Format | Supported | Description |
 | --- | --- | --- |
+| `arrow` | N | Apache Arrow IPC |
 | `feather` | Y | Apache Arrow Feather |
 | `orc` | Y | Optimized Row Columnar; common in Hadoop |
 | `parquet` | Y | Apache Parquet; common in Big Data |
@@ -264,6 +272,22 @@ File formats are grouped as in `FileFormat`. Support is marked as:
 | Format | Supported | Description |
 | --- | --- | --- |
 | `avro` | Y | Apache Avro |
+| `bson` | N | Binary JSON; common with MongoDB exports/dumps |
+| `cbor` | N | Concise Binary Object Representation |
+| `ion` | N | Amazon Ion |
+| `msgpack` | N | MessagePack |
+| `pb` | N | Protocol Buffers (Google Protobuf) |
+| `pbf` | N | Protocolbuffer Binary Format; often for GIS data |
+| `proto` | N | Protocol Buffers schema; often in .pb / .bin |
+
+#### Databases and Embedded Storage
+
+| Format | Supported | Description |
+| --- | --- | --- |
+| `accdb` | N | Microsoft Access database file (newer format) |
+| `duckdb` | N | DuckDB database file |
+| `mdb` | N | Microsoft Access database file (older format) |
+| `sqlite` | N | SQLite database file |
 
 #### Spreadsheets
 
@@ -279,6 +303,12 @@ File formats are grouped as in `FileFormat`. Support is marked as:
 | `gz` | Y | Gzip-compressed file |
 | `zip` | Y | ZIP archive |
 
+#### Logs and Event Streams
+
+| Format | Supported | Description |
+| --- | --- | --- |
+| `log` | N | Generic log file |
+
 ## Usage
 
 ### Command Line Interface