jsonql-py 0.1.0__py3-none-any.whl

jsonql/__init__.py

@@ -0,0 +1,142 @@
+"""JSONQL Python SDK — A JSON-based query language for SQL databases."""
+
+from .builder import MutationBuilder, QueryBuilder
+from .conditions import (
+    and_,
+    contains,
+    ends_with,
+    eq,
+    field,
+    gt,
+    gte,
+    is_in,
+    like,
+    lt,
+    lte,
+    neq,
+    not_,
+    not_in,
+    or_,
+    starts_with,
+)
+from .dialect import (
+    MySQLDialect,
+    PostgresDialect,
+    SQLDialect,
+    SQLiteDialect,
+    new_dialect,
+)
+from .driver import DatabaseDriver
+from .engine import JsonQLEngine
+from .errors import (
+    AdapterError,
+    JsonQLError,
+    JsonQLExecutionError,
+    JsonQLTranspileError,
+    JsonQLValidationError,
+)
+from .factory import (
+    connect_mongo,
+    create_driver,
+    create_driver_with_dsn,
+    env_or,
+    load_schema,
+    must_connect_mongo,
+    must_load_schema,
+)
+from .hydrator import ResultHydrator
+from .logger import ConsoleLogger, Logger, NoOpLogger
+from .mongo_driver import MongoDBDriver
+from .mongo_transpiler import MongoResult, MongoTranspiler
+from .parser import Parser, ParserOptions
+from .transpiler import SQLTranspiler
+from .types import (
+    DistinctOption,
+    JsonQLField,
+    JsonQLMutation,
+    JsonQLQuery,
+    JsonQLRelation,
+    JsonQLSchema,
+    JsonQLSettings,
+    JsonQLTable,
+    TranspileResult,
+    ValidationError,
+    ValidationResult,
+    parse_schema,
+)
+from .validator import Validator
+
+__all__ = [
+    # Types
+    "JsonQLQuery",
+    "JsonQLMutation",
+    "DistinctOption",
+    "JsonQLSchema",
+    "JsonQLSettings",
+    "JsonQLTable",
+    "JsonQLField",
+    "JsonQLRelation",
+    "TranspileResult",
+    "ValidationError",
+    "ValidationResult",
+    "parse_schema",
+    # Core
+    "Parser",
+    "ParserOptions",
+    "SQLTranspiler",
+    "Validator",
+    "ResultHydrator",
+    # Dialect
+    "SQLDialect",
+    "PostgresDialect",
+    "MySQLDialect",
+    "SQLiteDialect",
+    "new_dialect",
+    # Builder
+    "QueryBuilder",
+    "MutationBuilder",
+    # Conditions
+    "eq",
+    "neq",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "is_in",
+    "not_in",
+    "like",
+    "contains",
+    "starts_with",
+    "ends_with",
+    "field",
+    "and_",
+    "or_",
+    "not_",
+    # Engine / Driver
+    "DatabaseDriver",
+    "JsonQLEngine",
+    # MongoDB
+    "MongoTranspiler",
+    "MongoResult",
+    "MongoDBDriver",
+    # Factory / Helpers
+    "env_or",
+    "load_schema",
+    "must_load_schema",
+    "create_driver",
+    "create_driver_with_dsn",
+    "connect_mongo",
+    "must_connect_mongo",
+    # Errors
+    "JsonQLError",
+    "JsonQLValidationError",
+    "JsonQLTranspileError",
+    "JsonQLExecutionError",
+    "AdapterError",
+    # Logger
+    "Logger",
+    "ConsoleLogger",
+    "NoOpLogger",
+]
+
+__version__ = "0.1.0"

jsonql/adapters/__init__.py

