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

etlplus/file/yaml.py

@@ -1,19 +1,30 @@
 """
 :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
 
 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 ..utils import count_records
+from ._imports import get_yaml
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -24,43 +35,6 @@ __all__ = [
 ]
 
 
-# SECTION: INTERNAL CONSTANTS =============================================== #
-
-
-# Optional YAML support (lazy-loaded to avoid hard dependency)
-# Cached access function to avoid global statements.
-_YAML_CACHE: dict[str, Any] = {}
-
-
-# SECTION: INTERNAL FUNCTIONS =============================================== #
-
-
-def _get_yaml() -> Any:
-    """
-    Return the PyYAML module, importing it on first use.
-
-    Raises an informative ImportError if the optional dependency is missing.
-    """
-    mod = _YAML_CACHE.get('mod')
-    if mod is not None:  # pragma: no cover - tiny branch
-        return mod
-    try:
-        _yaml_mod = __import__('yaml')  # type: ignore[assignment]
-    except ImportError as e:  # pragma: no cover
-        raise ImportError(
-            'YAML support requires optional dependency "PyYAML".\n'
-            'Install with: pip install PyYAML',
-        ) from e
-    _YAML_CACHE['mod'] = _yaml_mod
-
-    return _yaml_mod
-
-
-def _require_yaml() -> None:
-    """Ensure PyYAML is available or raise an informative error."""
-    _get_yaml()
-
-
 # SECTION: FUNCTIONS ======================================================== #
 
 
@@ -87,10 +61,8 @@ def read(
     TypeError
         If the YAML root is not an object or an array of objects.
     """
-    _require_yaml()
-
     with path.open('r', encoding='utf-8') as handle:
-        loaded = _get_yaml().safe_load(handle)
+        loaded = get_yaml().safe_load(handle)
 
     if isinstance(loaded, dict):
         return cast(JSONDict, loaded)
