mygenx-fastql 0.0.1__tar.gz

mygenx_fastql-0.0.1/.gitignore

@@ -0,0 +1,13 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+
+# Virtual environments
+.venv/
+venv/
+
+# Build
+/build/
+/dist/

mygenx_fastql-0.0.1/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## Unreleased
+
+### Added
+
+- A shared dependency-free GraphQL-over-HTTP handler and request-aware `HTTPContext`.
+- Generic ASGI, Starlette, FastAPI, Flask, and Django integrations.
+- Independent `asgi`, `starlette`, `fastapi`, `flask`, and `django` installation extras, plus `all`.
+- Configurable GraphiQL, SDL, and introspection routes for production adapters.
+
+### Deferred
+
+- WebSocket subscriptions, multipart uploads, batching, persisted queries, and incremental delivery remain outside the initial integration contract.

mygenx_fastql-0.0.1/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: mygenx-fastql
+Version: 0.0.1
+Summary: A code-first, decorator-driven GraphQL framework for Python with a hand-built engine and a web-framework-agnostic core.
+Project-URL: Homepage, https://github.com/MyGenX/FastQL
+Project-URL: Documentation, https://github.com/MyGenX/FastQL/tree/main/docs
+Project-URL: Repository, https://github.com/MyGenX/FastQL
+Project-URL: Issues, https://github.com/MyGenX/FastQL/issues
+Author: FastQL
+License: MIT
+Keywords: async,decorators,framework-agnostic,graphql,schema
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: all
+Requires-Dist: django<6,>=5.2; extra == 'all'
+Requires-Dist: fastapi<1,>=0.129; extra == 'all'
+Requires-Dist: flask<4,>=3.1; extra == 'all'
+Requires-Dist: starlette<2,>=0.50; extra == 'all'
+Provides-Extra: asgi
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: hatchling>=1.26; extra == 'dev'
+Requires-Dist: httpx>=0.28; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django<6,>=5.2; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: fastapi<1,>=0.129; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask<4,>=3.1; extra == 'flask'
+Provides-Extra: starlette
+Requires-Dist: starlette<2,>=0.50; extra == 'starlette'
+Description-Content-Type: text/markdown
+
+# FastQL
+
+A code-first, decorator-driven GraphQL framework for Python with a **hand-built engine**
+(lexer → parser → validator → executor), a built-in **dependency-injection / context** layer,
+and a **web-framework-agnostic core** — zero runtime dependencies, Python 3.11+.
+
+> Status: early development. The core engine (parse → build → validate → execute, with
+> dependency injection and introspection) is in place.
+
+**Documentation:** Start with the [FastQL documentation](docs/index.mdx), then use the
+[capability catalog](docs/specifications/capability-catalog.mdx) to trace documented
+behavior to its canonical OpenSpec requirements.
+
+## Quickstart
+
+Define types and operations with decorators — field and argument types come from your
+Python type hints. Resolvers are plain functions; the executor injects arguments, the
+parent object, resolve `info`, and the `Context` based on each resolver's signature.
+
+```python
+import asyncio
+from typing import Annotated
+from fastql import Argument, Context, Field, Query, Schema, Type, execute
+
+
+@Type
+class User:                  # just fields — constructor/repr/eq are auto-generated
+    id: int
+    full_name: str
+
+    @Field
+    def loud_name(self) -> str:   # exposed as loudName by default
+        return self.full_name.upper()
+
+
+class AppContext(Context):
+    def __init__(self, users):
+        self.users = users
+
+
+@Query                       # group related queries on a class…
+class Queries:
+    @Field
+    async def user(
+        self,
+        user_id: Annotated[int, Argument(name="id")],
+        ctx: Context,
+    ) -> "User | None":
+        return ctx.users.get(user_id)
+
+    @Field
+    def ping(self) -> str:    # sync resolvers work alongside async ones
+        return "pong"
+
+
+schema = Schema(query=Queries)
+
+
+async def main():
+    ctx = AppContext(users={1: User(1, "Ada Lovelace")})
+    result = await execute(schema, "{ user(id: 1) { id fullName loudName } ping }", context=ctx)
+    print(result.data)       # {'user': {'id': 1, 'fullName': 'Ada Lovelace', 'loudName': 'ADA LOVELACE'}, 'ping': 'pong'}
+
+
+asyncio.run(main())
+```
+
+`@Type` and `@Input` classes get generated constructors, `repr`, and equality unless they define
+their own methods. Python snake_case fields and arguments become GraphQL camelCase by default;
+pass `SchemaConfig(auto_camel_case=False)` to `Schema` to preserve Python names. Explicit `name=`
+metadata always wins. `build_schema()` remains available for applications that intentionally merge
+multiple globally decorated root classes.
+
+`execute` returns an `ExecutionResult` with `data`, `errors`, and `extensions`, and a
+`.formatted()` helper that produces the GraphQL-over-HTTP response shape. Introspection
+(`__schema`, `__type`, `__typename`) is built in.
+
+A fuller, runnable version — covering every type kind, mutations, subscriptions,
+DataLoaders, permissions, and extensions — lives in [`examples/app`](examples/app), the
+showcase schema that the per-framework projects under [`examples/projects`](examples/projects)
+all reuse.
+
+The documentation quickstart and first-schema examples are also executed by the test
+suite from [`docs/snippets`](docs/snippets).
+
+## Dev server & playground
+
+Try a schema in the browser with the built-in, zero-dependency dev server:
+
+```bash
+python -m fastql serve examples.app:schema      # http://127.0.0.1:7691
+```
+
+It serves, on the default port **7691**:
+
+| Route             | Description                                  |
+| ----------------- | -------------------------------------------- |
+| `GET /`           | GraphiQL IDE (loaded from CDN)               |
+| `POST/GET /graphql` | the GraphQL endpoint (`{data, errors}` JSON) |
+| `GET /schema.graphql` | the schema as SDL                        |
+| `GET /schema.json`    | the schema as an introspection result    |
+
+Override the binding with `--host` / `--port`. If your resolvers need a `Context`,
+point `--context` at a value or zero-arg factory:
+
+```bash
+python -m fastql serve examples.app:schema --context examples.app:make_context
+```
+
+Or call it programmatically:
+
+```python
+import fastql
+from examples.app import schema, make_context
+
+fastql.serve(schema, port=7691, context_factory=make_context)  # blocking; Ctrl-C to stop
+```
+
+The dev server lives outside the agnostic core (in `fastql.server`) and only
+consumes `build_schema` / `execute` — it is a developer convenience, not a
+production transport (no TLS, auth, or subscriptions).
+
+## Design at a glance
+
+```
+@Type / @Input / root class decorators  ← unified type-hint-driven authoring
+        ▼
+Schema(query=...) / build_schema()       ← compiles decorators into the type-system IR
+        ▼
+Type-system IR (Schema, ObjectType, Field, scalars, wrappers)
+        ▼
+execute() ── validation ── coercion ── async resolution + DI/context
+        ▲
+language: Source → Lexer → Parser → AST  ← hand-built front-end
+```
+
+The core never imports an HTTP framework. Transports (an optional built-in dev server,
+plus FastAPI/Django/Flask/ASGI adapters) plug in on top and consume `build_schema` / `execute`.
+
+## Web framework integrations
+
+Install only the framework adapter an application uses:
+
+```bash
+pip install mygenx-fastql[fastapi]   # or starlette, flask, django
+```
+
+```python
+from fastapi import FastAPI
+from fastql.integrations.fastapi import create_fastapi_router
+
+app = FastAPI()
+app.include_router(create_fastapi_router(schema, graphiql=True))
+```
+
+The base installation includes the dependency-free `GraphQLASGI` adapter. See
+the [integration documentation](docs/integrations/overview.mdx) for mounting,
+request context, endpoint configuration, and supported versions.
+
+Runnable per-framework projects — FastAPI, Starlette, Flask, Django, and raw ASGI, each
+mounting the **same** [`examples/app`](examples/app) schema — live under
+[`examples/projects`](examples/projects). Reusing one schema across every adapter is the
+proof that the core is framework-agnostic; each project differs only in a few lines of glue.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

