Metadata-Version: 2.4
Name: exonware-xwquery
Version: 0.9.0.13
Summary: Universal query language for data structures - 50+ operations, 35+ format converters
Project-URL: Homepage, https://exonware.com
Project-URL: Repository, https://github.com/exonware/xwquery
Project-URL: Documentation, https://github.com/exonware/xwquery#readme
Author-email: eXonware Backend Team <connect@exonware.com>
License: Apache-2.0
License-File: LICENSE
Keywords: conversion,cypher,data,exonware,graphql,query,sparql,sql
Requires-Python: >=3.12
Requires-Dist: exonware-xwnode
Requires-Dist: exonware-xwsyntax
Requires-Dist: exonware-xwsystem
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: exonware-xwdata; extra == 'dev'
Requires-Dist: exonware-xwdata[xw]; extra == 'dev'
Requires-Dist: exonware-xwjson; extra == 'dev'
Requires-Dist: exonware-xwjson[xw]; extra == 'dev'
Requires-Dist: exonware-xwnode; extra == 'dev'
Requires-Dist: exonware-xwnode[xw]; extra == 'dev'
Requires-Dist: exonware-xwsyntax; extra == 'dev'
Requires-Dist: exonware-xwsyntax[xw]; extra == 'dev'
Requires-Dist: exonware-xwsystem[full]; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: jsonpath-ng>=1.6.0; extra == 'dev'
Requires-Dist: mypy>=1.0.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: tomli>=2.0.0; extra == 'dev'
Provides-Extra: full
Requires-Dist: exonware-xwdata; extra == 'full'
Requires-Dist: exonware-xwdata[xw]; extra == 'full'
Requires-Dist: exonware-xwjson; extra == 'full'
Requires-Dist: exonware-xwjson[xw]; extra == 'full'
Requires-Dist: exonware-xwnode; extra == 'full'
Requires-Dist: exonware-xwnode[xw]; extra == 'full'
Requires-Dist: exonware-xwsyntax; extra == 'full'
Requires-Dist: exonware-xwsyntax[xw]; extra == 'full'
Requires-Dist: exonware-xwsystem[full]; extra == 'full'
Requires-Dist: jsonpath-ng>=1.6.0; extra == 'full'
Requires-Dist: tomli>=2.0.0; extra == 'full'
Provides-Extra: lazy
Requires-Dist: exonware-xwdata; extra == 'lazy'
Requires-Dist: exonware-xwdata[xw]; extra == 'lazy'
Requires-Dist: exonware-xwjson; extra == 'lazy'
Requires-Dist: exonware-xwjson[xw]; extra == 'lazy'
Requires-Dist: exonware-xwlazy; extra == 'lazy'
Requires-Dist: exonware-xwnode; extra == 'lazy'
Requires-Dist: exonware-xwnode[xw]; extra == 'lazy'
Requires-Dist: exonware-xwsyntax; extra == 'lazy'
Requires-Dist: exonware-xwsyntax[xw]; extra == 'lazy'
Requires-Dist: exonware-xwsystem[lazy]; extra == 'lazy'
Provides-Extra: xw
Requires-Dist: exonware-xwdata; extra == 'xw'
Requires-Dist: exonware-xwjson; extra == 'xw'
Requires-Dist: exonware-xwnode; extra == 'xw'
Requires-Dist: exonware-xwsyntax; extra == 'xw'
Description-Content-Type: text/markdown

# xwquery

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

Query and transform native Python data structures with one API: SQL-style scripts, graph patterns, aggregations, and 35+ alternate surface syntaxes (Cypher, GraphQL, JMESPath, and others). It works directly with dictionaries, lists, and mixed in-memory structures; xwnode, xwdata, and xwentity integrations are optional add-ons when you want deeper stack features.

## 📦 Install

```bash
pip install exonware-xwquery
pip install exonware-xwquery[lazy]
pip install exonware-xwquery[full]
```

## 🚀 Basic usage

```python
from exonware.xwquery import XWQuery

data = {'users': [
    {'name': 'Alice', 'age': 30, 'city': 'NYC'},
    {'name': 'Bob', 'age': 25, 'city': 'LA'},
    {'name': 'Charlie', 'age': 35, 'city': 'NYC'}
]}

result = XWQuery.execute("""
    SELECT name, age
    FROM users
    WHERE age > 25 AND city = 'NYC'
""", data)

print(result)
# [{'name': 'Alice', 'age': 30}, {'name': 'Charlie', 'age': 35}]
```

## ✨ What you get

- **Broad operation set** - Core CRUD (SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP), filtering (WHERE, FILTER, LIKE, IN, RANGE, …), aggregation (GROUP BY, HAVING, SUM, COUNT, …), graph helpers (MATCH, PATH, …), and advanced pieces (JOIN, UNION, WITH, WINDOW, PIPE, …).
- **Many input languages** - Strategies for SQL-family dialects, Cypher/Gremlin/SPARQL/GraphQL, document and log query languages (MQL, Elasticsearch DSL, PromQL, Flux, …), and more. Parse or convert between them where supported.
- **Structure-aware execution** - The engine can adapt work to linear, tree, graph, or hybrid shapes when the backend exposes that metadata.

