Metadata-Version: 2.4
Name: exonware-xwapi
Version: 0.9.0.8
Summary: Entity- and action-centric API layer: build once, publish anywhere — expose XWAction/XWEntity over HTTP (FastAPI default, Flask engine) and consume the same contracts from client agents; OpenAPI, middleware, and production ops for the eXonware stack.
Project-URL: Homepage, https://exonware.com
Project-URL: Repository, https://github.com/exonware/xwapi
Project-URL: Documentation, https://github.com/exonware/xwapi#readme
Project-URL: Subtree, https://github.com/exonware/xwapi.git
Author-email: eXonware Backend Team <connect@exonware.com>
License: Apache-2.0
License-File: LICENSE
Keywords: actions,agent,api,client-server,exonware,fastapi,flask,graphql,oauth2,openapi,rest
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
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 :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: exonware-xwaction==0.9.0.12
Requires-Dist: exonware-xwdata==0.9.0.17
Requires-Dist: exonware-xwentity==0.6.0.11
Requires-Dist: exonware-xwschema==0.4.0.12
Requires-Dist: exonware-xwsystem==0.9.0.39
Requires-Dist: fastapi>=0.104.0
Requires-Dist: requests>=2.31.0
Requires-Dist: uvicorn[standard]>=0.24.0
Provides-Extra: dev
Requires-Dist: a2wsgi; extra == 'dev'
Requires-Dist: aiodns; extra == 'dev'
Requires-Dist: aiohttp; extra == 'dev'
Requires-Dist: atomicwrites; extra == 'dev'
Requires-Dist: attrs; extra == 'dev'
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: bottleneck; extra == 'dev'
Requires-Dist: brotli; extra == 'dev'
Requires-Dist: brotlicffi; extra == 'dev'
Requires-Dist: cachebox; extra == 'dev'
Requires-Dist: cachetools; extra == 'dev'
Requires-Dist: cbor2; extra == 'dev'
Requires-Dist: chardet; extra == 'dev'
Requires-Dist: cloudpickle; extra == 'dev'
Requires-Dist: cython; extra == 'dev'
Requires-Dist: dicttoxml; extra == 'dev'
Requires-Dist: exonware-xwaction==0.9.0.12; extra == 'dev'
Requires-Dist: exonware-xwaction[xw]==0.9.0.12; extra == 'dev'
Requires-Dist: exonware-xwauth==0.0.1.9; extra == 'dev'
Requires-Dist: exonware-xwauth[xw]==0.0.1.9; extra == 'dev'
Requires-Dist: exonware-xwdata==0.9.0.17; extra == 'dev'
Requires-Dist: exonware-xwdata[xw]==0.9.0.17; extra == 'dev'
Requires-Dist: exonware-xwentity==0.6.0.11; extra == 'dev'
Requires-Dist: exonware-xwentity[xw]==0.6.0.11; extra == 'dev'
Requires-Dist: exonware-xwschema==0.4.0.12; extra == 'dev'
Requires-Dist: exonware-xwschema[xw]==0.4.0.12; extra == 'dev'
Requires-Dist: exonware-xwstorage==0.0.1.7; extra == 'dev'
Requires-Dist: exonware-xwstorage[xw]==0.0.1.7; extra == 'dev'
Requires-Dist: exonware-xwsystem[full]==0.9.0.39; extra == 'dev'
Requires-Dist: httpx; extra == 'dev'
Requires-Dist: hyperlight-hyperjson; extra == 'dev'
Requires-Dist: interegular; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: json5; extra == 'dev'
Requires-Dist: lark; extra == 'dev'
Requires-Dist: lz4; extra == 'dev'
Requires-Dist: msgpack; extra == 'dev'
Requires-Dist: msgspec; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: numexpr; extra == 'dev'
Requires-Dist: numpy; extra == 'dev'
Requires-Dist: orjson; extra == 'dev'
Requires-Dist: pandas; extra == 'dev'
Requires-Dist: pyarrow; extra == 'dev'
Requires-Dist: pyjwt; extra == 'dev'
Requires-Dist: pylru; extra == 'dev'
Requires-Dist: pymongo; 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: python-multipart; extra == 'dev'
Requires-Dist: pytz; extra == 'dev'
Requires-Dist: regex; extra == 'dev'
Requires-Dist: rich; extra == 'dev'
Requires-Dist: scikit-learn; extra == 'dev'
Requires-Dist: simplejson; extra == 'dev'
Requires-Dist: socks; extra == 'dev'
Requires-Dist: tomli; extra == 'dev'
Requires-Dist: tomli-w; extra == 'dev'
Requires-Dist: uarray; extra == 'dev'
Requires-Dist: xmltodict; extra == 'dev'
Requires-Dist: zstandard; extra == 'dev'
Provides-Extra: full
Requires-Dist: a2wsgi; extra == 'full'
Requires-Dist: aiodns; extra == 'full'
Requires-Dist: aiohttp; extra == 'full'
Requires-Dist: atomicwrites; extra == 'full'
Requires-Dist: attrs; extra == 'full'
Requires-Dist: bottleneck; extra == 'full'
Requires-Dist: brotli; extra == 'full'
Requires-Dist: brotlicffi; extra == 'full'
Requires-Dist: cachebox; extra == 'full'
Requires-Dist: cachetools; extra == 'full'
Requires-Dist: cbor2; extra == 'full'
Requires-Dist: chardet; extra == 'full'
Requires-Dist: cloudpickle; extra == 'full'
Requires-Dist: cython; extra == 'full'
Requires-Dist: dicttoxml; extra == 'full'
Requires-Dist: exonware-xwaction==0.9.0.12; extra == 'full'
Requires-Dist: exonware-xwaction[xw]==0.9.0.12; extra == 'full'
Requires-Dist: exonware-xwauth==0.0.1.9; extra == 'full'
Requires-Dist: exonware-xwauth[xw]==0.0.1.9; extra == 'full'
Requires-Dist: exonware-xwdata==0.9.0.17; extra == 'full'
Requires-Dist: exonware-xwdata[xw]==0.9.0.17; extra == 'full'
Requires-Dist: exonware-xwentity==0.6.0.11; extra == 'full'
Requires-Dist: exonware-xwentity[xw]==0.6.0.11; extra == 'full'
Requires-Dist: exonware-xwschema==0.4.0.12; extra == 'full'
Requires-Dist: exonware-xwschema[xw]==0.4.0.12; extra == 'full'
Requires-Dist: exonware-xwstorage==0.0.1.7; extra == 'full'
Requires-Dist: exonware-xwstorage[xw]==0.0.1.7; extra == 'full'
Requires-Dist: exonware-xwsystem[full]==0.9.0.39; extra == 'full'
Requires-Dist: httpx; extra == 'full'
Requires-Dist: hyperlight-hyperjson; extra == 'full'
Requires-Dist: interegular; extra == 'full'
Requires-Dist: json5; extra == 'full'
Requires-Dist: lark; extra == 'full'
Requires-Dist: lz4; extra == 'full'
Requires-Dist: msgpack; extra == 'full'
Requires-Dist: msgspec; extra == 'full'
Requires-Dist: numexpr; extra == 'full'
Requires-Dist: numpy; extra == 'full'
Requires-Dist: orjson; extra == 'full'
Requires-Dist: pandas; extra == 'full'
Requires-Dist: pyarrow; extra == 'full'
Requires-Dist: pyjwt; extra == 'full'
Requires-Dist: pylru; extra == 'full'
Requires-Dist: pymongo; extra == 'full'
Requires-Dist: python-multipart; extra == 'full'
Requires-Dist: pytz; extra == 'full'
Requires-Dist: regex; extra == 'full'
Requires-Dist: rich; extra == 'full'
Requires-Dist: scikit-learn; extra == 'full'
Requires-Dist: simplejson; extra == 'full'
Requires-Dist: socks; extra == 'full'
Requires-Dist: tomli; extra == 'full'
Requires-Dist: tomli-w; extra == 'full'
Requires-Dist: uarray; extra == 'full'
Requires-Dist: xmltodict; extra == 'full'
Requires-Dist: zstandard; extra == 'full'
Provides-Extra: lazy
Requires-Dist: exonware-xwaction==0.9.0.12; extra == 'lazy'
Requires-Dist: exonware-xwaction[xw]==0.9.0.12; extra == 'lazy'
Requires-Dist: exonware-xwauth==0.0.1.9; extra == 'lazy'
Requires-Dist: exonware-xwauth[xw]==0.0.1.9; extra == 'lazy'
Requires-Dist: exonware-xwdata==0.9.0.17; extra == 'lazy'
Requires-Dist: exonware-xwdata[xw]==0.9.0.17; extra == 'lazy'
Requires-Dist: exonware-xwentity==0.6.0.11; extra == 'lazy'
Requires-Dist: exonware-xwentity[xw]==0.6.0.11; extra == 'lazy'
Requires-Dist: exonware-xwlazy==1.0.1.81; extra == 'lazy'
Requires-Dist: exonware-xwschema==0.4.0.12; extra == 'lazy'
Requires-Dist: exonware-xwschema[xw]==0.4.0.12; extra == 'lazy'
Requires-Dist: exonware-xwstorage==0.0.1.7; extra == 'lazy'
Requires-Dist: exonware-xwstorage[xw]==0.0.1.7; extra == 'lazy'
Requires-Dist: exonware-xwsystem[lazy]==0.9.0.39; extra == 'lazy'
Provides-Extra: xw
Requires-Dist: exonware-xwaction==0.9.0.12; extra == 'xw'
Requires-Dist: exonware-xwauth==0.0.1.9; extra == 'xw'
Requires-Dist: exonware-xwdata==0.9.0.17; extra == 'xw'
Requires-Dist: exonware-xwentity==0.6.0.11; extra == 'xw'
Requires-Dist: exonware-xwschema==0.4.0.12; extra == 'xw'
Requires-Dist: exonware-xwstorage==0.0.1.7; extra == 'xw'
Description-Content-Type: text/markdown

