Metadata-Version: 2.4
Name: xwstorage
Version: 0.0.1.6
Summary: Convenience wrapper for exonware-xwstorage - provides 'import xwstorage' alias
Project-URL: Homepage, https://github.com/exonware/xwstorage
Project-URL: Documentation, https://github.com/exonware/xwstorage/docs
Project-URL: Repository, https://github.com/exonware/xwstorage
Project-URL: Issues, https://github.com/exonware/xwstorage/issues
Author-email: eXonware Backend Team <connect@exonware.com>
License: Apache-2.0
License-File: LICENSE
Keywords: connectors,database,exonware,storage
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Requires-Dist: exonware-xwstorage
Provides-Extra: dev
Requires-Dist: exonware-xwstorage[dev]; extra == 'dev'
Provides-Extra: full
Requires-Dist: exonware-xwstorage[full]; extra == 'full'
Provides-Extra: lazy
Requires-Dist: exonware-xwstorage[lazy]; extra == 'lazy'
Provides-Extra: xw
Requires-Dist: exonware-xwstorage[xw]; extra == 'xw'
Description-Content-Type: text/markdown

# xwstorage

One API over embedded engines, SQL, NoSQL, graph, and vector backends, with entity-aware persistence (xwentity), xwquery, and optional server/UI layers. Built on xwsystem, xwentity, xwdata, xwnode, and xwquery. Status and roadmap: [REF_22_PROJECT](docs/REF_22_PROJECT.md).

Longer write-up: [README_LONG.md](README_LONG.md).

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

[![Status](https://img.shields.io/badge/status-alpha-orange.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-xwstorage` | **Lite** - core abstraction | Smallest install. |
| `pip install exonware-xwstorage[lazy]` | **Lazy** - connectors load when first used | Development. |
| `pip install exonware-xwstorage[full]` | **Full** - common connectors plus the same first-party **\[stack\]** pins (**xwjson** … **xwaction**, REF_41 §8) | CI or production images that should not miss the XW graph. |
| `pip install exonware-xwstorage[stack]` | **xwjson**, **xwnode**, **xwdata**, **xwschema**, **xwentity**, **xwmodels**, **xwquery**, **xwaction** (REF_41 §8) | Monorepo / enterprise hosts that want the full XW stack next to storage without guessing transitives. |

Depends on xwsystem; other stack packages as you use features. Extras only change dependencies.

After **`[stack]`** or **`[full]`**, you can **`import exonware.xwstorage.stack`** at process startup to eagerly import **xwjson** through **xwaction** (see REF_41 §8).

**Remote database / engine:** use ``exonware.xwstorage.connectors.XWDBRemoteConfig`` and an HTTP client against your engine’s API — ``exonware-xwdb`` is **not** a pip dependency of ``exonware-xwstorage``.

**Stack reference:** connector vs product vs `*-api` deploy packages — [.docs/guides/REF_40_CONNECTOR_PRODUCT_API_STACK.md](../.docs/guides/REF_40_CONNECTOR_PRODUCT_API_STACK.md). **Dependency directions:** [.docs/guides/REF_41_DEPENDENCY_DIRECTIONS.md](../.docs/guides/REF_41_DEPENDENCY_DIRECTIONS.md).

---

## 🚀 Quick start

```python
from exonware.xwstorage import get_storage_facade

storage = get_storage_facade(backend="embedded")  # or postgres, mongodb, neo4j, etc.
storage.connect()
storage.put("key", value)
data = storage.get("key")
storage.query("SELECT * FROM entities WHERE ...")
storage.disconnect()
```

Entity-aware persistence, xwquery, and transactions: [docs/](docs/) and [REF_15_API](docs/REF_15_API.md).

---

## ✨ What you get

| Area | Contents |
|------|----------|
| **Backends** | Pluggable embedded, PostgreSQL, MongoDB, Neo4j, vector stores, and more; transactions, indexing, WAL where supported. |
| **ACID (file-backed)** | **EmbeddedStorageEngine** with WAL and recovery - see [REF_15_API](docs/REF_15_API.md) (Transactions / file-backed ACID). |
| **Integration** | xwentity, xwdata, xwnode, xwquery. |
| **Server (optional)** | xwstorage-server - REST/GraphQL, auth, multi-tenant patterns. |
| **Frontend (optional)** | UI for schema, query, and data browsing (xwui). |

Architecture: [REF_13_ARCH](docs/REF_13_ARCH.md). Connectors: [docs/connectors/](docs/connectors/) when present.

---

## 🌐 Ecosystem functional contributions

`xwstorage` focuses on persistence; the surrounding XW libraries provide the contract, query, and domain layers it needs.
You can run `xwstorage` standalone with the backends and connectors you already use.
Bringing in more XW libraries is optional and mostly beneficial for enterprise and mission-critical environments where you want full infrastructure ownership.

| Supporting XW lib | What it provides to xwstorage | Functional requirement it satisfies |
|------|----------------|----------------|
| **XWSystem** | Core runtime contracts, serializer/caching/security utilities, and shared infrastructure primitives. | Stable engine internals and consistent operational behavior across storage backends. |
| **XWEntity** | Entity-aware persistence hooks and model lifecycle integration points. | Domain-driven persistence instead of raw key/value-only storage usage. |
| **XWData** | Data conversion and multi-format payload handling for ingest/export flows. | Interoperable data pipelines across formats and storage engines. |
| **XWNode** | Graph/structure-aware node strategies and path semantics integration. | Complex structured data handling beyond flat relational rows. |
| **XWQuery** | Unified query execution model across supported backends and in-memory data. | One query surface for heterogeneous storage engines. |
| **XWSchema** | Validation and schema contract support for persisted objects and evolution paths. | Safer schema-on-write/schema-on-read workflows and migration reliability. |
| **XWStorage-API** | Thin HTTP server wrapper over xwstorage API surfaces. | Service exposure requirement (remote access, API-first deployment). |

Competitive edge: `xwstorage` is not just a connector set; it is a storage control plane with consistent contracts across engine types, query styles, and deployment modes.

---

## 📖 Docs and tests

- **Start:** [docs/INDEX.md](docs/INDEX.md) if present; else [docs/](docs/).
- **REFs:** [REF_22_PROJECT](docs/REF_22_PROJECT.md), [REF_13_ARCH](docs/REF_13_ARCH.md), [REF_15_API](docs/REF_15_API.md), [REF_51_TEST](docs/REF_51_TEST.md).
- **Tests:** [docs/REF_51_TEST.md](docs/REF_51_TEST.md) if present. Run from repo root per layout.

---

## 📜 License and links

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

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


## ⏱️ Async Support

<!-- async-support:start -->
- xwstorage includes asynchronous execution paths in production code.
- Source validation: 117 async def definitions and 66 await usages under src/.
- Use async APIs for I/O-heavy or concurrent workloads to improve throughput and responsiveness.
<!-- async-support:end -->
Version: 0.0.1.6 | Updated: 11-Apr-2026

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