xwjson 0.9.0.23

Convenience wrapper for exonware-xwjson - provides 'import xwjson' alias

xwjson

Binary JSON plus local data-engine behavior for real workloads. .xwjson is powered by the xwsystem parser engine for high-throughput reads/writes, lazy and path-scoped access, schema-aware validation, encrypted payload support, and atomic-first ACID-style transaction flows with WAL. In this repo, performance/stress suites include large-file scenarios validated up to 20GB, stdlib JSON comparisons, and conversion stress runs.

Longer tour, examples, and troubleshooting: README_LONG.md.

Company: eXonware.com · Author: eXonware Backend Team · Email: [e-mail]

---

📦 Install

pip install exonware-xwjson
pip install exonware-xwjson[lazy]
pip install exonware-xwjson[full]

---

🚀 Quick start

from exonware.xwjson import XWJSONSerializer

serializer = XWJSONSerializer()
# Async (recommended)
data = await serializer.load_file_async("data.xwjson")
await serializer.save_file_async(data, "output.xwjson")
# Sync
data = serializer.load_file("data.xwjson")
serializer.save_file(data, "output.xwjson")

See docs/ for REF_*, guides, and examples.

---

✨ What you get

Area	What's in it
Binary engine	xwsystem parser-driven binary encoding with fast serialization paths and metadata-aware payloads.
Lazy + path I/O	Parse on access, stream/paging support, and path-level operations without full materialization.
References	$ref, @href, *anchor preserved and resolved.
Security	Password-based encrypted file support and encrypted payload detection helpers.
Atomic operations	Atomic read/write/update/delete paths for safe state transitions under concurrent workloads.
Transactions	ACID-style flows with WAL-backed transaction components, rollback support, and dependency-aware batch work.
Index/cache acceleration	xwnode strategy integrations for faster lookups and cache-assisted repeated access.
Integration	xwnode, xwschema, xwquery, xwdata, xwstorage; format metadata carried through.

---

⚛️ Atomic operations - core strength

• xwjson is designed around atomic state changes, not best-effort updates.
• Single-file and path-level operations are built to commit safely or fail safely.
• Transaction flows combine atomic steps with WAL-backed durability mechanics.
• For local data-engine workloads, this is a headline capability: atomic operations are first-class, not optional.

---

📊 Performance and benchmark posture

• Built-in performance guidance and benchmark methodology: docs/_archive/GUIDE_PERFORMANCE.md.
• Repo test artifacts include conversion/performance stress suites and large-file scenarios in tests/2.integration/scenarios/.
• File size note: no hard file-size cap is enforced by xwjson; largest documented test scenario in this repo is 20GB.
• Test summaries in tests/FINAL_TEST_SUMMARY.md and tests/TEST_SUMMARY.md document speed-oriented targets (including stdlib JSON comparison paths and cache/index speedups).
• Positioning: xwjson can act like a database-like local data layer for many workloads; external database claims should stay workload-specific and benchmark-backed.

---

🌐 Ecosystem functional contributions

xwjson is a serialization and local data-engine layer; sibling libs provide the runtime, validation, query, and persistence ecosystem around it. You can use xwjson standalone as a high-performance binary JSON and local data-engine option. Using more XW libraries is optional and most valuable for enterprise and mission-critical deployments where you want fully controlled infrastructure around schema, query, and storage.

Supporting XW lib	What it provides to xwjson	Functional requirement it satisfies
XWSystem	Parser/codec/runtime foundation for binary JSON engine behavior and shared helpers.	High-performance, consistent serializer runtime across stack packages.
XWNode	Index/cache and structure-oriented acceleration paths for repeated data access.	Faster structured lookups and navigation over complex payloads.
XWSchema	Schema-aware validation hooks for loaded/transformed data.	Data contract integrity during local JSON-engine operations.
XWQuery	Query execution over xwjson-backed in-memory payloads.	Declarative filtering/aggregation without custom traversal code.
XWData	Data-model and conversion workflows that consume xwjson input/output.	Cross-format data pipeline interoperability.
XWStorage	Persistence abstraction using xwjson as local/default serialization format in storage scenarios.	Durable state management and backend portability with predictable on-disk format.

Competitive edge: xwjson combines binary JSON performance with transaction/atomic semantics and first-class integration into query, schema, and storage layers.

---

📖 Docs and tests

• Start: docs/INDEX.md or docs/.
• Guides: Basic/advanced usage, performance, conversion, schema validation under docs/ when present.
• Tests: From repo root, follow this package's runner or pytest layout.

---

📜 License and links

Apache-2.0 - see LICENSE. Homepage: https://exonware.com · Repository: https://github.com/exonware/xwjson

⏱️ Async Support

• xwjson includes asynchronous execution paths in production code.
• Source validation: 46 async def definitions and 50 await usages under src/.
• Use async APIs for I/O-heavy or concurrent workloads to improve throughput and responsiveness.

Version: 0.9.0.23 | Updated: 13-Apr-2026

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