# xwapi

**Build once, publish anywhere.** `xwapi` is the entity- and **exposable-action** layer for eXonware: define `xwaction` operations and `xwentity` models once, then **publish** them over HTTP/OpenAPI (bots, consoles, and other adapters align to the same contracts). It also supports the **other direction** — **clients and agents** that **consume** those actions via `XWApiAgent` and related client engines.

Default HTTP engine is **FastAPI** (full OpenAPI/async ecosystem); **Flask** is a registered alternate so you can swap ASGI vs WSGI at app construction without rewriting actions. See [docs/REF_24_ALTERNATIVES.md](docs/REF_24_ALTERNATIVES.md) for comparable libraries and engine notes.

Beyond HTTP wiring: standardized errors, production middleware, durable action pipeline, API token lifecycle/metering.

*Longer guide: [README_LONG.md](README_LONG.md).*

**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 | When to use |
|---------|-------------|
| `pip install exonware-xwapi` | Core runtime |
| `pip install exonware-xwapi[lazy]` | Lazy dependency loading |
| `pip install exonware-xwapi[full]` | Full production dependency set |
| `pip install exonware-xwapi[engines-http]` | Optional HTTP engines (Starlette, Quart, Sanic, aiohttp, BlackSheep, Litestar, Django, Mangum) |

