Metadata-Version: 2.4
Name: exonware-xwformats
Version: 0.9.0.35
Summary: Heavyweight serialization formats for xwsystem (schema, scientific, database, binary, RON). CSV/JSON/TOML/YAML/XML, BSON, and other core xwsystem codecs are not registered by this package
Project-URL: Homepage, https://exonware.com
Project-URL: Repository, https://github.com/exonware/xwformats
Project-URL: Documentation, https://github.com/exonware/xwformats#readme
Author-email: "Eng. Muhammad AlShehri" <connect@exonware.com>
License: Apache-2.0
License-File: LICENSE
Keywords: avro,enterprise,exonware,formats,hdf5,netcdf,parquet,protobuf,scientific,serialization,thrift
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: exonware-xwlazy==1.0.1.82
Requires-Dist: exonware-xwsystem==0.9.0.43
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: exonware-xwsystem[lazy]==0.9.0.43; extra == 'dev'
Requires-Dist: fastavro>=1.4.0; extra == 'dev'
Requires-Dist: flatbuffers>=2.0.0; extra == 'dev'
Requires-Dist: h5py>=3.8.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: lmdb>=1.4.0; extra == 'dev'
Requires-Dist: lxml>=4.9.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: neo4j>=4.4.0; extra == 'dev'
Requires-Dist: netcdf4>=1.6.0; extra == 'dev'
Requires-Dist: numpy>=1.20.0; extra == 'dev'
Requires-Dist: pandas>=1.3.0; extra == 'dev'
Requires-Dist: plyvel>=1.5.0; extra == 'dev'
Requires-Dist: protobuf>=3.19.0; extra == 'dev'
Requires-Dist: py-ubjson>=0.16.0; extra == 'dev'
Requires-Dist: pyarrow>=8.0.0; extra == 'dev'
Requires-Dist: pycapnp>=1.1.0; extra == 'dev'
Requires-Dist: pydgraph>=21.3.0; extra == 'dev'
Requires-Dist: pyorc>=0.6.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: scipy>=1.7.0; extra == 'dev'
Requires-Dist: thrift>=0.15.0; extra == 'dev'
Requires-Dist: zarr>=2.15.0; extra == 'dev'
Provides-Extra: full
Requires-Dist: exonware-xwsystem[lazy]==0.9.0.43; extra == 'full'
Requires-Dist: fastavro>=1.4.0; extra == 'full'
Requires-Dist: flatbuffers>=2.0.0; extra == 'full'
Requires-Dist: h5py>=3.8.0; extra == 'full'
Requires-Dist: lmdb>=1.4.0; extra == 'full'
Requires-Dist: lxml>=4.9.0; extra == 'full'
Requires-Dist: neo4j>=4.4.0; extra == 'full'
Requires-Dist: netcdf4>=1.6.0; extra == 'full'
Requires-Dist: numpy>=1.20.0; extra == 'full'
Requires-Dist: pandas>=1.3.0; extra == 'full'
Requires-Dist: plyvel>=1.5.0; extra == 'full'
Requires-Dist: protobuf>=3.19.0; extra == 'full'
Requires-Dist: py-ubjson>=0.16.0; extra == 'full'
Requires-Dist: pyarrow>=8.0.0; extra == 'full'
Requires-Dist: pycapnp>=1.1.0; extra == 'full'
Requires-Dist: pydgraph>=21.3.0; extra == 'full'
Requires-Dist: pyorc>=0.6.0; extra == 'full'
Requires-Dist: scipy>=1.7.0; extra == 'full'
Requires-Dist: thrift>=0.15.0; extra == 'full'
Requires-Dist: zarr>=2.15.0; extra == 'full'
Provides-Extra: lazy
Requires-Dist: exonware-xwlazy==1.0.1.82; extra == 'lazy'
Requires-Dist: exonware-xwsystem[lazy]==0.9.0.43; extra == 'lazy'
Provides-Extra: xw
Description-Content-Type: text/markdown

# xwformats

**Many serialization formats, one package.** Schema (Protobuf, Parquet, Thrift, …), scientific (HDF5, Feather, Zarr, …), database (LMDB, LevelDB, …), plus binary and text. Same converter style as xwsystem; formats register on import. Pick **lite**, **lazy**, **full**, or **dev** extras to match how you deploy.

**Company:** eXonware.com · **Author:** eXonware Backend Team · **Email:** connect@exonware.com  