```python
linear_data = [1, 2, 3, 4, 5]
tree_data = {'a': 1, 'b': 2, 'c': 3}
graph_data = {'nodes': [...], 'edges': [...]}

XWQuery.execute("SELECT * WHERE value > 2", linear_data)
XWQuery.execute("SELECT * WHERE key BETWEEN 'a' AND 'c'", tree_data)
XWQuery.execute("MATCH (n)-[r]->(m)", graph_data)
```

## 📄 Script examples

```xquery
SELECT name, email, age FROM users WHERE age >= 18;

SELECT department, COUNT(*) AS employee_count, AVG(salary) AS avg_salary
FROM employees
GROUP BY department
HAVING avg_salary > 50000;

MATCH (u:User)-[:FRIENDS_WITH]->(f:User)
WHERE u.age > 25
RETURN u.name, f.name;
```

## 🔄 Format conversion

```python
sql_query = "SELECT id, name FROM users WHERE age > 25"
graphql = XWQuery.convert(sql_query, from_format='sql', to_format='graphql')

cypher_query = "MATCH (u:User)-[:WORKS_AT]->(c:Company) RETURN u.name, c.name"
sql = XWQuery.convert(cypher_query, from_format='cypher', to_format='sql')

any_query = XWQuery.parse(query_string)
target_format = any_query.to_format('mongodb')
```

## 🔗 Stack integration

**xwnode**

```python
from exonware.xwnode import XWNode
from exonware.xwquery import XWQuery

node = XWNode.from_native({'users': [...]})
result = XWQuery.execute("SELECT * FROM users WHERE active = true", node)
```

**xwdata**

```python
from exonware.xwdata import XWData
from exonware.xwquery import XWQuery

data = XWData.load('users.json')
filtered = XWQuery.execute("SELECT * WHERE age > 18", data)
filtered.save('adults.xml')
```

**xwentity**

```python
from exonware.xwentity import XWEntity
from exonware.xwquery import XWQuery

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

users = XWQuery.execute("SELECT * FROM User WHERE age > 18")
```

## 🌐 Ecosystem functional contributions

`xwquery` provides query execution; sibling XW libraries provide data shapes, domain contracts, and persistence targets that those queries operate on.
You can use `xwquery` standalone over native Python data structures without the full XW stack.
Broader XW integration is optional and mainly intended for enterprise and mission-critical query infrastructure where unified storage/schema/domain contracts are required.

| Supporting XW lib | What it provides to xwquery workflows | Functional requirement it satisfies |
|------|----------------|----------------|
| **XWNode** | Graph/tree/list strategy abstractions and structural metadata. | Shape-aware execution planning across linear, tree, and graph data. |
| **XWData** | Multi-format data ingestion/export around query execution. | Querying heterogeneous input/output formats with one pipeline. |
| **XWEntity** | Entity/domain model surfaces that can be queried directly. | Domain-level querying rather than raw structure-only filtering. |
| **XWStorage** | Backend persistence/query integration for stored datasets. | Query execution against durable data, not only in-memory objects. |
| **XWSchema** | Optional schema validation before/after query transformations. | Safer transformations and contract compliance in pipelines. |
| **XWSystem** | Shared runtime and utility infrastructure used by parsers/executors. | Consistent execution behavior and lower operational duplication. |

Competitive edge: `xwquery` unifies many query syntaxes while remaining tightly connected to structure, schema, and storage layers in the same ecosystem.

## 📖 Docs

- [docs/INDEX.md](docs/INDEX.md) - full map  
- [docs/GUIDE_01_USAGE.md](docs/GUIDE_01_USAGE.md) - usage  
- [docs/REF_15_API.md](docs/REF_15_API.md) - API  
- [docs/REF_13_ARCH.md](docs/REF_13_ARCH.md) - architecture  
- [docs/PROJECT_PHASES.md](docs/PROJECT_PHASES.md) - phases and roadmap  
- [docs/REF_51_TEST.md](docs/REF_51_TEST.md) - tests  

## 🛠️ Development

```bash
pip install -e .
python tests/runner.py
python tests/runner.py --core
python tests/runner.py --unit
python tests/runner.py --integration
```

## 📜 License

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

## 🌐 Ecosystem

- [xwsystem](https://github.com/exonware/xwsystem)  
- [xwnode](https://github.com/exonware/xwnode)  
- [xwquery](https://github.com/exonware/xwquery) (this repo)  
- [xwdata](https://github.com/exonware/xwdata)  
- [xwschema](https://github.com/exonware/xwschema)  
- [xwaction](https://github.com/exonware/xwaction)  
- [xwentity](https://github.com/exonware/xwentity)  
- [xwstorage](https://github.com/exonware/xwstorage)  
- [xwbase](https://github.com/exonware/xwbase)  

## ⏱️ Async Support

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

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