Set up oxa-types PyPI package (#18)

* feat(python): add `oxa-types` Python package

* chore(prettier): ignore generated json schema

* feat(python): add `oxa-types` Python package

* chore(prettier): ignore generated json schema

* test(python): add typecheck of generated types

---------

Co-authored-by: Rowan Cockett <[email protected]>

Author: nokome

.github/workflows/primary.yml

@@ -25,9 +25,11 @@ jobs:
           node-version: 22
           cache: "pnpm"
 
+      - uses: astral-sh/setup-uv@v5
+
       - run: pnpm install --frozen-lockfile
 
-      # Typecheck first (before format/lint possibly change line numbers)
+      # Typecheck generation code in scripts/ (before format/lint possibly change line numbers)
       - run: pnpm typecheck
 
       # On push: auto-fix formatting and linting (will be committed)
@@ -42,7 +44,12 @@ jobs:
       - run: pnpm lint
         if: github.event_name == 'pull_request'
 
-      - run: pnpm codegen all
+      - name: Generate types
+        run: pnpm codegen all
+
+      # Typecheck generated code (Python via ty, TypeScript via tsc)
+      - run: uv run ty check src/
+        working-directory: packages/oxa-types-py
       - run: pnpm test
 
       - name: Commit changes

.gitignore

@@ -1,4 +1,14 @@
+# Node.js
 node_modules
 dist
+
+# Python
+__pycache__
+*.pyc
+.venv
+.mypy_cache
+*.egg-info
+
+# Documentation
 docs/_build
 docs/schema

.prettierignore

@@ -2,3 +2,4 @@ dist/
 node_modules/
 target/
 pnpm-lock.yaml
+schema/schema.json

packages/oxa-types-py/README.md

@@ -0,0 +1,43 @@
+# oxa-types
+
+Pydantic models generated from the OXA JSON Schema.
+
+## Installation
+
+```bash
+pip install oxa-types
+```
+
+Or with uv:
+
+```bash
+uv add oxa-types
+```
+
+## Usage
+
+```python
+from oxa_types import Document, Paragraph, Text, Block, Inline
+
+# Create a simple document
+doc = Document(
+    metadata={},
+    title=[Text(value="Hello World")],
+    children=[
+        Paragraph(children=[Text(value="This is a paragraph.")])
+    ]
+)
+
+# Serialize to JSON
+print(doc.model_dump_json(indent=2))
+```
+
+## Development
+
+This package is automatically generated from the OXA JSON Schema. Do not edit the generated files directly.
+
+To regenerate the types:
+
+```bash
+pnpm codegen py
+```

packages/oxa-types-py/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "oxa-types"
+version = "0.1.0"
+description = "Pydantic models generated from the OXA schema"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+keywords = ["oxa", "types", "pydantic", "schema"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/oxa-dev/oxa"
+Repository = "https://github.com/oxa-dev/oxa.git"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/oxa_types"]
+
+[tool.uv]
+dev-dependencies = [
+    "ruff>=0.14",
+    "ty>=0.0.1a13",
+]

packages/oxa-types-py/src/oxa_types/__init__.py

@@ -0,0 +1,132 @@
+"""
+Pydantic models generated from the OXA JSON Schema.
+
+Do not edit this file directly. Instead, edit the YAML schema files
+in the schema/ directory and run `pnpm codegen py`.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Document(BaseModel):
+    """A document with metadata, title, and block content."""
+
+    model_config = ConfigDict(strict=True)
+
+    type: Literal["Document"] = "Document"
+    id: str | None = Field(
+        default=None, description="A unique identifier for the node."
+    )
+    classes: list[str] | None = Field(
+        default=None, description="A list of class names for styling or semantics."
+    )
+    data: dict[str, Any] | None = Field(
+        default=None, description="Arbitrary key-value data attached to the node."
+    )
+    metadata: dict[str, Any] = Field(description="Arbitrary document metadata.")
+    title: list["Inline"] = Field(description="The document title as inline content.")
+    children: list["Block"] = Field(description="The block content of the document.")
+
+
+class Heading(BaseModel):
+    """A heading with a level and inline content."""
+
+    model_config = ConfigDict(strict=True)
+
+    type: Literal["Heading"] = "Heading"
+    id: str | None = Field(
+        default=None, description="A unique identifier for the node."
+    )
+    classes: list[str] = Field(
+        description="A list of class names for styling or semantics."
+    )
+    data: dict[str, Any] = Field(
+        description="Arbitrary key-value data attached to the node."
+    )
+    level: int = Field(description="The heading level (1-6).")
+    children: list["Inline"] = Field(description="The inline content of the heading.")
+
+
+class Paragraph(BaseModel):
+    """A paragraph of inline content."""
+
+    model_config = ConfigDict(strict=True)
+
+    type: Literal["Paragraph"] = "Paragraph"
+    id: str | None = Field(
+        default=None, description="A unique identifier for the node."
+    )
+    classes: list[str] = Field(
+        description="A list of class names for styling or semantics."
+    )
+    data: dict[str, Any] = Field(
+        description="Arbitrary key-value data attached to the node."
+    )
+    children: list["Inline"] = Field(description="The inline content of the paragraph.")
+
+
+class Strong(BaseModel):
+    """Strongly emphasized content (typically bold)."""
+
+    model_config = ConfigDict(strict=True)
+
+    type: Literal["Strong"] = "Strong"
+    id: str | None = Field(
+        default=None, description="A unique identifier for the node."
+    )
+    classes: list[str] = Field(
+        description="A list of class names for styling or semantics."
+    )
+    data: dict[str, Any] = Field(
+        description="Arbitrary key-value data attached to the node."
+    )
+    children: list["Inline"] = Field(description="The inline content to emphasize.")
+
+
+class Text(BaseModel):
+    """A text node containing a string value."""
+
+    model_config = ConfigDict(strict=True)
+
+    type: Literal["Text"] = "Text"
+    id: str | None = Field(
+        default=None, description="A unique identifier for the node."
+    )
+    classes: list[str] = Field(
+        description="A list of class names for styling or semantics."
+    )
+    data: dict[str, Any] = Field(
+        description="Arbitrary key-value data attached to the node."
+    )
+    value: str = Field(description="The text content.")
+
+
+# Union of all block content types.
+Block = Annotated[Union[Heading, Paragraph], Field(discriminator="type")]
+
+
+# Union of all inline content types.
+Inline = Annotated[Union[Text, Strong], Field(discriminator="type")]
+
+
+# Rebuild models to resolve forward references
+Document.model_rebuild()
+Heading.model_rebuild()
+Paragraph.model_rebuild()
+Strong.model_rebuild()
+Text.model_rebuild()
+
+
+__all__ = [
+    "Block",
+    "Document",
+    "Heading",
+    "Inline",
+    "Paragraph",
+    "Strong",
+    "Text",
+]