@@ -0,0 +1,42 @@
+"""JSONQL framework adapters — Flask, FastAPI, Django REST + MongoDB variants."""
+
+from ..errors import AdapterError
+from .base import (
+    AdapterOptions,
+    BaseHandler,
+)
+from .base import (
+    _infer_mutation as infer_mutation,
+)
+from .django_adapter import JsonQLDjangoView
+from .django_mongo import JsonQLDjangoMongoView
+from .fastapi_adapter import create_fastapi_router
+from .fastapi_mongo import create_fastapi_mongo_router
+from .flask_adapter import create_flask_blueprint
+from .flask_mongo import create_flask_mongo_blueprint
+from .mongo_base import (
+    MongoAdapterOptions,
+    MongoBaseHandler,
+    build_rest_mutation,
+    get_id_from_query,
+)
+
+__all__ = [
+    # SQL adapters
+    "BaseHandler",
+    "AdapterOptions",
+    "create_flask_blueprint",
+    "create_fastapi_router",
+    "JsonQLDjangoView",
+    # MongoDB adapters
+    "MongoBaseHandler",
+    "MongoAdapterOptions",
+    "create_flask_mongo_blueprint",
+    "create_fastapi_mongo_router",
+    "JsonQLDjangoMongoView",
+    # Shared helpers
+    "AdapterError",
+    "infer_mutation",
+    "get_id_from_query",
+    "build_rest_mutation",
+]

jsonql/adapters/base.py