---

## 🚀 Quick start

```python
from exonware.xwapi import XWAPI
from exonware.xwentity import XWEntity


class User(XWEntity):
    name: str
    email: str
    age: int


api = XWAPI(entities=[User], title="My API", version="1.0.0")
app = api.create_app(engine="fastapi")
```

---

## 🆕 New production features

- **Engine-agnostic error contract:** `xwapi_error_to_http_parts` plus adapters keeps `XWAPIError` transport-neutral.
- **Outbox + singleton worker pipeline:** `ActionPipelineManager`, `AOutboxStore`/`InMemoryOutboxStore`, and `BackgroundWorker`.
- **API token lifecycle:** create/list/revoke tokens, usage tracking, balance/recharge, idempotent metering.
- **Provider abstractions:** `IAuthProvider`, `IStorageProvider`, `IPaymentProvider` with in-memory and library adapters.
- **API token middleware:** bearer verification, optional scope enforcement, deny-unmapped policy, usage metering via `Idempotency-Key`.
- **Admin/operations endpoints:** server status/health/pipeline controls and token admin endpoints.
- **Production guardrails:** environment-based admin token enforcement and admin read-protection support.

---

## 💻 Client side

Use **`XWApiAgent`** (and client engines) to discover `XWAction` methods, attach auth/session flows, and treat remote APIs as the consumer half of the same exposable-action model.

