Skip to content

AGENTS.md

Latest commit

 

History

History
47 lines (33 loc) · 2.02 KB

AGENTS.md

File metadata and controls

47 lines (33 loc) · 2.02 KB

GraphQL-API

Compatibility note: AGENTS.md and CLAUDE.md are both supported in this repo. Keep these files identical. Any change in one must be mirrored in the other.

Code-first, decorator-based GraphQL framework for Python. Published on PyPI.

Project Structure

Directory Description
graphql_api/ Main package source
tests/ Test suite (34 files, pytest)
docs/ Sphinx documentation

Development

# Install dependencies
uv sync

# Run tests
uv run pytest

# Run linter
uv run flake8 graphql_api tests

Key Patterns

  • Automatic snake_case to camelCase: All Python field names, arguments, and dataclass/Pydantic fields are auto-converted to camelCase in GraphQL. Input arguments are converted back to snake_case. Conversion lives in graphql_api/utils.py (to_camel_case(), to_snake_case())
  • @field marks a method as a query; @field(mutable=True) makes it a mutation; AsyncGenerator return type or subscription=True makes it a subscription
  • Plain functions: @api.query / @api.mutation / @api.subscription register a free function as a root-level field — no class required. Composes with class-based roots (registered fns are folded onto the user-provided query_type / mutation_type / subscription_type / root_type)
  • Python types auto-map: str→String, int→Int, bool→Boolean, float→Float, UUID→UUID scalar, datetime→DateTime, Optional[T]→nullable, List[T]→list, dataclasses/Pydantic models→object types, enums→enum types
  • Schema setup: GraphQLAPI(query_type=Q, mutation_type=M, subscription_type=S) or legacy root_type=Root (or neither — just @api.query/@api.mutation/@api.subscription)

Releasing

See the ecosystem-level CLAUDE.md in the parent workspace for the full release process. In short:

# Ensure CI is green on main, then:
git tag X.Y.Z
git push origin X.Y.Z

CI publishes to PyPI and creates a GitHub Release automatically.