@@ -0,0 +1,300 @@
+"""Framework-agnostic base handler for the JSONQL request pipeline.
+
+Subclasses only need to provide framework-specific input extraction
+and error creation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable
+
+from ..driver import DatabaseDriver
+from ..hydrator import ResultHydrator
+from ..logger import ConsoleLogger, Logger, NoOpLogger
+from ..parser import Parser
+from ..transpiler import SQLTranspiler
+from ..types import JsonQLMutation, JsonQLQuery, JsonQLSchema, is_mutation
+from ..validator import Validator
+
+# Type aliases for lifecycle hooks
+Hook = Callable[..., Any]
+
+
+@dataclass
+class AdapterOptions:
+    """Configuration for a JSONQL adapter."""
+
+    schema: JsonQLSchema | None = None
+    schema_resolver: Callable[..., JsonQLSchema | None] | None = None
+    driver: DatabaseDriver | None = None
+    execute: Callable[[str, list[Any]], Awaitable[list[dict[str, Any]]]] | None = None
+    dialect: str = "sqlite"
+
+    debug: bool = False
+    logger: Logger | None = None
+
+    tables: list[str] | dict[str, str] | None = None
+
+    # Mutation status resolver — determines HTTP status for mutations.
+    # Signature: (op: str, context: Any) -> int
+    # Default behaviour (when None): 201 for "create", 200 for update/delete.
+    mutation_status: Callable[[str, Any], int] | None = None
+
+    # Lifecycle hooks
+    before_parse: Hook | None = None
+    after_parse: Hook | None = None
+    before_query: Hook | None = None
+    before_validate: Hook | None = None
+    after_validate: Hook | None = None
+    before_hydrate: Hook | None = None
+    after_hydrate: Hook | None = None
+    after_query: Hook | None = None
+
+    # Mutation hooks
+    before_create: Hook | None = None
+    after_create: Hook | None = None
+    before_update: Hook | None = None
+    after_update: Hook | None = None
+    before_delete: Hook | None = None
+    after_delete: Hook | None = None
+
+
+# Re-export public helpers from mongo_base (shared between SQL and MongoDB)
+
+
+def _infer_mutation(http_method: str, raw: dict[str, Any]) -> dict[str, Any]:
+    """Inject ``op`` into the raw query based on the HTTP method."""
+    if "op" in raw:
+        return raw
+
+    if "create" in raw:
+        raw["op"] = "create"
+        if "data" not in raw:
+            raw["data"] = raw.get("create")
+        return raw
+    if "update" in raw:
+        raw["op"] = "update"
+        if "patch" not in raw:
+            raw["patch"] = raw.get("update")
+        return raw
+    if "delete" in raw:
+        raw["op"] = "delete"
+        return raw
+
+    upsert = raw.get("upsert")
+    if isinstance(upsert, dict):
+        if "where" in upsert and "update" in upsert:
+            raw["op"] = "update"
+            raw["where"] = upsert["where"]
+            raw["patch"] = upsert["update"]
+            return raw
+        if "create" in upsert:
+            raw["op"] = "create"
+            raw["data"] = upsert["create"]
+            return raw
+
+    method = http_method.upper()
+    if method == "POST" and "data" in raw:
+        raw["op"] = "create"
+    elif method in ("PUT", "PATCH") and ("patch" in raw or "where" in raw):
+        raw["op"] = "update"
+    elif method == "DELETE" and "where" in raw:
+        raw["op"] = "delete"
+    return raw
+
+
+class BaseHandler:
+    """Core pipeline: parse → validate → transpile → execute → hydrate."""
+
+    def __init__(self, options: AdapterOptions) -> None:
+        self.options = options
+        self.parser = Parser()
+        self.can_execute = bool(options.execute or options.driver)
+
+        dialect = options.dialect
+        if options.driver:
+            dialect = options.driver.dialect
+
+        self.transpiler = SQLTranspiler(dialect) if self.can_execute else None
+        self.hydrator = ResultHydrator() if self.can_execute else None
+
+        if options.logger:
+            self.logger: Logger = options.logger
+        elif options.debug:
+            self.logger = ConsoleLogger()
+        else:
+            self.logger = NoOpLogger()
+
+    async def process_request(
+        self,
+        raw_input: Any,
+        context: Any,
+        http_method: str,
+        path_name: str,
+    ) -> Any:
+        """Run the full JSONQL pipeline and return the result dict."""
+        raw_query = raw_input
+
+        # 1. beforeParse
+        if self.options.before_parse:
+            raw_query = await _await_maybe(self.options.before_parse(raw_query, context))
+
+        # 2. Infer mutation
+        if isinstance(raw_query, dict):
+            raw_query = _infer_mutation(http_method, raw_query)
+
+        # 3. Parse
+        statement = self.parser.parse(raw_query)
+
+        if self.options.after_parse:
+            statement = await _await_maybe(self.options.after_parse(statement, context))
+
+        # 4. Resolve table name
+        table_name: str | None = None
+        if isinstance(statement, JsonQLQuery):
+            table_name = statement.from_table or None
+        elif isinstance(statement, JsonQLMutation):
+            table_name = None  # mutations don't carry from_table
+
+        table_name = self._resolve_table(statement, table_name, path_name)
+
+        if isinstance(statement, JsonQLQuery) and table_name and not statement.from_table:
+            statement.from_table = table_name
+
+        # 5. beforeQuery
+        if self.options.before_query:
+            statement = await _await_maybe(self.options.before_query(statement, context))
+
+        # 6. beforeValidate
+        if self.options.before_validate:
+            statement = await _await_maybe(self.options.before_validate(statement, context))
+
+        # 7. Resolve schema
+        schema: JsonQLSchema | None = None
+        if self.options.schema_resolver:
+            schema = await _await_maybe(self.options.schema_resolver(context))
+        else:
+            schema = self.options.schema
+
+        # 8. Validate
+        if schema and table_name and isinstance(statement, JsonQLQuery):
+            table_def = schema.tables.get(table_name)
+            if table_def and table_def.fields:
+                validator = Validator(schema, table_name)
+                validation = validator.validate(statement)
+
+                if self.options.after_validate:
+                    await _await_maybe(self.options.after_validate(validation, context))
+
+                if not validation.valid:
+                    return {
+                        "error": "Validation Error",
+                        "details": [
+                            {"code": e.code, "message": e.message, "path": e.path}
+                            for e in validation.errors
+                        ],
+                    }, 400
+
+        # 9. Execute
+        if self.can_execute and self.transpiler and table_name:
+            is_mut = is_mutation(statement)
+
+            # Mutation before-hooks
+            if is_mut and isinstance(statement, JsonQLMutation):
+                if statement.op == "create" and self.options.before_create:
+                    statement = await _await_maybe(self.options.before_create(statement, context))
+                elif statement.op == "update" and self.options.before_update:
+                    statement = await _await_maybe(self.options.before_update(statement, context))
+                elif statement.op == "delete" and self.options.before_delete:
+                    statement = await _await_maybe(self.options.before_delete(statement, context))
+
+            # Transpile
+            result = self.transpiler.transpile(statement, table_name, schema)
+            self.logger.debug(f"[JSONQL] SQL: {result.sql}")
+            self.logger.debug(f"[JSONQL] Params: {result.args}")
+
+            # Execute
+            flat_rows: list[dict[str, Any]] = []
+            try:
+                if self.options.driver:
+                    flat_rows = await self.options.driver.query(result.sql, result.args)
+                elif self.options.execute:
+                    flat_rows = await self.options.execute(result.sql, result.args)
+            except Exception as exc:
+                self.logger.error(f"[JSONQL] Execution error: {exc}")
+                return {"error": "Execution Error", "details": str(exc)}, 400
+
+            # Mutation after-hooks
+            if is_mut and isinstance(statement, JsonQLMutation):
+                data: Any = {"meta": {"query": raw_input}, "data": flat_rows}
+                if statement.op == "create" and self.options.after_create:
+                    data = await _await_maybe(self.options.after_create(data, context))
+                elif statement.op == "update" and self.options.after_update:
+                    data = await _await_maybe(self.options.after_update(data, context))
+                elif statement.op == "delete" and self.options.after_delete:
+                    data = await _await_maybe(self.options.after_delete(data, context))
+                if self.options.after_query:
+                    data = await _await_maybe(self.options.after_query(data, context))
+
+                # Determine HTTP status: custom resolver → default 200
+                if self.options.mutation_status:
+                    status = await _await_maybe(
+                        self.options.mutation_status(statement.op or "", context)
+                    )
+                else:
+                    status = 200
+                return data, status
+
+            # Hydrate
+            if self.hydrator:
+                if self.options.before_hydrate:
+                    flat_rows = await _await_maybe(self.options.before_hydrate(flat_rows, context))
+
+                hydrated = self.hydrator.hydrate(flat_rows, schema, table_name)
+
+                if self.options.after_hydrate:
+                    hydrated = await _await_maybe(self.options.after_hydrate(hydrated, context))
+
+                result_data: Any = {"meta": {"query": raw_input}, "data": hydrated}
+                if self.options.after_query:
+                    result_data = await _await_maybe(self.options.after_query(result_data, context))
+                return result_data, 200
+
+        return None, 200
+
+    def _resolve_table(
+        self,
+        statement: Any,
+        table_name: str | None,
+        path_name: str,
+    ) -> str | None:
+        tables = self.options.tables
+
+        if tables is None:
+            return table_name or path_name or None
+
+        if isinstance(tables, list):
+            if not table_name:
+                table_name = path_name
+            if table_name not in tables:
+                raise ValueError(f"Table '{table_name}' is not allowed")
+            return table_name
+
+        # dict mapping
+        mapped = tables.get(path_name)
+        if mapped:
+            return mapped
+        if not path_name and table_name:
+            if table_name not in tables.values():
+                raise ValueError(f"Table '{table_name}' is not allowed")
+        return table_name
+
+
+async def _await_maybe(value: Any) -> Any:
+    """Await a value if it is a coroutine, otherwise return it directly."""
+    import asyncio
+
+    if asyncio.iscoroutine(value) or asyncio.isfuture(value):
+        return await value
+    return value

jsonql/adapters/django_adapter.py

@@ -0,0 +1,98 @@
+"""Django adapter — a class-based view for JSONQL.
+
+Usage::
+
+    # urls.py
+    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)),
+    ]
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any, ClassVar
+
+from ..errors import AdapterError, JsonQLError
+from .base import AdapterOptions, BaseHandler
+
+
+def _extract_raw_input(request: Any) -> Any:
+    """Extract the JSONQL query from a Django request.
+
+    - GET with ``?q=<json>`` → parse the JSON string
+    - GET without ``q``      → use query params as dict
+    - POST/PUT/PATCH/DELETE  → use the JSON body
+    """
+    if request.method == "GET":
+        q = request.GET.get("q")
+        if q:
+            try:
+                return json.loads(q)
+            except (ValueError, json.JSONDecodeError):
+                return q
+        if request.GET:
+            return dict(request.GET)
+        return {}
+    try:
+        return json.loads(request.body) if request.body else {}
+    except (json.JSONDecodeError, ValueError):
+        return {}
+
+
+class JsonQLDjangoView:
+    """Django class-based view for JSONQL.
+
+    Designed to work with or without Django REST Framework.
+    """
+
+    options: ClassVar[AdapterOptions]
+
+    def __init__(self, **kwargs: Any) -> None:
+        self._handler: BaseHandler | None = None
+        for key, value in kwargs.items():
+            setattr(self, key, value)
+
+    @classmethod
+    def as_view(cls, *, options: AdapterOptions | None = None, **initkwargs: Any) -> Any:
+        """Return a Django view function."""
+        from django.http import JsonResponse
+
+        handler = BaseHandler(options or cls.options)
+
+        def _run(coro: Any) -> Any:
+            loop = asyncio.new_event_loop()
+            try:
+                return loop.run_until_complete(coro)
+            finally:
+                loop.close()
+
+        def view(request: Any, path: str = "", **kwargs: Any) -> Any:
+            try:
+                raw_input = _extract_raw_input(request)
+                result, status = _run(
+                    handler.process_request(raw_input, request, request.method, path)
+                )
+                return JsonResponse(result, status=status, safe=False)
+            except AdapterError as exc:
+                return JsonResponse({"error": str(exc)}, status=exc.status)
+            except (ValueError, TypeError, JsonQLError) as exc:
+                return JsonResponse({"error": str(exc)}, status=400)
+            except Exception as exc:
+                if handler.logger:
+                    handler.logger.error(f"[JSONQL] Unhandled error: {exc}")
+                return JsonResponse({"error": str(exc)}, status=500)
+
+        from django.views.decorators.csrf import csrf_exempt
+
+        return csrf_exempt(view)