mygenx_fastql-0.0.1/README.md

@@ -0,0 +1,170 @@
+# FastQL
+
+A code-first, decorator-driven GraphQL framework for Python with a **hand-built engine**
+(lexer → parser → validator → executor), a built-in **dependency-injection / context** layer,
+and a **web-framework-agnostic core** — zero runtime dependencies, Python 3.11+.
+
+> Status: early development. The core engine (parse → build → validate → execute, with
+> dependency injection and introspection) is in place.
+
+**Documentation:** Start with the [FastQL documentation](docs/index.mdx), then use the
+[capability catalog](docs/specifications/capability-catalog.mdx) to trace documented
+behavior to its canonical OpenSpec requirements.
+
+## Quickstart
+
+Define types and operations with decorators — field and argument types come from your
+Python type hints. Resolvers are plain functions; the executor injects arguments, the
+parent object, resolve `info`, and the `Context` based on each resolver's signature.
+
+```python
+import asyncio
+from typing import Annotated
+from fastql import Argument, Context, Field, Query, Schema, Type, execute
+
+
+@Type
+class User:                  # just fields — constructor/repr/eq are auto-generated
+    id: int
+    full_name: str
+
+    @Field
+    def loud_name(self) -> str:   # exposed as loudName by default
+        return self.full_name.upper()
+
+
+class AppContext(Context):
+    def __init__(self, users):
+        self.users = users
+
+
+@Query                       # group related queries on a class…
+class Queries:
+    @Field
+    async def user(
+        self,
+        user_id: Annotated[int, Argument(name="id")],
+        ctx: Context,
+    ) -> "User | None":
+        return ctx.users.get(user_id)
+
+    @Field
+    def ping(self) -> str:    # sync resolvers work alongside async ones
+        return "pong"
+
+
+schema = Schema(query=Queries)
+
+
+async def main():
+    ctx = AppContext(users={1: User(1, "Ada Lovelace")})
+    result = await execute(schema, "{ user(id: 1) { id fullName loudName } ping }", context=ctx)
+    print(result.data)       # {'user': {'id': 1, 'fullName': 'Ada Lovelace', 'loudName': 'ADA LOVELACE'}, 'ping': 'pong'}
+
+
+asyncio.run(main())
+```
+
+`@Type` and `@Input` classes get generated constructors, `repr`, and equality unless they define
+their own methods. Python snake_case fields and arguments become GraphQL camelCase by default;
+pass `SchemaConfig(auto_camel_case=False)` to `Schema` to preserve Python names. Explicit `name=`
+metadata always wins. `build_schema()` remains available for applications that intentionally merge
+multiple globally decorated root classes.
+
+`execute` returns an `ExecutionResult` with `data`, `errors`, and `extensions`, and a
+`.formatted()` helper that produces the GraphQL-over-HTTP response shape. Introspection
+(`__schema`, `__type`, `__typename`) is built in.
+
+A fuller, runnable version — covering every type kind, mutations, subscriptions,
+DataLoaders, permissions, and extensions — lives in [`examples/app`](examples/app), the
+showcase schema that the per-framework projects under [`examples/projects`](examples/projects)
+all reuse.
+
+The documentation quickstart and first-schema examples are also executed by the test
+suite from [`docs/snippets`](docs/snippets).
+
+## Dev server & playground
+
+Try a schema in the browser with the built-in, zero-dependency dev server:
+
+```bash
+python -m fastql serve examples.app:schema      # http://127.0.0.1:7691
+```
+
+It serves, on the default port **7691**:
+
+| Route             | Description                                  |
+| ----------------- | -------------------------------------------- |
+| `GET /`           | GraphiQL IDE (loaded from CDN)               |
+| `POST/GET /graphql` | the GraphQL endpoint (`{data, errors}` JSON) |
+| `GET /schema.graphql` | the schema as SDL                        |
+| `GET /schema.json`    | the schema as an introspection result    |
+
+Override the binding with `--host` / `--port`. If your resolvers need a `Context`,
+point `--context` at a value or zero-arg factory:
+
+```bash
+python -m fastql serve examples.app:schema --context examples.app:make_context
+```
+
+Or call it programmatically:
+
+```python
+import fastql
+from examples.app import schema, make_context
+
+fastql.serve(schema, port=7691, context_factory=make_context)  # blocking; Ctrl-C to stop
+```
+
+The dev server lives outside the agnostic core (in `fastql.server`) and only
+consumes `build_schema` / `execute` — it is a developer convenience, not a
+production transport (no TLS, auth, or subscriptions).
+
+## Design at a glance
+
+```
+@Type / @Input / root class decorators  ← unified type-hint-driven authoring
+        ▼
+Schema(query=...) / build_schema()       ← compiles decorators into the type-system IR
+        ▼
+Type-system IR (Schema, ObjectType, Field, scalars, wrappers)
+        ▼
+execute() ── validation ── coercion ── async resolution + DI/context
+        ▲
+language: Source → Lexer → Parser → AST  ← hand-built front-end
+```
+
+The core never imports an HTTP framework. Transports (an optional built-in dev server,
+plus FastAPI/Django/Flask/ASGI adapters) plug in on top and consume `build_schema` / `execute`.
+
+## Web framework integrations
+
+Install only the framework adapter an application uses:
+
+```bash
+pip install mygenx-fastql[fastapi]   # or starlette, flask, django
+```
+
+```python
+from fastapi import FastAPI
+from fastql.integrations.fastapi import create_fastapi_router
+
+app = FastAPI()
+app.include_router(create_fastapi_router(schema, graphiql=True))
+```
+
+The base installation includes the dependency-free `GraphQLASGI` adapter. See
+the [integration documentation](docs/integrations/overview.mdx) for mounting,
+request context, endpoint configuration, and supported versions.
+
+Runnable per-framework projects — FastAPI, Starlette, Flask, Django, and raw ASGI, each
+mounting the **same** [`examples/app`](examples/app) schema — live under
+[`examples/projects`](examples/projects). Reusing one schema across every adapter is the
+proof that the core is framework-agnostic; each project differs only in a few lines of glue.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