[![Status](https://img.shields.io/badge/status-beta-blue.svg)](https://exonware.com)
[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

---

## 📦 Install

| Install | What you get | When to use |
|---------|--------------|-------------|
| `pip install exonware-xwformats` | **Base** — `exonware-xwsystem[full]` (shared text/JSON stack, etc.) + lazy hooks | Heavier than core-only xwsystem; add `[full]` for extra heavyweight codecs. |
| `pip install exonware-xwformats[lazy]` | **Lazy** - `xwsystem[lazy]` + lazy extras | Matches lazy-optional stack in docs. |
| `pip install exonware-xwformats[full]` | **Full** - common format deps installed up front | Production or CI; on **Windows**, LevelDB/RocksDB wheels may be missing (see `docs/REF_54_BENCH.md`). |
| `pip install exonware-xwformats[dev]` | **Dev** - pytest, black, mypy, … | Contributors |

Base install pulls **`exonware-xwsystem[full]`** (CSV, JSON, TOML, YAML, XML, and other xwsystem optionals) and enables **xwlazy** when available. `[lazy]`, `[dev]`, and `[full]` are extras on top.

---

## 🚀 Quick start

```python
from exonware.xwformats import XWFormats

xf = XWFormats()
print(xf.list_formats())                       # All registered formats
data = xf.convert(json_bytes, "json", "yaml")  # Bidirectional conversion
ser = xf.get_serializer("parquet")
ser.encode(value)
ser.decode(data)
```

Importing xwformats registers its formats with xwsystem; use xwsystem's codec/facade for detection by file extension. See [REF_14_DX](docs/REF_14_DX.md) and [REF_15_API](docs/REF_15_API.md).

---

## ✨ What you get

| Area | What's in it |
|------|----------------|
| **Schema** | Protobuf, Parquet, Thrift, ORC, Cap'n Proto, FlatBuffers, Arrow. **Avro** is optional (may be off default import on some platforms - see `__init__.py` and `docs/_archive/KNOWN_ISSUES.md`). |
| **Scientific** | HDF5, Feather, Zarr, NetCDF, MAT. |
| **Database** | LMDB, LevelDB, RocksDB, GraphDB. |
| **Binary / text** | **UBJSON**, Bincode, Dill, Postcard, and **RON** are implemented in xwformats. **BSON**, **CSV, JSON, TOML, YAML, XML**, and other core xwsystem binaries are **xwsystem-only** — not registered or exported by xwformats. |
| **Integration** | Same converter/facade as xwsystem; codec registry updated on import. |

**Lite** = few deps. **Lazy** = optional format wheels on first use. **Full** = common optionals pre-installed. Platform notes (e.g. RocksDB on Windows): [docs/logs/setup/](docs/logs/setup/). Known issues: [docs/_archive/KNOWN_ISSUES.md](docs/_archive/KNOWN_ISSUES.md) and [REF_22_PROJECT.md](docs/REF_22_PROJECT.md#project-status-overview).

---

## 🌐 Ecosystem functional contributions

`xwformats` extends format coverage; sibling XW libs provide runtime loading strategy, registration, and downstream consumption layers.
You can use `xwformats` standalone for broad serializer coverage and conversion tasks.
Integrating with additional XW libraries is optional and mainly useful for enterprise and mission-critical pipelines that need unified runtime, storage, and query infrastructure.

| Supporting XW lib | What it provides to xwformats | Functional requirement it satisfies |
|------|----------------|----------------|
| **XWSystem** | Core codec registry/facade and serializer contracts that xwformats registers into. | One unified serialization API despite many optional format backends. |
| **XWLazy** | On-demand dependency loading/install behavior for optional format stacks. | Practical deployment of many formats without forcing heavy installs. |
| **XWData** | Higher-level data transformation workflows that consume xwformats codecs. | Real pipeline usage beyond encode/decode-only primitives. |
| **XWStorage** | Persistence engine integrations that use specialized format serializers. | Storage interoperability for scientific/schema/database-oriented payloads. |
| **XWJSON** | Binary JSON and local data-engine flows that can interoperate with format conversion paths. | Efficient local format conversion and transition workflows. |
| **XWQuery** | Query pipelines over data loaded via format serializers. | End-to-end analytics/transform use cases after format normalization. |

Competitive edge: instead of isolated serializer plugins, `xwformats` plugs into a shared runtime and data stack so advanced formats are immediately usable in storage/query/application workflows.

---

## 📖 Docs and tests

Aligned with project REFs and [docs/GUIDE_01_USAGE.md](docs/GUIDE_01_USAGE.md) (see [GUIDE_63_README](../.docs/guides/GUIDE_63_README.md) in the monorepo).

- **Start:** [docs/INDEX.md](docs/INDEX.md) - index and quick links.
- **Use:** [docs/GUIDE_01_USAGE.md](docs/GUIDE_01_USAGE.md) - usage and format list.
- **Requirements / status:** [docs/REF_01_REQ.md](docs/REF_01_REQ.md), [docs/REF_22_PROJECT.md](docs/REF_22_PROJECT.md).
- **API / design:** [docs/REF_15_API.md](docs/REF_15_API.md), [docs/REF_13_ARCH.md](docs/REF_13_ARCH.md), [docs/REF_14_DX.md](docs/REF_14_DX.md).
- **Tests:** [docs/REF_51_TEST.md](docs/REF_51_TEST.md). Summaries: [docs/logs/tests/](docs/logs/tests/). Run: `python tests/runner.py` or pytest from repo root.

---

## 📜 License and links

Apache-2.0 - see [LICENSE](LICENSE).

- **Homepage:** https://exonware.com  
- **Repository:** https://github.com/exonware/xwformats  

## ⏱️ Async Support

<!-- async-support:start -->
- xwformats is primarily synchronous in its current implementation.
- Source validation: 0 async def definitions and 0 await usages under src/.
- This module still composes with async-capable xw libraries at integration boundaries when needed.
<!-- async-support:end -->
Version: 0.9.0.34 | Updated: 25-Apr-2026

*Built with ❤️ by eXonware.com - Revolutionizing Python Development Since 2025*
