jsonql-py 0.1.0__tar.gz

jsonql_py-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,172 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Ruff check
+        run: ruff check src/ tests/
+
+      - name: Ruff format check
+        run: ruff format --check src/ tests/
+
+      - name: Mypy
+        run: mypy src/jsonql/
+
+  test:
+    runs-on: ubuntu-latest
+    needs: lint
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest --tb=short -q
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  integration:
+    runs-on: ubuntu-latest
+    needs: test
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: jsonql
+          POSTGRES_PASSWORD: password
+          POSTGRES_DB: jsonql_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U jsonql"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+
+    strategy:
+      fail-fast: false
+      matrix:
+        adapter:
+          - name: py-flask-simple
+            port: 9200
+            test-path: tests/unified
+          - name: py-flask-lifecycle
+            port: 9201
+            test-path: tests/unified/lifecycle
+          - name: py-fastapi-simple
+            port: 9202
+            test-path: tests/unified
+          - name: py-fastapi-lifecycle
+            port: 9203
+            test-path: tests/unified/lifecycle
+          - name: py-django-simple
+            port: 9204
+            test-path: tests/unified
+          - name: py-django-lifecycle
+            port: 9205
+            test-path: tests/unified/lifecycle
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: jsonql-py
+
+      - uses: actions/checkout@v4
+        with:
+          repository: JSONQL-Standard/jsonql-tests
+          token: ${{ secrets.JSONQL_TESTS_TOKEN }}
+          path: jsonql-tests
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install jsonql-py from source
+        run: pip install -e ./jsonql-py
+
+      - name: Install server dependencies
+        run: |
+          pip install flask fastapi uvicorn django djangorestframework
+          pip install psycopg2-binary pymysql pymssql pymongo
+
+      - name: Install test runner dependencies
+        run: pip install -r jsonql-tests/requirements.txt
+
+      - name: Start ${{ matrix.adapter.name }}
+        run: |
+          cd jsonql-tests/integration-tests/${{ matrix.adapter.name }}
+          PYTHONPATH=${{ github.workspace }}/jsonql-tests/integration-tests/py-shared \
+          DB_TYPE=postgres \
+          DB_DSN="host=localhost dbname=jsonql_test user=jsonql password=password" \
+          JSONQL_SCHEMA_PATH=${{ github.workspace }}/jsonql-tests/fixtures/standard/schema.json \
+          PORT=${{ matrix.adapter.port }} \
+          python server.py &
+          # Wait for server to be ready
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:${{ matrix.adapter.port }}/health > /dev/null 2>&1; then
+              echo "Server ready"
+              break
+            fi
+            sleep 2
+          done
+
+      - name: Run compliance tests against ${{ matrix.adapter.name }}
+        run: |
+          cd jsonql-tests
+          python -m pytest tests/ \
+            --target=http://localhost:${{ matrix.adapter.port }} \
+            --db-type=postgres \
+            --db-dsn="postgresql://jsonql:password@localhost:5432/jsonql_test" \
+            --test-path=${{ matrix.adapter.test-path }} \
+            -q --tb=short

jsonql_py-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,86 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+permissions:
+  contents: read
+  id-token: write  # Required for trusted publishing
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  test:
+    runs-on: ubuntu-latest
+    needs: build
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest --tb=short -q
+
+  publish-testpypi:
+    runs-on: ubuntu-latest
+    needs: [build, test]
+    environment: testpypi
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    if: ${{ !github.event.release.prerelease }}
+    runs-on: ubuntu-latest
+    needs: [build, test, publish-testpypi]
+    environment: pypi
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

jsonql_py-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.pyc
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/