mygenx_fastql-0.0.1/fastql/__init__.py

@@ -0,0 +1,143 @@
+"""FastQL — a code-first, decorator-driven GraphQL framework for Python.
+
+Define types and operations with decorators, build a schema, and execute
+operations — all without any web framework. The core turns Python values into a
+:class:`~fastql.types.schema.Schema` and runs operations through a hand-built,
+async-first engine.
+
+    from fastql import Type, Query, Schema, Context, execute
+
+    @Type
+    class User:
+        id: int
+        name: str
+
+    @Query
+    class QueryRoot:
+        @Field
+        async def user(self, id: int, ctx: Context) -> "User":
+            return ctx.users[id]
+
+    schema = Schema(query=QueryRoot)
+    result = await execute(schema, "{ user(id: 1) { id name } }", context=ctx)
+"""
+
+from fastql.context import (
+    Context,
+    Info,
+    ResolveInfo,
+    provides,
+    register_dependency,
+)
+from fastql.dataloader import DataLoader, DataLoaderError, get_loader
+from fastql.decorators import (
+    Arg,
+    Argument,
+    BasePermission,
+    Enum,
+    Field,
+    FieldExtension,
+    Input,
+    Interface,
+    Mutation,
+    Query,
+    Scalar,
+    Subscription,
+    Type,
+    Union,
+)
+from fastql.errors import GraphQLError, GraphQLSyntaxError, ValidationError
+from fastql.execution import ExecutionResult, execute, subscribe
+from fastql.extensions import SchemaExtension
+from fastql.language import parse
+from fastql.registry import TypeRegistry, default_registry
+from fastql.schema_builder import SchemaBuildError, build_schema
+from fastql.sdl import print_schema
+from fastql.testing import GraphQLTestClient
+from fastql.types import (
+    AppliedDirective,
+    Boolean,
+    Float,
+    ID,
+    Int,
+    ListType,
+    NonNull,
+    Schema,
+    SchemaConfig,
+    String,
+)
+from fastql.validation import validate
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "__version__",
+    # Decorators
+    "Type",
+    "Input",
+    "Interface",
+    "Enum",
+    "Union",
+    "Scalar",
+    "Query",
+    "Mutation",
+    "Subscription",
+    "Field",
+    "Arg",
+    "Argument",
+    "AppliedDirective",
+    "BasePermission",
+    "FieldExtension",
+    "SchemaExtension",
+    # Context / DI
+    "Context",
+    "Info",
+    "ResolveInfo",
+    "register_dependency",
+    "provides",
+    # DataLoader (request-scoped batch loading)
+    "DataLoader",
+    "DataLoaderError",
+    "get_loader",
+    # Built-in scalars and wrappers
+    "Int",
+    "Float",
+    "String",
+    "Boolean",
+    "ID",
+    "NonNull",
+    "ListType",
+    # Schema building and execution
+    "Schema",
+    "SchemaConfig",
+    "build_schema",
+    "SchemaBuildError",
+    "execute",
+    "subscribe",
+    "ExecutionResult",
+    "validate",
+    "parse",
+    "print_schema",
+    "GraphQLTestClient",
+    # Dev server (lazy — keeps the agnostic core free of the HTTP layer)
+    "serve",
+    "start_server",
+    # Registry
+    "TypeRegistry",
+    "default_registry",
+    # Errors
+    "GraphQLError",
+    "GraphQLSyntaxError",
+    "ValidationError",
+]
+
+
+def __getattr__(name: str):
+    # `serve` / `start_server` live in fastql.server, which imports asyncio HTTP
+    # machinery. Import them lazily so the agnostic core never pulls in the
+    # transport layer just by `import fastql`.
+    if name in ("serve", "start_server"):
+        from fastql import server
+
+        return getattr(server, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

mygenx_fastql-0.0.1/fastql/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m fastql ...``."""
+
+from fastql.cli import main
+
+if __name__ == "__main__":
+    main()

mygenx_fastql-0.0.1/fastql/cli.py

@@ -0,0 +1,130 @@
+"""Command-line entry point: ``python -m fastql serve module:attr``."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import importlib
+import json
+import sys
+from typing import Any
+
+from fastql.server import DEFAULT_HOST, DEFAULT_PORT, serve
+from fastql.types.schema import Schema
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="fastql", description="FastQL CLI")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    serve_parser = sub.add_parser("serve", help="Run the dev server for a schema.")
+    serve_parser.add_argument(
+        "target",
+        help="Dotted path to the schema object, e.g. 'myapp.schema:schema'.",
+    )
+    serve_parser.add_argument("--host", default=DEFAULT_HOST)
+    serve_parser.add_argument("--port", type=int, default=DEFAULT_PORT)
+    serve_parser.add_argument(
+        "--context",
+        default=None,
+        help=(
+            "Dotted path to a per-request context value or zero-arg factory, "
+            "e.g. 'myapp:make_context'."
+        ),
+    )
+
+    export_parser = sub.add_parser(
+        "export-schema", help="Write a schema's SDL or introspection JSON."
+    )
+    export_parser.add_argument(
+        "target",
+        help="Dotted path to the schema object, e.g. 'myapp.schema:schema'.",
+    )
+    export_parser.add_argument(
+        "--output",
+        "-o",
+        default=None,
+        help="File to write to. Writes to stdout when omitted.",
+    )
+    export_parser.add_argument(
+        "--format",
+        choices=("sdl", "json"),
+        default="sdl",
+        help="Output format: 'sdl' (default) or 'json' (introspection result).",
+    )
+    return parser
+
+
+def _load_schema(target: str) -> Any:
+    """Import and return the schema object named by a dotted ``module:attr`` path."""
+    if ":" in target:
+        module_name, attr = target.split(":", 1)
+    else:
+        module_name, _, attr = target.rpartition(".")
+    if not module_name or not attr:
+        raise SystemExit(
+            f"Invalid target {target!r}; expected 'module:attr' or 'module.attr'."
+        )
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError as error:
+        raise SystemExit(f"Could not import module {module_name!r}: {error}")
+    try:
+        return getattr(module, attr)
+    except AttributeError:
+        raise SystemExit(f"Module {module_name!r} has no attribute {attr!r}.")
+
+
+def _render_schema(schema: Any, fmt: str) -> str:
+    """Render ``schema`` as SDL or as an introspection-result JSON document."""
+    if not isinstance(schema, Schema):
+        raise SystemExit(
+            f"Loaded object is not a fastql Schema (got {type(schema).__name__})."
+        )
+    if fmt == "json":
+        from fastql.execution import execute
+        from fastql.integrations.http import INTROSPECTION_QUERY
+
+        result = asyncio.run(execute(schema, INTROSPECTION_QUERY))
+        if result.errors:
+            raise SystemExit(
+                f"Introspection failed: {result.errors[0].message}"
+            )
+        return json.dumps(result.data, indent=2)
+
+    from fastql.sdl import print_schema
+
+    return print_schema(schema)
+
+
+def _export_schema(target: str, output: str | None, fmt: str) -> None:
+    schema = _load_schema(target)
+    rendered = _render_schema(schema, fmt)
+    if output:
+        with open(output, "w", encoding="utf-8") as handle:
+            handle.write(rendered + ("\n" if not rendered.endswith("\n") else ""))
+    else:
+        print(rendered)
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if args.command == "serve":
+        schema = _load_schema(args.target)
+        context_factory = None
+        if args.context:
+            obj = _load_schema(args.context)
+            context_factory = obj if callable(obj) else (lambda value=obj: value)
+        serve(
+            schema,
+            host=args.host,
+            port=args.port,
+            context_factory=context_factory,
+        )
+    elif args.command == "export-schema":
+        _export_schema(args.target, args.output, args.format)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()