etlplus 0.16.9__tar.gz → 0.17.2__tar.gz

{etlplus-0.16.9 → etlplus-0.17.2}/.github/workflows/ci.yml

@@ -62,7 +62,11 @@ jobs:
         run: |
           ruff version
           ruff check .
-          ruff format --check .
+          # ruff format --check .
+          files="$(git ls-files '*.py')"
+          if [ -n "$files" ]; then
+            autopep8 --diff --exit-code --max-line-length=79 $files
+          fi
 
   test:
     runs-on: ubuntu-latest

{etlplus-0.16.9 → etlplus-0.17.2}/.ruff.toml

@@ -19,6 +19,10 @@ select = [
   "I",   # isort
   "UP",  # pyupgrade
 ]
+preview = true
+extend-select = [
+  "E203",  # Enforce autopep8 slice spacing (no space before ':')
+]
 ignore = [
   # Allow module-level variable use for caches/helpers, if needed
 ]

{etlplus-0.16.9 → etlplus-0.17.2}/Makefile

@@ -172,6 +172,11 @@ dist: ## Build sdist and wheel into ./dist using pyproject.toml
 	@$(PYTHON) -m twine check dist/*
 	@$(call ECHO_OK,"Built and validated distribution artifacts in ./dist")
 
+.PHONY: file
+file: venv ## Install package + file extras
+	@$(PYTHON) -m pip install -e $(PKG_DIR)[file]
+	@$(call ECHO_OK,"Installed etlplus + file extras")
+
 .PHONY: fix
 fix: ## Auto-fix with ruff
 	@$(VENV_BIN)/ruff check . --fix || (echo "Hint: run 'make dev' first" && false)
@@ -211,8 +216,11 @@ doclint: ## Run docstring linters (pydocstyle + pydoclint if available)
 .PHONY: fmt
 fmt: ## Format code with ruff (imports + fixes) and black
 	@$(VENV_BIN)/ruff check . --fix || (echo "Hint: run 'make dev' first" && false)
-	@$(VENV_BIN)/ruff format . || true
-	@$(VENV_BIN)/black . || true
+# 	@$(VENV_BIN)/ruff format . || true
+# 	@$(VENV_BIN)/black . || true
+	@$(VENV_BIN)/autopep8 --in-place --max-line-length=79 \
+	  --exclude .venv,dist,build,etlplus.egg-info,.mypy_cache,.pytest_cache \
+	  $(shell git ls-files '*.py') || true
 
 .PHONY: run
 run: ## Run the etlplus CLI (dry-run) using $(ENV)

{etlplus-0.16.9/etlplus.egg-info → etlplus-0.17.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: etlplus
-Version: 0.16.9
+Version: 0.17.2
 Summary: A Swiss Army knife for simple ETL operations
 Home-page: https://github.com/Dagitali/ETLPlus
 Author: ETLPlus Team
@@ -32,6 +32,7 @@ Requires-Dist: typer>=0.21.0
 Requires-Dist: xlrd>=2.0.2
 Requires-Dist: xlwt>=1.3.0
 Provides-Extra: dev
+Requires-Dist: autopep8>=2.3.2; extra == "dev"
 Requires-Dist: black>=25.9.0; extra == "dev"
 Requires-Dist: build>=1.2.2; extra == "dev"
 Requires-Dist: flake8>=7.3.0; extra == "dev"
@@ -44,6 +45,17 @@ Requires-Dist: ruff>=0.14.4; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: sphinx>=4.0.0; extra == "docs"
 Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
+Provides-Extra: file
+Requires-Dist: pymongo>=4.9.1; extra == "file"
+Requires-Dist: cbor2>=5.6.4; extra == "file"
+Requires-Dist: duckdb>=1.1.0; extra == "file"
+Requires-Dist: msgpack>=1.0.8; extra == "file"
+Requires-Dist: netCDF4>=1.7.2; extra == "file"
+Requires-Dist: odfpy>=1.4.1; extra == "file"
+Requires-Dist: pyreadr>=0.5.2; extra == "file"
+Requires-Dist: pyreadstat>=1.3.3; extra == "file"
+Requires-Dist: tomli-w>=1.2.0; extra == "file"
+Requires-Dist: xarray>=2024.9.0; extra == "file"
 Dynamic: home-page
 Dynamic: license-file
 Dynamic: requires-python
@@ -176,6 +188,12 @@ For development:
 pip install -e ".[dev]"
 ```
 
+For full file-format support (optional extras):
+
+```bash
+pip install -e ".[file]"
+```
+
 ## Quickstart
 
 Get up and running in under a minute.
@@ -240,10 +258,10 @@ Recognized file formats are listed in the tables below. Support for reading to o
 | Format | Read | Write | Description |
 | --- | --- | --- | --- |
 | `csv` | Y | Y | Comma-Separated Values |
-| `dat` | N | N | Generic data file, often delimited or fixed-width |
-| `fwf` | N | N | Fixed-Width Fields |
-| `psv` | N | N | Pipe-Separated Values |
-| `tab` | N | N | Often synonymous with TSV |
+| `dat` | Y | Y | Generic data file, often delimited or fixed-width |
+| `fwf` | Y | Y | Fixed-Width Fields |
+| `psv` | Y | Y | Pipe-Separated Values |
+| `tab` | Y | Y | Often synonymous with TSV |
 | `tsv` | Y | Y | Tab-Separated Values |
 | `txt` | Y | Y | Plain text, often delimited or fixed-width |
 
@@ -253,11 +271,11 @@ Recognized file formats are listed in the tables below. Support for reading to o
 | --- | --- | --- | --- |
 | `cfg` | N | N | Config-style key-value pairs |
 | `conf` | N | N | Config-style key-value pairs |
-| `ini` | N | N | Config-style key-value pairs |
+| `ini` | Y | Y | Config-style key-value pairs |
 | `json` | Y | Y | JavaScript Object Notation |
 | `ndjson` | Y | Y | Newline-Delimited JSON |
-| `properties` | N | N | Java-style key-value pairs |
-| `toml` | N | N | Tom's Obvious Minimal Language |
+| `properties` | Y | Y | Java-style key-value pairs |
+| `toml` | Y | Y | Tom's Obvious Minimal Language |
 | `xml` | Y | Y | Extensible Markup Language |
 | `yaml` | Y | Y | YAML Ain't Markup Language |
 
@@ -265,7 +283,7 @@ Recognized file formats are listed in the tables below. Support for reading to o
 
 | Format | Read | Write | Description |
 | --- | --- | --- | --- |
-| `arrow` | N | N | Apache Arrow IPC |
+| `arrow` | Y | Y | Apache Arrow IPC |
 | `feather` | Y | Y | Apache Arrow Feather |
 | `orc` | Y | Y | Optimized Row Columnar; common in Hadoop |
 | `parquet` | Y | Y | Apache Parquet; common in Big Data |
@@ -275,48 +293,48 @@ Recognized file formats are listed in the tables below. Support for reading to o
 | Format | Read | Write | Description |
 | --- | --- | --- | --- |
 | `avro` | Y | Y | Apache Avro |
-| `bson` | N | N | Binary JSON; common with MongoDB exports/dumps |
-| `cbor` | N | N | Concise Binary Object Representation |
+| `bson` | Y | Y | Binary JSON; common with MongoDB exports/dumps |
+| `cbor` | Y | Y | Concise Binary Object Representation |
 | `ion` | N | N | Amazon Ion |
-| `msgpack` | N | N | MessagePack |
-| `pb` | N | N | Protocol Buffers (Google Protobuf) |
+| `msgpack` | Y | Y | MessagePack |
+| `pb` | Y | Y | Protocol Buffers (Google Protobuf) |
 | `pbf` | N | N | Protocolbuffer Binary Format; often for GIS data |
-| `proto` | N | N | Protocol Buffers schema; often in .pb / .bin |
+| `proto` | Y | Y | Protocol Buffers schema; often in .pb / .bin |
 
 #### Databases and Embedded Storage
 
 | Format | Read | Write | Description |
 | --- | --- | --- | --- |
 | `accdb` | N | N | Microsoft Access (newer format) |
-| `duckdb` | N | N | DuckDB |
+| `duckdb` | Y | Y | DuckDB |
 | `mdb` | N | N | Microsoft Access (older format) |
-| `sqlite` | N | N | SQLite |
+| `sqlite` | Y | Y | SQLite |
 
 #### Spreadsheets
 
 | Format | Read | Write | Description |
 | --- | --- | --- | --- |
 | `numbers` | N | N | Apple Numbers |
-| `ods` | N | N | OpenDocument |
+| `ods` | Y | Y | OpenDocument |
 | `wks` | N | N | Lotus 1-2-3  |
 | `xls` | Y | N | Microsoft Excel (BIFF; read-only) |
-| `xlsm` | N | N | Microsoft Excel Macro-Enabled (Open XML) |
+| `xlsm` | Y | Y | Microsoft Excel Macro-Enabled (Open XML) |
 | `xlsx` | Y | Y | Microsoft Excel (Open XML) |
 
 #### Statistical / Scientific / Numeric Computing
 
 | Format | Read | Write | Description |
 | --- | --- | --- | --- |
-| `dta` | N | N | Stata |
-| `hdf5` | N | N | Hierarchical Data Format |
+| `dta` | Y | Y | Stata |
+| `hdf5` | Y | N | Hierarchical Data Format |
 | `mat` | N | N | MATLAB |
-| `nc` | N | N | NetCDF |
-| `rda` | N | N | RData workspace/object |
-| `rds` | N | N | R data |
-| `sas7bdat` | N | N | SAS data |
-| `sav` | N | N | SPSS data |
+| `nc` | Y | Y | NetCDF |
+| `rda` | Y | Y | RData workspace/object |
+| `rds` | Y | Y | R data |
+| `sas7bdat` | Y | N | SAS data |
+| `sav` | Y | Y | SPSS data |
 | `sylk` | N | N | Symbolic Link |
-| `xpt` | N | N | SAS Transport |
+| `xpt` | Y | Y | SAS Transport |
 | `zsav` | N | N | Compressed SPSS data |
 
 #### Logs and Event Streams

{etlplus-0.16.9 → etlplus-0.17.2}/README.md

@@ -126,6 +126,12 @@ For development:
 pip install -e ".[dev]"
 ```
 
+For full file-format support (optional extras):
+
+```bash
+pip install -e ".[file]"
+```
+
 ## Quickstart
 
 Get up and running in under a minute.
@@ -190,10 +196,10 @@ Recognized file formats are listed in the tables below. Support for reading to o
 | Format | Read | Write | Description |
 | --- | --- | --- | --- |
 | `csv` | Y | Y | Comma-Separated Values |
-| `dat` | N | N | Generic data file, often delimited or fixed-width |
-| `fwf` | N | N | Fixed-Width Fields |
-| `psv` | N | N | Pipe-Separated Values |
-| `tab` | N | N | Often synonymous with TSV |
+| `dat` | Y | Y | Generic data file, often delimited or fixed-width |
+| `fwf` | Y | Y | Fixed-Width Fields |
+| `psv` | Y | Y | Pipe-Separated Values |
+| `tab` | Y | Y | Often synonymous with TSV |
 | `tsv` | Y | Y | Tab-Separated Values |
 | `txt` | Y | Y | Plain text, often delimited or fixed-width |
 
@@ -203,11 +209,11 @@ Recognized file formats are listed in the tables below. Support for reading to o
 | --- | --- | --- | --- |
 | `cfg` | N | N | Config-style key-value pairs |
 | `conf` | N | N | Config-style key-value pairs |
-| `ini` | N | N | Config-style key-value pairs |
+| `ini` | Y | Y | Config-style key-value pairs |
 | `json` | Y | Y | JavaScript Object Notation |
 | `ndjson` | Y | Y | Newline-Delimited JSON |
-| `properties` | N | N | Java-style key-value pairs |
-| `toml` | N | N | Tom's Obvious Minimal Language |
+| `properties` | Y | Y | Java-style key-value pairs |
+| `toml` | Y | Y | Tom's Obvious Minimal Language |
 | `xml` | Y | Y | Extensible Markup Language |
 | `yaml` | Y | Y | YAML Ain't Markup Language |
 
@@ -215,7 +221,7 @@ Recognized file formats are listed in the tables below. Support for reading to o
 
 | Format | Read | Write | Description |
 | --- | --- | --- | --- |
-| `arrow` | N | N | Apache Arrow IPC |
+| `arrow` | Y | Y | Apache Arrow IPC |
 | `feather` | Y | Y | Apache Arrow Feather |
 | `orc` | Y | Y | Optimized Row Columnar; common in Hadoop |
 | `parquet` | Y | Y | Apache Parquet; common in Big Data |
@@ -225,48 +231,48 @@ Recognized file formats are listed in the tables below. Support for reading to o
 | Format | Read | Write | Description |
 | --- | --- | --- | --- |
 | `avro` | Y | Y | Apache Avro |
-| `bson` | N | N | Binary JSON; common with MongoDB exports/dumps |
-| `cbor` | N | N | Concise Binary Object Representation |
+| `bson` | Y | Y | Binary JSON; common with MongoDB exports/dumps |
+| `cbor` | Y | Y | Concise Binary Object Representation |
 | `ion` | N | N | Amazon Ion |
-| `msgpack` | N | N | MessagePack |
-| `pb` | N | N | Protocol Buffers (Google Protobuf) |
+| `msgpack` | Y | Y | MessagePack |
+| `pb` | Y | Y | Protocol Buffers (Google Protobuf) |
 | `pbf` | N | N | Protocolbuffer Binary Format; often for GIS data |
-| `proto` | N | N | Protocol Buffers schema; often in .pb / .bin |
+| `proto` | Y | Y | Protocol Buffers schema; often in .pb / .bin |
 
 #### Databases and Embedded Storage
 
 | Format | Read | Write | Description |
 | --- | --- | --- | --- |
 | `accdb` | N | N | Microsoft Access (newer format) |
-| `duckdb` | N | N | DuckDB |
+| `duckdb` | Y | Y | DuckDB |
 | `mdb` | N | N | Microsoft Access (older format) |
-| `sqlite` | N | N | SQLite |
+| `sqlite` | Y | Y | SQLite |
 
 #### Spreadsheets
 
 | Format | Read | Write | Description |
 | --- | --- | --- | --- |
 | `numbers` | N | N | Apple Numbers |
-| `ods` | N | N | OpenDocument |
+| `ods` | Y | Y | OpenDocument |
 | `wks` | N | N | Lotus 1-2-3  |
 | `xls` | Y | N | Microsoft Excel (BIFF; read-only) |
-| `xlsm` | N | N | Microsoft Excel Macro-Enabled (Open XML) |
+| `xlsm` | Y | Y | Microsoft Excel Macro-Enabled (Open XML) |
 | `xlsx` | Y | Y | Microsoft Excel (Open XML) |
 
 #### Statistical / Scientific / Numeric Computing
 
 | Format | Read | Write | Description |
 | --- | --- | --- | --- |
-| `dta` | N | N | Stata |
-| `hdf5` | N | N | Hierarchical Data Format |
+| `dta` | Y | Y | Stata |
+| `hdf5` | Y | N | Hierarchical Data Format |
 | `mat` | N | N | MATLAB |
-| `nc` | N | N | NetCDF |
-| `rda` | N | N | RData workspace/object |
-| `rds` | N | N | R data |
-| `sas7bdat` | N | N | SAS data |
-| `sav` | N | N | SPSS data |
+| `nc` | Y | Y | NetCDF |
+| `rda` | Y | Y | RData workspace/object |
+| `rds` | Y | Y | R data |
+| `sas7bdat` | Y | N | SAS data |
+| `sav` | Y | Y | SPSS data |
 | `sylk` | N | N | Symbolic Link |
-| `xpt` | N | N | SAS Transport |
+| `xpt` | Y | Y | SAS Transport |
 | `zsav` | N | N | Compressed SPSS data |
 
 #### Logs and Event Streams

{etlplus-0.16.9 → etlplus-0.17.2}/etlplus/file/README.md

@@ -9,6 +9,12 @@ and writing data files.
   types
 - Exposes a `File` class with instance methods for reading and writing data
 
+Some formats require optional dependencies. Install with:
+
+```bash
+pip install -e ".[file]"
+```
+
 Back to project overview: see the top-level [README](../../README.md).
 
 - [`etlplus.file` Subpackage](#etlplusfile-subpackage)
@@ -29,21 +35,48 @@ matrix across all `FileFormat` values, see the top-level [README](../../README.m
 | Format    | Description                                 |
 |-----------|---------------------------------------------|
 | avro      | Apache Avro binary serialization            |
+| arrow     | Apache Arrow IPC                            |
+| bson      | Binary JSON (BSON)                          |
+| cbor      | Concise Binary Object Representation        |
 | csv       | Comma-separated values text files           |
+| dat       | Generic data files (delimited)              |
+| dta       | Stata datasets                              |
+| duckdb    | DuckDB database file                        |
 | feather   | Apache Arrow Feather columnar format        |
+| fwf       | Fixed-width formatted text files            |
 | gz        | Gzip-compressed files (see Compression)     |
+| hdf5      | Hierarchical Data Format                    |
+| ini       | INI config files                            |
 | json      | Standard JSON files                         |
+| msgpack   | MessagePack binary serialization            |
+| nc        | NetCDF datasets                             |
 | ndjson    | Newline-delimited JSON (JSON Lines)         |
+| ods       | OpenDocument spreadsheets                   |
 | orc       | Apache ORC columnar format                  |
 | parquet   | Apache Parquet columnar format              |
+| pb        | Protocol Buffers binary                     |
+| properties | Java-style properties                     |
+| proto     | Protocol Buffers schema                     |
+| psv       | Pipe-separated values text files            |
+| rda       | RData workspace bundles                     |
+| rds       | RDS datasets                                |
+| sas7bdat  | SAS datasets                                |
+| sav       | SPSS datasets                               |
+| sqlite    | SQLite database file                        |
+| tab       | Tab-delimited text files                    |
+| toml      | TOML config files                           |
 | tsv       | Tab-separated values text files             |
 | txt       | Plain text files                            |
 | xls       | Microsoft Excel (legacy .xls; read-only)    |
+| xlsm      | Microsoft Excel Macro-Enabled (XLSM)        |
 | xlsx      | Microsoft Excel (modern .xlsx)              |
+| xpt       | SAS transport files                         |
 | zip       | ZIP-compressed files (see Compression)      |
 | xml       | XML files                                   |
 | yaml      | YAML files                                  |
 
+Note: HDF5 support is read-only; writing is currently disabled.
+
 Compression formats (gz, zip) are also supported as wrappers for other formats. Formats not listed
 here are currently stubbed and will raise `NotImplementedError` on read/write.
 

{etlplus-0.16.9 → etlplus-0.17.2}/etlplus/file/arrow.py

@@ -1,8 +1,7 @@
 """
 :mod:`etlplus.file.arrow` module.
 
-Stub helpers for reading/writing Apache Arrow (ARROW) files (not implemented
-yet).
+Helpers for reading/writing Apache Arrow (ARROW) files.
 
 Notes
 -----
@@ -20,10 +19,13 @@ Notes
 from __future__ import annotations
 
 from pathlib import Path
+from typing import Any
+from typing import cast
 
 from ..types import JSONData
 from ..types import JSONList
-from . import stub
+from ._imports import get_optional_module
+from ._io import normalize_records
 
 # SECTION: EXPORTS ========================================================== #
 
@@ -35,6 +37,20 @@ __all__ = [
 ]
 
 
+# SECTION: INTERNAL FUNCTIONS =============================================== #
+
+
+def _get_pyarrow() -> Any:
+    """Return the pyarrow module, importing it on first use."""
+    return get_optional_module(
+        'pyarrow',
+        error_message=(
+            'ARROW support requires optional dependency "pyarrow".\n'
+            'Install with: pip install pyarrow'
+        ),
+    )
+
+
 # SECTION: FUNCTIONS ======================================================== #
 
 
@@ -54,7 +70,11 @@ def read(
     JSONList
         The list of dictionaries read from the Apache Arrow file.
     """
-    return stub.read(path, format_name='ARROW')
+    pyarrow = _get_pyarrow()
+    with pyarrow.memory_map(str(path), 'r') as source:
+        reader = pyarrow.ipc.open_file(source)
+        table = reader.read_all()
+    return cast(JSONList, table.to_pylist())
 
 
 def write(
@@ -77,4 +97,14 @@ def write(
     int
         The number of rows written to the ARROW file.
     """
-    return stub.write(path, data, format_name='ARROW')
+    records = normalize_records(data, 'ARROW')
+    if not records:
+        return 0
+
+    pyarrow = _get_pyarrow()
+    table = pyarrow.Table.from_pylist(records)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with pyarrow.OSFile(str(path), 'wb') as sink:
+        with pyarrow.ipc.new_file(sink, table.schema) as writer:
+            writer.write_table(table)
+    return len(records)

etlplus-0.17.2/etlplus/file/bson.py

@@ -0,0 +1,124 @@
+"""
+:mod:`etlplus.file.bson` module.
+
+Helpers for reading/writing Binary JSON (BSON) files.
+
+Notes
+-----
+- A BSON file is a binary-encoded serialization of JSON-like documents.
+- Common cases:
+    - Data storage in MongoDB.
+    - Efficient data interchange between systems.
+    - Handling of complex data types not supported in standard JSON.
+- Rule of thumb:
+    - If the file follows the BSON 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 JSONList
+from ._imports import get_optional_module
+from ._io import normalize_records
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    # Functions
+    'read',
+    'write',
+]
+
+
+# SECTION: INTERNAL FUNCTIONS =============================================== #
+
+
+def _decode_all(bson_module: Any, payload: bytes) -> list[dict[str, Any]]:
+    if hasattr(bson_module, 'decode_all'):
+        return bson_module.decode_all(payload)
+    if hasattr(bson_module, 'BSON'):
+        return bson_module.BSON.decode_all(payload)
+    raise AttributeError('bson module lacks decode_all()')
+
+
+def _encode_doc(bson_module: Any, doc: dict[str, Any]) -> bytes:
+    if hasattr(bson_module, 'encode'):
+        return bson_module.encode(doc)
+    if hasattr(bson_module, 'BSON'):
+        return bson_module.BSON.encode(doc)
+    raise AttributeError('bson module lacks encode()')
+
+
+def _get_bson() -> Any:
+    """Return the bson module, importing it on first use."""
+    return get_optional_module(
+        'bson',
+        error_message=(
+            'BSON support requires optional dependency "pymongo".\n'
+            'Install with: pip install pymongo'
+        ),
+    )
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def read(
+    path: Path,
+) -> JSONList:
+    """
+    Read BSON content from *path*.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the BSON file on disk.
+
+    Returns
+    -------
+    JSONList
+        The list of dictionaries read from the BSON file.
+    """
+    bson = _get_bson()
+    with path.open('rb') as handle:
+        payload = handle.read()
+    docs = _decode_all(bson, payload)
+    return cast(JSONList, docs)
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write *data* to BSON at *path* and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the BSON file on disk.
+    data : JSONData
+        Data to write as BSON. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the BSON file.
+    """
+    bson = _get_bson()
+    records = normalize_records(data, 'BSON')
+    if not records:
+        return 0
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open('wb') as handle:
+        for record in records:
+            handle.write(_encode_doc(bson, record))
+    return len(records)

etlplus-0.17.2/etlplus/file/cbor.py

@@ -0,0 +1,104 @@
+"""
+:mod:`etlplus.file.cbor` module.
+
+Helpers for reading/writing Concise Binary Object Representation (CBOR) files.
+
+Notes
+-----
+- A CBOR file is a binary data format designed for small code size and message
+    size, suitable for constrained environments.
+- Common cases:
+    - IoT data interchange.
+    - Efficient data serialization.
+    - Storage of structured data in a compact binary form.
+- Rule of thumb:
+    - If the file follows the CBOR specification, use this module for reading
+        and writing.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ..types import JSONData
+from ._imports import get_optional_module
+from ._io import coerce_record_payload
+from ._io import normalize_records
+
+# SECTION: EXPORTS ========================================================== #
+
+
+__all__ = [
+    # Functions
+    'read',
+    'write',
+]
+
+
+# SECTION: INTERNAL FUNCTIONS =============================================== #
+
+
+def _get_cbor() -> Any:
+    """Return the cbor2 module, importing it on first use."""
+    return get_optional_module(
+        'cbor2',
+        error_message=(
+            'CBOR support requires optional dependency "cbor2".\n'
+            'Install with: pip install cbor2'
+        ),
+    )
+
+
+# SECTION: FUNCTIONS ======================================================== #
+
+
+def read(
+    path: Path,
+) -> JSONData:
+    """
+    Read CBOR content from *path*.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the CBOR file on disk.
+
+    Returns
+    -------
+    JSONData
+        The structured data read from the CBOR file.
+    """
+    cbor2 = _get_cbor()
+    with path.open('rb') as handle:
+        payload = cbor2.loads(handle.read())
+    return coerce_record_payload(payload, format_name='CBOR')
+
+
+def write(
+    path: Path,
+    data: JSONData,
+) -> int:
+    """
+    Write *data* to CBOR file at *path* and return record count.
+
+    Parameters
+    ----------
+    path : Path
+        Path to the CBOR file on disk.
+    data : JSONData
+        Data to write as CBOR file. Should be a list of dictionaries or a
+        single dictionary.
+
+    Returns
+    -------
+    int
+        The number of rows written to the CBOR file.
+    """
+    cbor2 = _get_cbor()
+    records = normalize_records(data, 'CBOR')
+    payload: JSONData = records if isinstance(data, list) else records[0]
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open('wb') as handle:
+        handle.write(cbor2.dumps(payload))
+    return len(records)