nabu-forge 1.0.0__tar.gz

nabu_forge-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [ master ]
+    tags: [ "v*" ]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [ "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 project and dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: ruff check src/
+
+      - name: Format check (ruff)
+        run: ruff format --check src/
+
+      - name: Tests
+        run: pytest -q
+
+  publish:
+    name: Publish to PyPI
+    needs: test
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build distribution
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

nabu_forge-1.0.0/.gitignore

@@ -0,0 +1,58 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.egg
+*.egg-info/
+dist/
+build/
+wheels/
+sdist/
+.eggs/
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# uv
+.uv/
+uv.lock
+
+# Distribution / packaging
+pip-wheel-metadata/
+share/python-wheels/
+
+# Testing
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+.tox/
+
+# Type checking
+.mypy_cache/
+.pyright/
+pyrightconfig.json
+
+# Ruff
+.ruff_cache/
+
+# IDEs
+.idea/
+.vscode/
+*.iml
+
+# macOS
+.DS_Store
+
+# Generated output (development artefacts, not committed)
+generated_client/
+
+architecture/phases/
+architecture/assets/*.drawio
+
+samples/euporie/

nabu_forge-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Nikolov
+
+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.

nabu_forge-1.0.0/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.5
+Name: nabu-forge
+Version: 1.0.0
+Summary: A schema-driven compiler that transforms GraphQL SDL and operation definitions into type-safe Python client packages.
+Project-URL: Repository, https://github.com/ivanNikolov2910/nabu-forge
+Author: Ivan Nikolov
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: graphql-core>=3.2
+Requires-Dist: httpx>=0.26.2
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typer>=0.27.1
+Provides-Extra: dev
+Requires-Dist: pytest>=9.1.1; extra == 'dev'
+Requires-Dist: ruff>=0.16.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Nabu Forge
+
+A schema-driven compiler that transforms GraphQL SDL and operation definitions into type-safe Python client packages.
+
+```text
+GraphQL SDL + operations  ->  Nabu Forge  ->  Typed Python client package
+```
+
+## What it does
+
+Given a GraphQL schema and operation documents, Nabu Forge generates a complete Python package with:
+
+- Pydantic v2 models for every response shape, with correct list/nullability handling
+- Discriminated unions for interfaces and polymorphic types (via `__typename`)
+- Enum definitions (`str, Enum`)
+- Input models with camelCase -> snake_case aliasing for correct wire serialization
+- Async client methods with typed variables and response deserialization
+- Custom scalar mappings via config
+- Async httpx transport with configurable timeout and persistent connection
+- Compiler-style diagnostics with file/line/column and hints
+
+### Example generated usage
+
+```python
+from generated_client import Client
+
+# basic usage
+client = Client(url="https://example.com/graphql", headers={"Authorization": "Bearer token"})
+result = await client.get_student(id="123")
+print(result.student.id, result.student.status)
+
+# async context manager for clean connection teardown
+async with Client(url="https://example.com/graphql") as client:
+    result = await client.get_student(id="123")
+```
+
+## Installation
+
+```bash
+pip install nabu-forge
+```
+
+Or for development:
+
+```bash
+cd nabu-forge
+pip install -e .
+```
+
+## Usage
+
+### 1. Write a `nabu.toml`
+
+```toml
+schema = "schema.graphqls"
+operations = "operations/"
+output = "generated_client"
+
+[scalars]
+DateTime = "datetime.datetime"
+JSON = "typing.Any"
+Void = "None"
+```
+
+### 2. Run
+
+```bash
+nabu validate --config nabu.toml      # validate without writing files
+nabu inspect  --schema schema.graphqls # show schema structure
+nabu generate --config nabu.toml      # generate the client package
+```
+
+## Configuration
+
+| Field        | Description                                     |
+|--------------|-------------------------------------------------|
+| `schema`     | Path to the GraphQL SDL file                    |
+| `operations` | Directory containing `.graphql` operation files |
+| `output`     | Output directory for the generated package      |
+| `[scalars]`  | Python type mappings for custom scalars         |
+
+All paths are relative to `nabu.toml`.
+
+## GraphQL → Python type mapping
+
+| GraphQL       | Python                      |
+|---------------|-----------------------------|
+| `String!`     | `str`                       |
+| `String`      | `str \| None`               |
+| `[String!]!`  | `list[str]`                 |
+| `[String]`    | `list[str \| None] \| None` |
+| `Int!`        | `int`                       |
+| `Float!`      | `float`                     |
+| `Boolean!`    | `bool`                      |
+| `ID!`         | `str`                       |
+| Custom scalar | configured via `[scalars]`  |
+
+camelCase GraphQL field names are converted to `snake_case`. A `Field(alias="camelCase")` is emitted automatically so
+generated models deserialize real GraphQL responses correctly.
+
+## Polymorphic types (interfaces and unions)
+
+Inline fragments generate discriminated union aliases using `__typename` as the discriminator. Shared interface-level
+fields appear in every member class — you do not need to repeat them in each fragment.
+
+```graphql
+query GetJob($id: String!) {
+    job(id: $id) {
+        jobId          # shared — emitted in ALL member classes
+        state
+        ... on ExecutionJob  { task { name } }
+        ... on CollectionJob { }
+    }
+}
+```
+
+Generated:
+
+```python
+class GetJobJobExecutionJob(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+    typename: Literal["ExecutionJob"] = Field(alias="__typename")
+    job_id: str = Field(..., alias="jobId")  # shared
+    state: JobState  # shared
+    task: GetJobJobExecutionJobTask | None
+
+
+GetJobJob = Annotated[
+    GetJobJobExecutionJob | GetJobJobCollectionJob,
+    Field(discriminator="typename"),
+]
+```
+
+`__typename` is injected automatically in the sent document — no need to add it to your `.graphql` files.
+
+## Diagnostics
+
+Nabu Forge emits compiler-style diagnostics. Errors abort generation; warnings print and continue.
+
+```
+error[E023]: Field 'ghost' does not exist on type 'Query'.
+  operations/bad.graphql:2:5
+
+warning[E029]: Field 'job' returns polymorphic type 'Job' but has no inline fragments.
+  operations/get_job.graphql:3:5
+  hint: Add '... on ConcreteType { fields }' for each possible type.
+```
+
+| Code | Severity | Meaning                                    |
+|------|----------|--------------------------------------------|
+| E001 | error    | Config file not found                      |
+| E002 | error    | Missing required config fields             |
+| E010 | error    | GraphQL syntax error                       |
+| E020 | error    | Unknown type reference                     |
+| E021 | error    | Unmapped custom scalar                     |
+| E022 | error    | Unknown variable type                      |
+| E023 | error    | Unknown field / direct field on union type |
+| E024 | error    | Unknown fragment spread                    |
+| E025 | error    | Bad inline fragment target                 |
+| E026 | error    | Generated name collision                   |
+| E028 | error    | Unsupported feature (subscriptions)        |
+| E030 | error    | File write error                           |
+
+## Compiler pipeline
+
+<img src="architecture/assets/compiler-pipeline.drawio.png" alt="Nabu Forge compiler pipeline"/>
+
+## Supported / not supported
+
+**Supported:**
+
+- Object types, input types, enums, interfaces, unions
+- Lists and nullability (all 8 combinations)
+- Custom scalars via `[scalars]` config
+- Queries and mutations
+- Named fragments (inlined at codegen time)
+- Inline fragments → discriminated unions via `__typename`
+- Shared interface fields alongside inline fragments
+- Field aliases including two aliases of the same underlying field
+- camelCase → snake_case with `Field(alias=...)`
+- Async httpx transport with `timeout`, persistent `AsyncClient`, `async with` support
+
+**Not supported:**
+
+- Subscriptions (E028 at semantic analysis)
+- File uploads (multipart)
+- Query batching
+- `@skip` / `@include` directives
+- Variable default values
+- Introspection-based generation (SDL file required)
+
+## Development
+
+```bash
+pip install -e .
+
+ruff check src/         # lint
+pytest                  # 144 tests
+nabu generate --config samples/university/nabu.toml
+```
+
+## Architecture docs
+
+- [`architecture/overview.md`](architecture/overview.md) — project summary and goals
+- [`architecture/compiler-pipeline.md`](architecture/compiler-pipeline.md) — all pipeline stages
+- [`architecture/generated-package.md`](architecture/generated-package.md) — generated package layout
+- [`architecture/diagnostics-and-cli.md`](architecture/diagnostics-and-cli.md) — CLI and diagnostics design
+- [`architecture/development-plan.md`](architecture/development-plan.md) — implementation phases
+- [`architecture/product-requirements.md`](architecture/product-requirements.md) — scope and definition of done

nabu_forge-1.0.0/README.md

@@ -0,0 +1,209 @@
+# Nabu Forge
+
+A schema-driven compiler that transforms GraphQL SDL and operation definitions into type-safe Python client packages.
+
+```text
+GraphQL SDL + operations  ->  Nabu Forge  ->  Typed Python client package
+```
+
+## What it does
+
+Given a GraphQL schema and operation documents, Nabu Forge generates a complete Python package with:
+
+- Pydantic v2 models for every response shape, with correct list/nullability handling
+- Discriminated unions for interfaces and polymorphic types (via `__typename`)
+- Enum definitions (`str, Enum`)
+- Input models with camelCase -> snake_case aliasing for correct wire serialization
+- Async client methods with typed variables and response deserialization
+- Custom scalar mappings via config
+- Async httpx transport with configurable timeout and persistent connection
+- Compiler-style diagnostics with file/line/column and hints
+
+### Example generated usage
+
+```python
+from generated_client import Client
+
+# basic usage
+client = Client(url="https://example.com/graphql", headers={"Authorization": "Bearer token"})
+result = await client.get_student(id="123")
+print(result.student.id, result.student.status)
+
+# async context manager for clean connection teardown
+async with Client(url="https://example.com/graphql") as client:
+    result = await client.get_student(id="123")
+```
+
+## Installation
+
+```bash
+pip install nabu-forge
+```
+
+Or for development:
+
+```bash
+cd nabu-forge
+pip install -e .
+```
+
+## Usage
+
+### 1. Write a `nabu.toml`
+
+```toml
+schema = "schema.graphqls"
+operations = "operations/"
+output = "generated_client"
+
+[scalars]
+DateTime = "datetime.datetime"
+JSON = "typing.Any"
+Void = "None"
+```
+
+### 2. Run
+
+```bash
+nabu validate --config nabu.toml      # validate without writing files
+nabu inspect  --schema schema.graphqls # show schema structure
+nabu generate --config nabu.toml      # generate the client package
+```
+
+## Configuration
+
+| Field        | Description                                     |
+|--------------|-------------------------------------------------|
+| `schema`     | Path to the GraphQL SDL file                    |
+| `operations` | Directory containing `.graphql` operation files |
+| `output`     | Output directory for the generated package      |
+| `[scalars]`  | Python type mappings for custom scalars         |
+
+All paths are relative to `nabu.toml`.
+
+## GraphQL → Python type mapping
+
+| GraphQL       | Python                      |
+|---------------|-----------------------------|
+| `String!`     | `str`                       |
+| `String`      | `str \| None`               |
+| `[String!]!`  | `list[str]`                 |
+| `[String]`    | `list[str \| None] \| None` |
+| `Int!`        | `int`                       |
+| `Float!`      | `float`                     |
+| `Boolean!`    | `bool`                      |
+| `ID!`         | `str`                       |
+| Custom scalar | configured via `[scalars]`  |
+
+camelCase GraphQL field names are converted to `snake_case`. A `Field(alias="camelCase")` is emitted automatically so
+generated models deserialize real GraphQL responses correctly.
+
+## Polymorphic types (interfaces and unions)
+
+Inline fragments generate discriminated union aliases using `__typename` as the discriminator. Shared interface-level
+fields appear in every member class — you do not need to repeat them in each fragment.
+
+```graphql
+query GetJob($id: String!) {
+    job(id: $id) {
+        jobId          # shared — emitted in ALL member classes
+        state
+        ... on ExecutionJob  { task { name } }
+        ... on CollectionJob { }
+    }
+}
+```
+
+Generated:
+
+```python
+class GetJobJobExecutionJob(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+    typename: Literal["ExecutionJob"] = Field(alias="__typename")
+    job_id: str = Field(..., alias="jobId")  # shared
+    state: JobState  # shared
+    task: GetJobJobExecutionJobTask | None
+
+
+GetJobJob = Annotated[
+    GetJobJobExecutionJob | GetJobJobCollectionJob,
+    Field(discriminator="typename"),
+]
+```
+
+`__typename` is injected automatically in the sent document — no need to add it to your `.graphql` files.
+
+## Diagnostics
+
+Nabu Forge emits compiler-style diagnostics. Errors abort generation; warnings print and continue.
+
+```
+error[E023]: Field 'ghost' does not exist on type 'Query'.
+  operations/bad.graphql:2:5
+
+warning[E029]: Field 'job' returns polymorphic type 'Job' but has no inline fragments.
+  operations/get_job.graphql:3:5
+  hint: Add '... on ConcreteType { fields }' for each possible type.
+```
+
+| Code | Severity | Meaning                                    |
+|------|----------|--------------------------------------------|
+| E001 | error    | Config file not found                      |
+| E002 | error    | Missing required config fields             |
+| E010 | error    | GraphQL syntax error                       |
+| E020 | error    | Unknown type reference                     |
+| E021 | error    | Unmapped custom scalar                     |
+| E022 | error    | Unknown variable type                      |
+| E023 | error    | Unknown field / direct field on union type |
+| E024 | error    | Unknown fragment spread                    |
+| E025 | error    | Bad inline fragment target                 |
+| E026 | error    | Generated name collision                   |
+| E028 | error    | Unsupported feature (subscriptions)        |
+| E030 | error    | File write error                           |
+
+## Compiler pipeline
+
+<img src="architecture/assets/compiler-pipeline.drawio.png" alt="Nabu Forge compiler pipeline"/>
+
+## Supported / not supported
+
+**Supported:**
+
+- Object types, input types, enums, interfaces, unions
+- Lists and nullability (all 8 combinations)
+- Custom scalars via `[scalars]` config
+- Queries and mutations
+- Named fragments (inlined at codegen time)
+- Inline fragments → discriminated unions via `__typename`
+- Shared interface fields alongside inline fragments
+- Field aliases including two aliases of the same underlying field
+- camelCase → snake_case with `Field(alias=...)`
+- Async httpx transport with `timeout`, persistent `AsyncClient`, `async with` support
+
+**Not supported:**
+
+- Subscriptions (E028 at semantic analysis)
+- File uploads (multipart)
+- Query batching
+- `@skip` / `@include` directives
+- Variable default values
+- Introspection-based generation (SDL file required)
+
+## Development
+
+```bash
+pip install -e .
+
+ruff check src/         # lint
+pytest                  # 144 tests
+nabu generate --config samples/university/nabu.toml
+```
+
+## Architecture docs
+
+- [`architecture/overview.md`](architecture/overview.md) — project summary and goals
+- [`architecture/compiler-pipeline.md`](architecture/compiler-pipeline.md) — all pipeline stages
+- [`architecture/generated-package.md`](architecture/generated-package.md) — generated package layout
+- [`architecture/diagnostics-and-cli.md`](architecture/diagnostics-and-cli.md) — CLI and diagnostics design
+- [`architecture/development-plan.md`](architecture/development-plan.md) — implementation phases
+- [`architecture/product-requirements.md`](architecture/product-requirements.md) — scope and definition of done