etlplus 0.11.8__tar.gz → 0.12.4__tar.gz

{etlplus-0.11.8 → etlplus-0.12.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: etlplus
-Version: 0.11.8
+Version: 0.12.4
 Summary: A Swiss Army knife for simple ETL operations
 Home-page: https://github.com/Dagitali/ETLPlus
 Author: ETLPlus Team
@@ -17,8 +17,11 @@ Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.13,<3.15
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: fastavro>=1.12.1
 Requires-Dist: jinja2>=3.1.6
+Requires-Dist: openpyxl>=3.1.5
 Requires-Dist: pyodbc>=5.3.0
+Requires-Dist: pyarrow>=22.0.0
 Requires-Dist: python-dotenv>=1.2.1
 Requires-Dist: pandas>=2.3.3
 Requires-Dist: pydantic>=2.12.5
@@ -26,6 +29,8 @@ Requires-Dist: PyYAML>=6.0.3
 Requires-Dist: requests>=2.32.5
 Requires-Dist: SQLAlchemy>=2.0.45
 Requires-Dist: typer>=0.21.0
+Requires-Dist: xlrd>=2.0.2
+Requires-Dist: xlwt>=1.3.0
 Provides-Extra: dev
 Requires-Dist: black>=25.9.0; extra == "dev"
 Requires-Dist: build>=1.2.2; extra == "dev"
@@ -59,6 +64,7 @@ ETLPlus is a veritable Swiss Army knife for enabling simple ETL operations, offe
 package and command-line interface for data extraction, validation, transformation, and loading.
 
 - [ETLPlus](#etlplus)
+  - [Getting Started](#getting-started)
   - [Features](#features)
   - [Installation](#installation)
   - [Quickstart](#quickstart)
@@ -87,11 +93,27 @@ package and command-line interface for data extraction, validation, transformati
     - [Linting](#linting)
     - [Updating Demo Snippets](#updating-demo-snippets)
     - [Releasing to PyPI](#releasing-to-pypi)
-  - [Links](#links)
   - [License](#license)
   - [Contributing](#contributing)
+  - [Documentation](#documentation)
+    - [Python Packages/Subpackage](#python-packagessubpackage)
+    - [Community Health](#community-health)
+    - [Other](#other)
   - [Acknowledgments](#acknowledgments)
 
+## Getting Started
+
+ETLPlus helps you extract, validate, transform, and load data from files, databases, and APIs, either
+as a Python library or from the command line.
+
+To get started:
+
+- See [Installation](#installation) for setup instructions.
+- Try the [Quickstart](#quickstart) for a minimal working example (CLI and Python).
+- Explore [Usage](#usage) for more detailed options and workflows.
+
+ETLPlus supports Python 3.13 and above.
+
 ## Features
 
 - **Check** data pipeline definitions before running them:
@@ -416,7 +438,7 @@ etlplus transform \
 # 3. Validate transformed data
 etlplus validate \
   --rules '{"name": {"type": "string", "required": true}, "email": {"type": "string", "required": true}}' \
-  temo/sample_transformed.json
+  temp/sample_transformed.json
 
 # 4. Load to CSV
 cat temp/sample_transformed.json \
@@ -603,17 +625,6 @@ git push origin v1.4.0
 If you want an extra smoke-test before tagging, run `make dist && pip install dist/*.whl` locally;
 this exercises the same build path the workflow uses.
 
-## Links
-
-- API client docs: [`etlplus/api/README.md`](etlplus/api/README.md)
-- Examples: [`examples/README.md`](examples/README.md)
-- Pipeline authoring guide: [`docs/pipeline-guide.md`](docs/pipeline-guide.md)
-- Runner internals: [`docs/run-module.md`](docs/run-module.md)
-- Design notes (Mapping inputs, dict outputs): [`docs/pipeline-guide.md#design-notes-mapping-inputs-dict-outputs`](docs/pipeline-guide.md#design-notes-mapping-inputs-dict-outputs)
-- Typing philosophy: [`CONTRIBUTING.md#typing-philosophy`](CONTRIBUTING.md#typing-philosophy)
-- Demo and walkthrough: [`DEMO.md`](DEMO.md)
-- Additional references: [`REFERENCES.md`](`REFERENCES.md)
-
 ## License
 
 This project is licensed under the [MIT License](LICENSE).
@@ -637,6 +648,39 @@ If you choose to be a code contributor, please first refer these documents:
 - Typing philosophy (TypedDicts as editor hints, permissive runtime):
   [`CONTRIBUTING.md#typing-philosophy`](CONTRIBUTING.md#typing-philosophy)
 
+## Documentation
+
+### Python Packages/Subpackage
+
+Navigate to detailed documentation for each subpackage:
+
+- [etlplus.api](etlplus/api/README.md): Lightweight HTTP client and paginated REST helpers
+- [etlplus.file](etlplus/file/README.md): Unified file format support and helpers
+- [etlplus.config](etlplus/config/README.md): Configuration helpers for connectors, pipelines, jobs,
+  and profiles
+- [etlplus.cli](etlplus/cli/README.md): Command-line interface for ETLPlus workflows
+- [etlplus.database](etlplus/database/README.md): Database engine, schema, and ORM helpers
+- [etlplus.templates](etlplus/templates/README.md): SQL and DDL template helpers
+- [etlplus.validation](etlplus/validation/README.md): Data validation utilities and helpers
+
+### Community Health
+
+- [Contributing Guidelines](CONTRIBUTING.md): How to contribute, report issues, and submit PRs
+- [Code of Conduct](CODE_OF_CONDUCT.md): Community standards and expectations
+- [Security Policy](SECURITY.md): Responsible disclosure and vulnerability reporting
+- [Support](SUPPORT.md): Where to get help
+
+### Other
+
+- API client docs: [`etlplus/api/README.md`](etlplus/api/README.md)
+- Examples: [`examples/README.md`](examples/README.md)
+- Pipeline authoring guide: [`docs/pipeline-guide.md`](docs/pipeline-guide.md)
+- Runner internals: [`docs/run-module.md`](docs/run-module.md)
+- Design notes (Mapping inputs, dict outputs): [`docs/pipeline-guide.md#design-notes-mapping-inputs-dict-outputs`](docs/pipeline-guide.md#design-notes-mapping-inputs-dict-outputs)
+- Typing philosophy: [`CONTRIBUTING.md#typing-philosophy`](CONTRIBUTING.md#typing-philosophy)
+- Demo and walkthrough: [`DEMO.md`](DEMO.md)
+- Additional references: [`REFERENCES.md`](REFERENCES.md)
+
 ## Acknowledgments
 
 ETLPlus is inspired by common work patterns in data engineering and software engineering patterns in

etlplus-0.11.8/etlplus.egg-info/PKG-INFO → etlplus-0.12.4/README.md

@@ -1,48 +1,3 @@
-Metadata-Version: 2.4
-Name: etlplus
-Version: 0.11.8
-Summary: A Swiss Army knife for simple ETL operations
-Home-page: https://github.com/Dagitali/ETLPlus
-Author: ETLPlus Team
-License: MIT
-Project-URL: Homepage, https://github.com/Dagitali/ETLPlus
-Project-URL: Repository, https://github.com/Dagitali/ETLPlus
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Requires-Python: >=3.13,<3.15
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: jinja2>=3.1.6
-Requires-Dist: pyodbc>=5.3.0
-Requires-Dist: python-dotenv>=1.2.1
-Requires-Dist: pandas>=2.3.3
-Requires-Dist: pydantic>=2.12.5
-Requires-Dist: PyYAML>=6.0.3
-Requires-Dist: requests>=2.32.5
-Requires-Dist: SQLAlchemy>=2.0.45
-Requires-Dist: typer>=0.21.0
-Provides-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"
-Requires-Dist: PyYAML>=6.0.3; extra == "dev"
-Requires-Dist: pydoclint>=0.8.1; extra == "dev"
-Requires-Dist: pydocstyle>=6.3.0; extra == "dev"
-Requires-Dist: pytest>=8.4.2; extra == "dev"
-Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
-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"
-Dynamic: home-page
-Dynamic: license-file
-Dynamic: requires-python
-
 # ETLPlus
 
 [![PyPI](https://img.shields.io/pypi/v/etlplus.svg)][PyPI package]
@@ -59,6 +14,7 @@ ETLPlus is a veritable Swiss Army knife for enabling simple ETL operations, offe
 package and command-line interface for data extraction, validation, transformation, and loading.
 
 - [ETLPlus](#etlplus)
+  - [Getting Started](#getting-started)
   - [Features](#features)
   - [Installation](#installation)
   - [Quickstart](#quickstart)
@@ -87,11 +43,27 @@ package and command-line interface for data extraction, validation, transformati
     - [Linting](#linting)
     - [Updating Demo Snippets](#updating-demo-snippets)
     - [Releasing to PyPI](#releasing-to-pypi)
-  - [Links](#links)
   - [License](#license)
   - [Contributing](#contributing)
+  - [Documentation](#documentation)
+    - [Python Packages/Subpackage](#python-packagessubpackage)
+    - [Community Health](#community-health)
+    - [Other](#other)
   - [Acknowledgments](#acknowledgments)
 
+## Getting Started
+
+ETLPlus helps you extract, validate, transform, and load data from files, databases, and APIs, either
+as a Python library or from the command line.
+
+To get started:
+
+- See [Installation](#installation) for setup instructions.
+- Try the [Quickstart](#quickstart) for a minimal working example (CLI and Python).
+- Explore [Usage](#usage) for more detailed options and workflows.
+
+ETLPlus supports Python 3.13 and above.
+
 ## Features
 
 - **Check** data pipeline definitions before running them:
@@ -416,7 +388,7 @@ etlplus transform \
 # 3. Validate transformed data
 etlplus validate \
   --rules '{"name": {"type": "string", "required": true}, "email": {"type": "string", "required": true}}' \
-  temo/sample_transformed.json
+  temp/sample_transformed.json
 
 # 4. Load to CSV
 cat temp/sample_transformed.json \
@@ -603,17 +575,6 @@ git push origin v1.4.0
 If you want an extra smoke-test before tagging, run `make dist && pip install dist/*.whl` locally;
 this exercises the same build path the workflow uses.
 
-## Links
-
-- API client docs: [`etlplus/api/README.md`](etlplus/api/README.md)
-- Examples: [`examples/README.md`](examples/README.md)
-- Pipeline authoring guide: [`docs/pipeline-guide.md`](docs/pipeline-guide.md)
-- Runner internals: [`docs/run-module.md`](docs/run-module.md)
-- Design notes (Mapping inputs, dict outputs): [`docs/pipeline-guide.md#design-notes-mapping-inputs-dict-outputs`](docs/pipeline-guide.md#design-notes-mapping-inputs-dict-outputs)
-- Typing philosophy: [`CONTRIBUTING.md#typing-philosophy`](CONTRIBUTING.md#typing-philosophy)
-- Demo and walkthrough: [`DEMO.md`](DEMO.md)
-- Additional references: [`REFERENCES.md`](`REFERENCES.md)
-
 ## License
 
 This project is licensed under the [MIT License](LICENSE).
@@ -637,6 +598,39 @@ If you choose to be a code contributor, please first refer these documents:
 - Typing philosophy (TypedDicts as editor hints, permissive runtime):
   [`CONTRIBUTING.md#typing-philosophy`](CONTRIBUTING.md#typing-philosophy)
 
+## Documentation
+
+### Python Packages/Subpackage
+
+Navigate to detailed documentation for each subpackage:
+
+- [etlplus.api](etlplus/api/README.md): Lightweight HTTP client and paginated REST helpers
+- [etlplus.file](etlplus/file/README.md): Unified file format support and helpers
+- [etlplus.config](etlplus/config/README.md): Configuration helpers for connectors, pipelines, jobs,
+  and profiles
+- [etlplus.cli](etlplus/cli/README.md): Command-line interface for ETLPlus workflows
+- [etlplus.database](etlplus/database/README.md): Database engine, schema, and ORM helpers
+- [etlplus.templates](etlplus/templates/README.md): SQL and DDL template helpers
+- [etlplus.validation](etlplus/validation/README.md): Data validation utilities and helpers
+
+### Community Health
+
+- [Contributing Guidelines](CONTRIBUTING.md): How to contribute, report issues, and submit PRs
+- [Code of Conduct](CODE_OF_CONDUCT.md): Community standards and expectations
+- [Security Policy](SECURITY.md): Responsible disclosure and vulnerability reporting
+- [Support](SUPPORT.md): Where to get help
+
+### Other
+
+- API client docs: [`etlplus/api/README.md`](etlplus/api/README.md)
+- Examples: [`examples/README.md`](examples/README.md)
+- Pipeline authoring guide: [`docs/pipeline-guide.md`](docs/pipeline-guide.md)
+- Runner internals: [`docs/run-module.md`](docs/run-module.md)
+- Design notes (Mapping inputs, dict outputs): [`docs/pipeline-guide.md#design-notes-mapping-inputs-dict-outputs`](docs/pipeline-guide.md#design-notes-mapping-inputs-dict-outputs)
+- Typing philosophy: [`CONTRIBUTING.md#typing-philosophy`](CONTRIBUTING.md#typing-philosophy)
+- Demo and walkthrough: [`DEMO.md`](DEMO.md)
+- Additional references: [`REFERENCES.md`](REFERENCES.md)
+
 ## Acknowledgments
 
 ETLPlus is inspired by common work patterns in data engineering and software engineering patterns in

etlplus-0.12.4/SECURITY.md

@@ -0,0 +1,15 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in ETLPlus, please report it responsibly:
+
+- **Do not** open a public issue for security problems.
+- Email the maintainers at security@dagitali.com (or use a private contact method listed in the
+  repository).
+- Include as much detail as possible: affected versions, steps to reproduce, and any relevant logs
+  or code.
+- We will acknowledge your report within 3 business days and work with you to resolve the issue
+  promptly.
+
+Thank you for helping keep ETLPlus and its users safe!

etlplus-0.12.4/SUPPORT.md

@@ -0,0 +1,18 @@
+# Support
+
+Thank you for using ETLPlus!
+
+## Where to Get Help
+
+- **Questions & Usage**: Please use [GitHub Discussions][discussions] for general questions, usage
+  help, and best practices.
+- **Bugs & Feature Requests**: Open an issue in the [GitHub Issues][issues] tracker.
+- **Security Issues**: See [SECURITY.md](SECURITY.md) for responsible disclosure.
+- **Documentation**: See the [README](README.md) and [docs/](docs/) directory for guides and
+  references.
+
+We aim to respond to questions and issues as quickly as possible. Community contributions and peer
+support are also welcome!
+
+[discussions]: https://github.com/Dagitali/ETLPlus/discussions
+[issues]: https://github.com/Dagitali/ETLPlus/issues

etlplus-0.12.4/etlplus/README.md

@@ -0,0 +1,37 @@
+# etlplus package
+
+The `etlplus` package provides a unified Python API and CLI for ETL operations: extraction,
+validation, transformation, and loading of data from files, APIs, and databases.
+
+- Top-level entry points for extract, validate, transform, and load
+- Utilities for pipeline orchestration and helpers
+- Exposes all subpackages for advanced usage
+
+Back to project overview: see the top-level [README](../README.md).
+
+## Subpackages
+
+- [etlplus.api](api/README.md): Lightweight HTTP client and paginated REST helpers
+- [etlplus.file](file/README.md): Unified file format support and helpers
+- [etlplus.config](config/README.md): Configuration helpers for connectors, pipelines, jobs, and
+  profiles
+- [etlplus.cli](cli/README.md): Command-line interface for ETLPlus workflows
+- [etlplus.database](database/README.md): Database engine, schema, and ORM helpers
+- [etlplus.templates](templates/README.md): SQL and DDL template helpers
+- [etlplus.validation](validation/README.md): Data validation utilities and helpers
+
+## Quickstart
+
+```python
+from etlplus import extract, validate, transform, load
+
+data = extract("file", "input.csv")
+filtered = transform(data, {"filter": {"field": "age", "op": "gt", "value": 25}})
+assert validate(filtered, {"age": {"type": "number", "min": 0}})["valid"]
+load(filtered, "file", "output.json", file_format="json")
+```
+
+## See Also
+
+- [Top-level project README](../README.md)
+- [API reference](../docs/README.md)

{etlplus-0.11.8 → etlplus-0.12.4}/etlplus/api/README.md

@@ -1,7 +1,7 @@
-# etlplus.api module.
+# etlplus.api subpackage
 
-Focused documentation for the `etlplus.api` subpackage: a lightweight HTTP client and helpers for
-paginated REST endpoints.
+Documentation for the `etlplus.api` subpackage: a lightweight HTTP client and helpers for paginated
+REST endpoints.
 
 - Provides a small `EndpointClient` for calling JSON APIs
 - Supports page-, offset-, and cursor-based pagination via `PaginationConfig`
@@ -12,6 +12,20 @@ paginated REST endpoints.
 
 Back to project overview: see the top-level [README](../../README.md).
 
+- [etlplus.api subpackage](#etlplusapi-subpackage)
+  - [Installation](#installation)
+  - [Quickstart](#quickstart)
+    - [Overriding Rate Limits Per Call](#overriding-rate-limits-per-call)
+  - [Choosing `records_path` and `cursor_path`](#choosing-records_path-and-cursor_path)
+  - [Cursor-Based Pagination Example](#cursor-based-pagination-example)
+  - [Offset-based pagination example](#offset-based-pagination-example)
+  - [Authentication](#authentication)
+  - [Errors and Rate Limiting](#errors-and-rate-limiting)
+  - [Types and Transport](#types-and-transport)
+  - [Supporting Modules](#supporting-modules)
+  - [Minimal Contract](#minimal-contract)
+  - [See also](#see-also)
+
 ## Installation
 
 `etlplus.api` ships as part of the `etlplus` package. Install the package as usual:
@@ -233,3 +247,6 @@ providers can fall back to their own defaults. If you already possess a static t
 ## See also
 
 - Top-level CLI and library usage in the main [README](../../README.md)
+
+
+[def]: #installation

etlplus-0.12.4/etlplus/cli/README.md

@@ -0,0 +1,40 @@
+# etlplus.cli subpackage
+
+Documentation for the `etlplus.cli` subpackage: command-line interface for ETLPlus workflows.
+
+- Provides a CLI for running ETL pipelines, jobs, and utilities
+- Supports commands for running, validating, and inspecting pipelines
+- Includes options for configuration, state, and output control
+- Exposes handlers for custom command integration
+
+Back to project overview: see the top-level [README](../../README.md).
+
+- [etlplus.cli subpackage](#etlpluscli-subpackage)
+  - [Available Commands](#available-commands)
+  - [Command Options](#command-options)
+  - [Example: Running a Pipeline](#example-running-a-pipeline)
+  - [See Also](#see-also)
+
+## Available Commands
+
+- **run**: Execute a pipeline or job
+- **validate**: Validate pipeline or config files
+- **inspect**: Show pipeline/job details
+
+## Command Options
+
+- `--config`: Path to config file
+- `--state`: Path to state file
+- `--output`: Output file or format
+
+## Example: Running a Pipeline
+
+```bash
+etlplus run --config configs/pipeline.yml --output results.json
+```
+
+## See Also
+
+- Top-level CLI and library usage in the main [README](../../README.md)
+- Command handlers in [handlers.py](handlers.py)
+- Command options in [options.py](options.py)

{etlplus-0.11.8 → etlplus-0.12.4}/etlplus/cli/handlers.py

@@ -570,7 +570,7 @@ def transform_handler(
     data = transform(payload, cast(TransformOperations, operations_payload))
 
     if target and target != '-':
-        File.from_path(target, file_format=target_format).write(data)
+        File(target, file_format=target_format).write(data)
         print(f'Data transformed and saved to {target}')
         return 0
 

etlplus-0.12.4/etlplus/config/README.md

@@ -0,0 +1,52 @@
+# etlplus.config subpackage
+
+Documentation for the `etlplus.config` subpackage: configuration helpers for connectors, pipelines,
+jobs, and profiles.
+
+- Provides classes and utilities for managing ETL pipeline configuration
+- Supports YAML/JSON config loading and validation
+- Includes helpers for connectors, jobs, pipelines, and profiles
+- Exposes type definitions for config schemas
+
+Back to project overview: see the top-level [README](../../README.md).
+
+- [etlplus.config subpackage](#etlplusconfig-subpackage)
+  - [Supported Configuration Types](#supported-configuration-types)
+  - [Loading and Validating Configs](#loading-and-validating-configs)
+  - [Example: Loading a Pipeline Config](#example-loading-a-pipeline-config)
+  - [See Also](#see-also)
+
+## Supported Configuration Types
+
+- **Connector**: Connection details for databases, files, or APIs
+- **Job**: ETL job definitions and scheduling
+- **Pipeline**: End-to-end pipeline configuration
+- **Profile**: User or environment-specific settings
+
+## Loading and Validating Configs
+
+Use the provided classes to load and validate configuration files:
+
+```python
+from etlplus.config import PipelineConfig
+
+cfg = PipelineConfig.from_yaml("pipeline.yml")
+```
+
+- Supports YAML and JSON formats
+- Validates against expected schema
+
+## Example: Loading a Pipeline Config
+
+```python
+from etlplus.config import PipelineConfig
+
+pipeline = PipelineConfig.from_yaml("configs/pipeline.yml")
+print(pipeline)
+```
+
+## See Also
+
+- Top-level CLI and library usage in the main [README](../../README.md)
+- Config type definitions in [types.py](types.py)
+- Config utilities in [utils.py](utils.py)

etlplus-0.12.4/etlplus/database/README.md

@@ -0,0 +1,48 @@
+# etlplus.database subpackage
+
+Documentation for the `etlplus.database` subpackage: database engine, schema, and ORM helpers.
+
+- Provides database engine and connection management
+- Supports schema definition and DDL generation
+- Includes lightweight ORM utilities for tabular data
+- Exposes type definitions for database objects
+
+Back to project overview: see the top-level [README](../../README.md).
+
+- [etlplus.database subpackage](#etlplusdatabase-subpackage)
+  - [Database Engine and Connections](#database-engine-and-connections)
+  - [Schema and DDL Helpers](#schema-and-ddl-helpers)
+  - [ORM Utilities](#orm-utilities)
+  - [Example: Creating a Table](#example-creating-a-table)
+  - [See Also](#see-also)
+
+## Database Engine and Connections
+
+- Manage connections to supported databases
+- Configure engines for different backends
+
+## Schema and DDL Helpers
+
+- Define table schemas and columns
+- Generate DDL statements for supported databases
+
+## ORM Utilities
+
+- Map rows to Python objects
+- Simple CRUD helpers for tabular data
+
+## Example: Creating a Table
+
+```python
+from etlplus.database import Schema, Engine
+
+engine = Engine.connect("sqlite:///example.db")
+schema = Schema.from_dict({"name": "users", "columns": [ ... ]})
+engine.create_table(schema)
+```
+
+## See Also
+
+- Top-level CLI and library usage in the main [README](../../README.md)
+- Schema helpers in [schema.py](schema.py)
+- ORM utilities in [orm.py](orm.py)

{etlplus-0.11.8 → etlplus-0.12.4}/etlplus/database/ddl.py

@@ -203,7 +203,7 @@ def load_table_spec(
         raise ValueError('Spec must be .json, .yml, or .yaml')
 
     try:
-        spec = File.from_path(spec_path).read()
+        spec = File(spec_path).read()
     except ImportError as e:
         if suffix in {'.yml', '.yaml'}:
             raise RuntimeError(

etlplus-0.12.4/etlplus/file/README.md

@@ -0,0 +1,105 @@
+# etlplus.file subpackage
+
+Documentation for the `etlplus.file` subpackage: unified file format support and helpers for reading
+and writing data files.
+
+- Provides a consistent interface for reading and writing files in various formats
+- Supports all formats defined in `FileFormat` (see below)
+- Includes helpers for inferring file format and compression from filenames, extensions, or MIME
+  types
+- Exposes a `File` class with instance methods for reading and writing data
+
+Back to project overview: see the top-level [README](../../README.md).
+
+- [etlplus.file subpackage](#etlplusfile-subpackage)
+  - [Supported File Formats](#supported-file-formats)
+  - [Inferring File Format and Compression](#inferring-file-format-and-compression)
+  - [Reading and Writing Files](#reading-and-writing-files)
+    - [Reading a File](#reading-a-file)
+    - [Writing a File](#writing-a-file)
+  - [File Instance Methods](#file-instance-methods)
+  - [Example: Reading and Writing](#example-reading-and-writing)
+  - [See Also](#see-also)
+
+## Supported File Formats
+
+The following formats are defined in `FileFormat` and supported for reading and writing:
+
+| Format    | Description                                 |
+|-----------|---------------------------------------------|
+| avro      | Apache Avro binary serialization            |
+| csv       | Comma-separated values text files           |
+| feather   | Apache Arrow Feather columnar format        |
+| gz        | Gzip-compressed files (see Compression)     |
+| json      | Standard JSON files                         |
+| ndjson    | Newline-delimited JSON (JSON Lines)         |
+| orc       | Apache ORC columnar format                  |
+| parquet   | Apache Parquet columnar format              |
+| tsv       | Tab-separated values text files             |
+| txt       | Plain text files                            |
+| xls       | Microsoft Excel (legacy .xls)               |
+| xlsx      | Microsoft Excel (modern .xlsx)              |
+| zip       | ZIP-compressed files (see Compression)      |
+| xml       | XML files                                   |
+| yaml      | YAML files                                  |
+
+Compression formats (gz, zip) are also supported as wrappers for other formats.
+
+## Inferring File Format and Compression
+
+Use `infer_file_format_and_compression(value, filename=None)` to infer the file format and
+compression from a filename, extension, or MIME type. Returns a tuple `(file_format,
+compression_format)`.
+
+## Reading and Writing Files
+
+The main entry point for file operations is the `File` class. To read or write files:
+
+### Reading a File
+
+```python
+from etlplus.file import File
+
+f = File("data/sample.csv")
+data = f.read()
+```
+
+- The `read()` method automatically detects the format and compression.
+- Returns parsed data (e.g., list of dicts for tabular formats).
+
+### Writing a File
+
+```python
+from etlplus.file import File
+
+f = File("output.json")
+f.write(data)
+```
+
+- The `write()` method serializes and writes data in the appropriate format.
+- Supports all formats listed above.
+
+## File Instance Methods
+
+- `read()`: Reads and parses the file, returning structured data.
+- `write(data)`: Writes structured data to the file in the detected format.
+
+## Example: Reading and Writing
+
+```python
+from etlplus.file import File
+
+# Read CSV
+csv_file = File("data.csv")
+rows = csv_file.read()
+
+# Write JSON
+json_file = File("output.json")
+json_file.write(rows)
+```
+
+## See Also
+
+- Top-level CLI and library usage in the main [README](../../README.md)
+- File format enums in [enums.py](enums.py)
+- Compression format enums in [enums.py](enums.py)