jsonql/adapters/django_mongo.py

@@ -0,0 +1,94 @@
+"""Django adapter for MongoDB — a class-based view for JSONQL.
+
+Usage::
+
+    # urls.py
+    from jsonql.adapters import JsonQLDjangoMongoView, MongoAdapterOptions
+    from jsonql import must_connect_mongo, must_load_schema
+
+    client, db = must_connect_mongo("mongodb://localhost:27017", "mydb")
+    schema = must_load_schema("schema.json")
+
+    options = MongoAdapterOptions(database=db, schema=schema)
+
+    urlpatterns = [
+        path("jsonql/", JsonQLDjangoMongoView.as_view(options=options)),
+        path("jsonql/<path:path>/", JsonQLDjangoMongoView.as_view(options=options)),
+    ]
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any, ClassVar
+
+from ..errors import AdapterError, JsonQLError
+from .mongo_base import MongoAdapterOptions, MongoBaseHandler
+
+
+def _extract_raw_input(request: Any) -> Any:
+    """Extract the JSONQL query from a Django request.
+
+    - GET with ``?q=<json>`` → parse the JSON string
+    - GET without ``q``      → use query params as dict
+    - POST/PUT/PATCH/DELETE  → use the JSON body
+    """
+    if request.method == "GET":
+        q = request.GET.get("q")
+        if q:
+            try:
+                return json.loads(q)
+            except (ValueError, json.JSONDecodeError):
+                return q
+        if request.GET:
+            return dict(request.GET)
+        return {}
+    try:
+        return json.loads(request.body) if request.body else {}
+    except (json.JSONDecodeError, ValueError):
+        return {}
+
+
+class JsonQLDjangoMongoView:
+    """Django class-based view for JSONQL with MongoDB."""
+
+    options: ClassVar[MongoAdapterOptions]
+
+    def __init__(self, **kwargs: Any) -> None:
+        for key, value in kwargs.items():
+            setattr(self, key, value)
+
+    @classmethod
+    def as_view(cls, *, options: MongoAdapterOptions | None = None, **initkwargs: Any) -> Any:
+        """Return a Django view function."""
+        from django.http import JsonResponse
+
+        handler = MongoBaseHandler(options or cls.options)
+
+        def _run(coro: Any) -> Any:
+            loop = asyncio.new_event_loop()
+            try:
+                return loop.run_until_complete(coro)
+            finally:
+                loop.close()
+
+        def view(request: Any, path: str = "", **kwargs: Any) -> Any:
+            try:
+                raw_input = _extract_raw_input(request)
+                result, status = _run(
+                    handler.process_request(raw_input, request, request.method, path)
+                )
+                return JsonResponse(result, status=status, safe=False)
+            except AdapterError as exc:
+                return JsonResponse({"error": str(exc)}, status=exc.status)
+            except (ValueError, TypeError, JsonQLError) as exc:
+                return JsonResponse({"error": str(exc)}, status=400)
+            except Exception as exc:
+                if handler.logger:
+                    handler.logger.error(f"[JSONQL] Unhandled error: {exc}")
+                return JsonResponse({"error": str(exc)}, status=500)
+
+        from django.views.decorators.csrf import csrf_exempt
+
+        return csrf_exempt(view)