@@ -124,9 +96,8 @@ def write(
     int
         The number of records written.
     """
-    _require_yaml()
     with path.open('w', encoding='utf-8') as handle:
-        _get_yaml().safe_dump(
+        get_yaml().safe_dump(
             data,
             handle,
             sort_keys=False,

{etlplus-0.12.3.dist-info → etlplus-0.12.10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: etlplus
-Version: 0.12.3
+Version: 0.12.10
 Summary: A Swiss Army knife for simple ETL operations
 Home-page: https://github.com/Dagitali/ETLPlus
 Author: ETLPlus Team
@@ -68,6 +68,19 @@ package and command-line interface for data extraction, validation, transformati
   - [Features](#features)
   - [Installation](#installation)
   - [Quickstart](#quickstart)
+  - [Data Connectors](#data-connectors)
+    - [REST APIs (`api`)](#rest-apis-api)
+    - [Databases (`database`)](#databases-database)
+    - [Files (`file`)](#files-file)
+      - [Stubbed / Placeholder](#stubbed--placeholder)
+      - [Tabular \& Delimited Text](#tabular--delimited-text)
+      - [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)
@@ -191,6 +204,111 @@ assert validate(filtered, rules)["valid"]
 load(filtered, "file", "temp/sample_output.json", file_format="json")
 ```
 
+## Data Connectors
+
+Data connectors abstract sources from which to extract data and targets to which to load data. They
+are differentiated by their types, each of which is represented in the subsections below.
+
+### REST APIs (`api`)
+
+ETLPlus can extract from REST APIs and load results via common HTTP methods. Supported operations
+include GET for extract and PATCH/POST/PUT for load.
+
+### Databases (`database`)
+
+Database connectors use connection strings for extraction and loading, and
+DDL can be rendered from table specs for migrations or schema checks.
+
+### Files (`file`)
+
+File formats are grouped as in `FileFormat`. Support is marked as:
+
+- **Y**: implemented (may require optional dependencies)
+- **N**: stubbed or not yet implemented
+
+#### Stubbed / Placeholder
+
+| Format | Supported | Description |
+| --- | --- | --- |
+| `stub` | N | Placeholder format for tests and future connectors. |
+
+#### Tabular & Delimited Text
+
+| Format | Supported | Description |
+| --- | --- | --- |
+| `csv` | Y | Comma-Separated Values |
+| `fwf` | N | Fixed-Width Fields |
+| `dat` | N | Generic data file, often delimited or fixed-width |
+| `psv` | N | Pipe-Separated Values |
+| `tab` | N | Often synonymous with TSV |
+| `tsv` | Y | Tab-Separated Values |
+| `txt` | Y | Plain text, often delimited or fixed-width |
+
+#### Semi-Structured Text
+
+| 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 |
+
+#### Columnar / Analytics-Friendly
+
+| 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 |
+
+#### Binary Serialization and Interchange
+
+| 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
+
+| Format | Supported | Description |
+| --- | --- | --- |
+| `xls` | Y | Microsoft Excel (BIFF); read-only |
+| `xlsx` | Y | Microsoft Excel (Open XML) |
+
+#### Data Archives
+
+| Format | Supported | Description |
+| --- | --- | --- |
+| `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

{etlplus-0.12.3.dist-info → etlplus-0.12.10.dist-info}/RECORD

@@ -57,24 +57,47 @@ etlplus/database/schema.py,sha256=813C0Dd3WE53KTYot4dgjAxctgKXLXx-8_Rk_4r2e28,70
 etlplus/database/types.py,sha256=_pkQyC14TzAlgyeIqZG4F5LWYknZbHw3TW68Auk7Ya0,795
 etlplus/file/README.md,sha256=avWnyeKfs3uP3qa-DVBJ6t05jS2oFUPeQ3xf1Ph0eC0,3626
 etlplus/file/__init__.py,sha256=X03bosSM-uSd6dh3ur0un6_ozFRw2Tm4PE6kVUjtXK8,475
-etlplus/file/_io.py,sha256=kSbe4Bc9J8br7g856IzBvmKIWSSlng8vo66XN9Z2aiw,2917
-etlplus/file/_pandas.py,sha256=6ZqU7QzEMBq7OFl3mfEtotnKunpS3XV_GGRgz7SIHsI,1282
-etlplus/file/avro.py,sha256=JHK95zrwuHHICRe8f20xfKmeWzv1wP0Br5pOnINdLSc,4621
-etlplus/file/core.py,sha256=BkCliUez8SBEgpagxSeDbJixnX9QvD5XQp0dbYOOw0k,8692
-etlplus/file/csv.py,sha256=gtEUWJO54veEtgaLB_QnmR8yOpeToq78nrtAPVTTl44,1269
-etlplus/file/enums.py,sha256=rwrbwj6PejG0c5v6jzcsmeNu9cSqDyWB1foIuM5UyJo,6648
-etlplus/file/feather.py,sha256=WYZBn2f_Z7KDZZJ1eX0RS-934MnYIMydD0p2Oo30do4,2182
+etlplus/file/_imports.py,sha256=9e8CWjyNIRcmiULEPuwtnJELUOXd4EvVv_vDnDYiB9c,3121
+etlplus/file/_io.py,sha256=GXTcvjfXQX4rSdyu1JNhFmqQJlirDqd8dEGCN3dHvNg,2968
+etlplus/file/accdb.py,sha256=xdBLrXHDonVJ1Z6-qZRrLBXpUwqw5nZYxDuxYMJHzVs,1681
+etlplus/file/arrow.py,sha256=rYPqoCAI3cBHETYN3c0Xi7R5Nq7_prIdyESm3ll3Zos,1694
+etlplus/file/avro.py,sha256=yFQMnWPcvC0CbDCyagoB9SHRIuvl2SXIoQJTBIlw4dA,4437
+etlplus/file/bson.py,sha256=okCWQveCnaRxJ47Oy7-HpByEkiwmiSLSWc0a9eISuVg,1613
+etlplus/file/cbor.py,sha256=hpXTqQ-ei4jYKt6-zq3frDXy-SWRpx1ThQUce6b01xU,1667
+etlplus/file/cfg.py,sha256=sUgbQndKM8vNB7uKRNCaKmJ7Z1KcAVclOnhFP6rqAB8,1726
+etlplus/file/conf.py,sha256=30OsMACauw2gzAo4LN6I0LY0mfnB9OR92GLTOcaH4Mc,1784
+etlplus/file/core.py,sha256=71AFsVwvAP6crsAphMkAmhqTwk_-TkEw9eByG6gwzpA,8862
+etlplus/file/csv.py,sha256=6zXt7OKXm_6k8MrDyw8DdEwpQQrmrxG6myrDplF87_E,1744
+etlplus/file/dat.py,sha256=j-GpY49SmkZtDUzZK6CbrHY9k6N83pyGcMqVGgJZ9cs,1642
+etlplus/file/duckdb.py,sha256=hQ8PWcvYILpkgPEtWeqbT_0yhQpJN9bJh1OwQQCcRD4,1631
+etlplus/file/enums.py,sha256=l7rnwOSf4G27He1y_6Gia3LHLKhnsewlJl7tSlPD_Pw,10924
+etlplus/file/feather.py,sha256=U19T5V_08ooK1STclE9nDvsnUFzu7nvQvi6J09iC-_0,2669
+etlplus/file/fwf.py,sha256=WLbvL94cyLCOYfhABJvoIQc1fljtz3yOuA7X4Fc4QGo,1589
 etlplus/file/gz.py,sha256=NKsvIV7TIWn8USbvuZmRH9hr6OrXh4TzTfDykHD41Kk,2631
-etlplus/file/json.py,sha256=_KAXb4rZ1C8xnaV10IkihuFh1lhbWvajFOlMrBCNVjQ,2099
-etlplus/file/ndjson.py,sha256=gT-kgcqCUUSxtm2j-JMejoh65jk-njMvFwxKCquLZw0,2393
-etlplus/file/orc.py,sha256=GUrq9rgXCLBJ0i8Jd0Xsl4DzldDBg0FDxYhytb4OgxQ,2139
-etlplus/file/parquet.py,sha256=Tp2bi_PAIUdkzc25nArJp7beuUaudw5NdciV6IFHsdQ,2281
-etlplus/file/tsv.py,sha256=NiqF84Ck8e_DinaiO8yKRR6fVUTnUhpThzo4E1QUD8k,1271
-etlplus/file/txt.py,sha256=BStC7crpkGT4qddEeAD1_1mi_2-vQSXLj2DI-ddPFQE,2206
-etlplus/file/xls.py,sha256=83BbBJGxHAdbKH8Imz1l4mOgQT34uo-tyujp2WONRY4,1771
-etlplus/file/xlsx.py,sha256=mBKc3dSci9tk4KjQX3CaODwG1ueGtFAfztNUOaWYQAE,2181
-etlplus/file/xml.py,sha256=rYtCPvyLn9djClN2xKeqRCPsMXnvCH4R8zj94NJRdQc,4018
-etlplus/file/yaml.py,sha256=pWJf0rWyiRpOVOBAwVOosPsdIzuywZ_Cv8_tXLZ6RFw,3183
+etlplus/file/ini.py,sha256=HlvQyQC00oBD8KFBfznPjBx9wF1ZwXH7Yo1JaXqCq8I,1701
+etlplus/file/ion.py,sha256=9q938jROTAcuUT5sRYvS1qIeoz9p8KkVWYDDS2-2A_4,1710
+etlplus/file/json.py,sha256=6EWsOI4RZo366FYsnPp-VkHdgAVBRVUwix-hAJZQM10,2537
+etlplus/file/log.py,sha256=OmsGijXZn1VhN7BUklF8saoktxkmHh1MPLI_BbGDLyc,1681
+etlplus/file/mdb.py,sha256=hSCaxBbc_b9dGTBpR-Gb0UTY2r3zYUxoEiKuwpnx0kI,1657
+etlplus/file/msgpack.py,sha256=9PTitVGnZM0yB2iiwsgLokai6DRmp2l2zfhyjEcajg8,1658
+etlplus/file/ndjson.py,sha256=fSMAAdyucGIVl6zVqylWSBosOg899wgIpIWCGm2HOWU,2432
+etlplus/file/orc.py,sha256=fOO2jQwUr5FHbDve7ztmrE1Mb8uBMQtDo0yp-elVn8Q,2602
+etlplus/file/parquet.py,sha256=nzMrUNQux7Of8Nn0c4d2WYuIJQwZY_xQiO_AuVMCzrI,2758
+etlplus/file/pb.py,sha256=sg72vrjbp7azgEK_oRigmNdSqtEnsrBF24VjOohZhow,1615
+etlplus/file/pbf.py,sha256=lcdehGK_g2drs0VFqTAxZO9-sv65SAkW894ttmlBG8I,1620
+etlplus/file/properties.py,sha256=ZvQ6xiSC71bPH8e5VUt-oITSI1xF99zymoMUgwVur3c,1674
+etlplus/file/proto.py,sha256=QnZMGYHmr6jyiQ08W7hx_MHzNDrPEmMmnbttNRlY4Pg,1668
+etlplus/file/psv.py,sha256=-pfGvLSNOMWVl1mGoKJ_Rh5p5wDyCaxLEd09U23Iub0,1726
+etlplus/file/sqlite.py,sha256=3YRGMB5cRwdZeUVq3J_jSKauad7s8wWHWviqx7yfrUw,1652
+etlplus/file/stub.py,sha256=UPiKD_CYkz66X6bZtSqWX3ShBFrMlf-Se83z4qYnIR4,1733
+etlplus/file/tab.py,sha256=yIbgIM8jkbOmCmewYnDeL4751tHSjVszMIxNlm9C3q8,1984
+etlplus/file/toml.py,sha256=GJ37L3iHwHKksUXCiYz89b490_dwqRVoh3-2bsrSOWI,1642
+etlplus/file/tsv.py,sha256=hKlJd8Q7waZs9_jhRANhmb-fQdPsbvaVG46gYuNVtq0,1766
+etlplus/file/txt.py,sha256=46gSCxPn3SsixtR3RQ-kziaY5cnApHgRbW7UP__9ryE,2313
+etlplus/file/xls.py,sha256=P94lEH8ZMex_G5x1hotidcj-dvGHAnUY7ouzvSYaV7o,1772
+etlplus/file/xlsx.py,sha256=vtiAS8Ng9FV1vCWYTd1YO2ORKIJG3HDfmqy3NkVpt0A,2182
+etlplus/file/xml.py,sha256=p5P60DiV6hyiz-t970d0d0ZXB41gVvAm3MT7dTMULa8,4360
+etlplus/file/yaml.py,sha256=8BEqCELaTQ_nRu1iksLBHVj19P6JmcUf5__fe0yVigw,2449
 etlplus/file/zip.py,sha256=nd26V3S0edklriKnKOGDTLlO8RBXTda_zLLEQrJgKL4,4185
 etlplus/templates/README.md,sha256=kHSZ8FWcrlrcWz0hBIbho-k1Bi-PL-DQ7g02o-g70c8,1355
 etlplus/templates/__init__.py,sha256=tsniN7XJYs3NwYxJ6c2HD5upHP3CDkLx-bQCMt97UOM,106
@@ -83,9 +106,9 @@ etlplus/templates/view.sql.j2,sha256=Iy8DHfhq5yyvrUKDxqp_aHIEXY4Tm6j4wT7YDEFWAhk
 etlplus/validation/README.md,sha256=qusyiyJu2DsaK80jlwfXVZ0iDgeuTPOX2EL3a_fcFiw,1401
 etlplus/validation/__init__.py,sha256=Pe5Xg1_EA4uiNZGYu5WTF3j7odjmyxnAJ8rcioaplSQ,1254
 etlplus/validation/utils.py,sha256=Mtqg449VIke0ziy_wd2r6yrwJzQkA1iulZC87FzXMjo,10201
-etlplus-0.12.3.dist-info/licenses/LICENSE,sha256=MuNO63i6kWmgnV2pbP2SLqP54mk1BGmu7CmbtxMmT-U,1069
-etlplus-0.12.3.dist-info/METADATA,sha256=pOs4RzpaFcMK7DkbD4k6pzh8BW7aPMUbT4rF1gcSKd4,22878
-etlplus-0.12.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-etlplus-0.12.3.dist-info/entry_points.txt,sha256=6w-2-jzuPa55spzK34h-UKh2JTEShh38adFRONNP9QE,45
-etlplus-0.12.3.dist-info/top_level.txt,sha256=aWWF-udn_sLGuHTM6W6MLh99ArS9ROkUWO8Mi8y1_2U,8
-etlplus-0.12.3.dist-info/RECORD,,
+etlplus-0.12.10.dist-info/licenses/LICENSE,sha256=MuNO63i6kWmgnV2pbP2SLqP54mk1BGmu7CmbtxMmT-U,1069
+etlplus-0.12.10.dist-info/METADATA,sha256=Ktx5wLuLA6nVhYLjDVz3OQVog-b_u9FQY4vD3r_lgoQ,26886
+etlplus-0.12.10.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+etlplus-0.12.10.dist-info/entry_points.txt,sha256=6w-2-jzuPa55spzK34h-UKh2JTEShh38adFRONNP9QE,45
+etlplus-0.12.10.dist-info/top_level.txt,sha256=aWWF-udn_sLGuHTM6W6MLh99ArS9ROkUWO8Mi8y1_2U,8
+etlplus-0.12.10.dist-info/RECORD,,

etlplus/file/_pandas.py

@@ -1,58 +0,0 @@
-"""
-:mod:`etlplus.file._pandas` module.
-
-Shared helpers for optional pandas usage.
-"""
-
-from __future__ import annotations
-
-from typing import Any
-
-# SECTION: EXPORTS ========================================================== #
-
-
-__all__ = [
-    'get_pandas',
-]
-
-# SECTION: INTERNAL CONSTANTS =============================================== #
-
-
-_PANDAS_CACHE: dict[str, Any] = {}
-
-
-# SECTION: FUNCTIONS ======================================================== #
-
-
-def get_pandas(format_name: str) -> Any:
-    """
-    Return the pandas module, importing it on first use.
-
-    Parameters
-    ----------
-    format_name : str
-        Human-readable format name for error messages.
-
-    Returns
-    -------
-    Any
-        The pandas module.
-
-    Raises
-    ------
-    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(
-            f'{format_name} support requires optional dependency "pandas".\n'
-            'Install with: pip install pandas',
-        ) from e
-    _PANDAS_CACHE['mod'] = _pd
-
-    return _pd