---

## 🔗 eXonware integration

`xwapi` now explicitly integrates with:

- `xwsystem` (serialization, logging/utilities)
- `xwaction` (action registration and execution)
- `xwentity` (entity-driven API surfaces)
- `xwschema` (schema validation/generation integration points)
- `xwdata` (data/serialization integration paths)

---

## 🌐 Ecosystem functional contributions

For `xwapi`, each XW library covers a specific feature and requirement boundary rather than acting as a generic dependency layer.
You can use `xwapi` standalone with its core install and existing non-XW components.
Adding more XW packages is optional and mainly useful when you want full enterprise and mission-critical infrastructure patterns under your own control.

| Supporting XW lib | What it provides to xwapi | Functional requirement it satisfies |
|------|----------------|----------------|
| **XWAction** | Metadata, registration, execution, and engine adapters for *exposable actions* (HTTP, and other surfaces). | Same business action from server publish to client consume; reusable across FastAPI/Flask engines. |
| **XWEntity** | Entity-first domain surface that xwapi can expose directly as API resources. | Stable domain contracts and lower boilerplate for CRUD/API scaffolding. |
| **XWSystem** | Shared error and runtime foundations (logging, config, async/helpers, transport-neutral utility layers). | Uniform API behavior across FastAPI/Flask/GraphQL/gRPC and predictable ops behavior in production. |
| **XWSchema** | Validation and schema integration points for request/response shaping and API contracts. | Strong input/output contract enforcement and safer API evolution. |
| **XWStorage** | Persistence abstraction used by server pipeline components and token/admin paths where durable state is needed. | Durable action/outbox/token workflows instead of in-memory-only behavior. |
| **XWAuth** | Authentication/authorization provider integrations used by middleware and protected routes. | API security requirements (token validation, authz boundaries, tenant-safe access). |
| **XWData** | Data transformation/serialization support for mixed payloads and format conversion paths. | Multi-format payload handling without duplicating conversion logic in endpoint code. |

This is the practical edge: one place composes **publish** (server) and **consume** (agent/client) paths around the same exposable actions, instead of stitching unrelated libraries per service.

---

## 📖 Docs and tests

- Start at [docs/INDEX.md](docs/INDEX.md).
- Alternatives + FastAPI/Flask engines: [docs/REF_24_ALTERNATIVES.md](docs/REF_24_ALTERNATIVES.md).
- Full engine registry: [docs/REF_25_ENGINES.md](docs/REF_25_ENGINES.md).
- API and architecture references: [docs/REF_15_API.md](docs/REF_15_API.md), [docs/REF_13_ARCH.md](docs/REF_13_ARCH.md).
- Test layers: `0.core`, `1.unit`, `2.integration`, `3.advance`.
- Full run: `python tests/runner.py`

---

## ⏱️ Async support

- Core runtime includes async methods across facade, token manager, middleware paths, and server actions.
- Async APIs are recommended for I/O-heavy and concurrent workloads.

---

Apache-2.0 - see [LICENSE](LICENSE). Homepage: https://exonware.com
Version: 0.9.0.8 | Updated: 13-Apr-2026

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