jsonql_py-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 JSONQL-Standard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jsonql_py-0.1.0/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: jsonql-py
+Version: 0.1.0
+Summary: Python SDK for JSONQL — a JSON-based query language for SQL databases
+Project-URL: Homepage, https://github.com/JSONQL-Standard/jsonql-py
+Project-URL: Documentation, https://jsonql.org
+Project-URL: Repository, https://github.com/JSONQL-Standard/jsonql-py
+Project-URL: Issues, https://github.com/JSONQL-Standard/jsonql-py/issues
+Project-URL: Changelog, https://github.com/JSONQL-Standard/jsonql-py/blob/master/CHANGELOG.md
+Author: JSONQL Standard
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,jsonql,orm,query,sql
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=4.0; extra == 'django'
+Requires-Dist: djangorestframework>=3.14; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Requires-Dist: uvicorn>=0.20; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=2.0; extra == 'flask'
+Provides-Extra: mysql
+Requires-Dist: mysql-connector-python>=8.0; extra == 'mysql'
+Provides-Extra: postgres
+Requires-Dist: psycopg2-binary>=2.9; extra == 'postgres'
+Provides-Extra: sqlite
+Description-Content-Type: text/markdown
+
+# jsonql-py
+
+**Python SDK** for [JSONQL](https://github.com/jsonql-standard/jsonql-spec) — a JSON-based query language for SQL databases.
+
+## Installation
+
+```bash
+pip install jsonql-py
+```
+
+With framework extras:
+
+```bash
+pip install jsonql-py[flask]      # Flask adapter
+pip install jsonql-py[fastapi]    # FastAPI adapter
+pip install jsonql-py[django]     # Django REST adapter
+pip install jsonql-py[postgres]   # PostgreSQL driver support
+```
+
+## Quick Start
+
+### Query Builder
+
+```python
+from jsonql import QueryBuilder
+from jsonql.conditions import eq, gt, field, and_
+
+query = (
+    QueryBuilder()
+    .from_table("users")
+    .select("id", "name", "email")
+    .where(and_(
+        field("age", gt(18)),
+        field("status", eq("active")),
+    ))
+    .order_by("name", "-age")
+    .limit(10)
+    .build()
+)
+```
+
+### Mutation Builder
+
+```python
+from jsonql import MutationBuilder
+
+# Create
+mutation = MutationBuilder().create({"name": "Alice", "age": 30}).build()
+
+# Update
+mutation = (
+    MutationBuilder()
+    .update({"name": "Bob"})
+    .where({"id": {"eq": 1}})
+    .build()
+)
+
+# Delete
+mutation = MutationBuilder().delete().where({"id": {"eq": 1}}).build()
+```
+
+### Transpiler
+
+```python
+from jsonql import Parser, SQLTranspiler
+
+parser = Parser()
+query = parser.parse({
+    "fields": ["id", "name"],
+    "where": {"status": {"eq": "active"}},
+    "sort": ["-name"],
+    "limit": 10,
+})
+
+transpiler = SQLTranspiler("postgres")
+result = transpiler.transpile(query, "users")
+print(result.sql)   # SELECT "users"."id", "users"."name" FROM "users" WHERE "users"."status" = $1 ORDER BY "users"."name" DESC LIMIT 10
+print(result.args)  # ['active']
+```
+
+### Schema Validation
+
+```python
+from jsonql import Validator, JsonQLQuery
+from jsonql.types import JsonQLSchema, JsonQLTable, JsonQLField
+
+schema = JsonQLSchema(tables={
+    "users": JsonQLTable(fields={
+        "id": JsonQLField(type="integer"),
+        "name": JsonQLField(type="string"),
+        "secret": JsonQLField(type="string", allow_select=False),
+    }),
+})
+
+validator = Validator(schema, "users")
+
+# Returns ValidationResult
+result = validator.validate(JsonQLQuery(fields=["id", "name"]))
+assert result.valid
+
+# Raises JsonQLValidationError
+validator.validate_or_raise(JsonQLQuery(fields=["secret"]))
+```
+
+### Engine (Full Pipeline)
+
+```python
+import asyncio
+from jsonql import JsonQLEngine
+from jsonql.types import parse_schema
+
+schema = parse_schema({...})  # Your schema JSON
+
+async def run_sql(sql: str, params: list) -> list[dict]:
+    # Your database execution logic
+    ...
+
+engine = (
+    JsonQLEngine.builder()
+    .postgres()
+    .schema(schema)
+    .executor(run_sql)
+    .debug()
+    .build()
+)
+
+result = asyncio.run(engine.execute({"fields": ["id", "name"]}, "users"))
+print(result["data"])
+```
+
+### Flask Adapter
+
+```python
+from flask import Flask
+from jsonql.adapters import create_flask_blueprint, AdapterOptions
+
+app = Flask(__name__)
+
+bp = create_flask_blueprint(AdapterOptions(
+    dialect="sqlite",
+    execute=run_sql,
+    schema=my_schema,
+))
+app.register_blueprint(bp, url_prefix="/jsonql")
+```
+
+### FastAPI Adapter
+
+```python
+from fastapi import FastAPI
+from jsonql.adapters import create_fastapi_router, AdapterOptions
+
+app = FastAPI()
+
+router = create_fastapi_router(AdapterOptions(
+    dialect="postgres",
+    execute=run_sql,
+    schema=my_schema,
+))
+app.include_router(router, prefix="/jsonql")
+```
+
+### Django Adapter
+
+```python
+# urls.py
+from django.urls import path
+from jsonql.adapters import JsonQLDjangoView, AdapterOptions
+
+options = AdapterOptions(dialect="postgres", execute=run_sql, schema=my_schema)
+
+urlpatterns = [
+    path("jsonql/", JsonQLDjangoView.as_view(options=options)),
+    path("jsonql/<path:path>/", JsonQLDjangoView.as_view(options=options)),
+]
+```
+
+## Supported Dialects
+
+| Dialect    | Placeholder | Quoting    | RETURNING |
+|------------|-------------|------------|-----------|
+| `postgres` | `$1, $2`    | `"col"`    | ✅        |
+| `mysql`    | `?, ?`      | `` `col` ``| ❌        |
+| `sqlite`   | `?, ?`      | `"col"`    | ❌        |
+
+## Condition Helpers
+
+```python
+from jsonql.conditions import (
+    eq, neq, gt, gte, lt, lte,
+    is_in, not_in, like, contains, starts_with, ends_with,
+    field, and_, or_, not_,
+)
+```
+
+## Error Hierarchy
+
+```
+JsonQLError
+├── JsonQLValidationError   (code: VALIDATION_ERROR)
+├── JsonQLTranspileError    (code: TRANSPILE_ERROR)
+└── JsonQLExecutionError    (code: EXECUTION_ERROR)
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"  # import name is still 'jsonql'
+pytest
+ruff check src/ tests/
+mypy src/
+```
+
+## License
+
+MIT