https://github.com/tony/learning-fastapi
FastAPI + strawberry + uv + strict mypy typings + py.test harnessed
https://github.com/tony/learning-fastapi
fastapi graphql mypy pytest python starter strawberry uv
Last synced: about 2 months ago
JSON representation
FastAPI + strawberry + uv + strict mypy typings + py.test harnessed
- Host: GitHub
- URL: https://github.com/tony/learning-fastapi
- Owner: tony
- License: mit
- Created: 2025-09-28T11:54:11.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2026-04-18T13:42:34.000Z (2 months ago)
- Last Synced: 2026-04-18T15:32:53.353Z (2 months ago)
- Topics: fastapi, graphql, mypy, pytest, python, starter, strawberry, uv
- Language: Python
- Homepage:
- Size: 490 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Learning FastAPI
A compact playground that demonstrates how to serve classic HTTP routes and
GraphQL queries with [FastAPI](https://fastapi.tiangolo.com) and
[Strawberry GraphQL](https://strawberry.rocks). The project keeps the footprint
small so you can focus on how the pieces fit together: a Strawberry schema, a
FastAPI application with both REST and GraphQL endpoints, and a concise
pytest-based test suite.
## Highlights
- FastAPI application defined in `src/app/app.py` that exposes:
- `GET /` — synchronous route returning a plain-text greeting.
- `POST /graphql` — a Strawberry-powered GraphQL router mounted at `/graphql`.
- GraphQL `Query` type uses `strawberry.Private` to store the greeting server-side
while exposing a typed resolver.
- Tests built with `pytest` and `fastapi.testclient.TestClient` exercising both
HTTP and GraphQL flows.
- Tooling powered by `uv`, `ruff`, and `mypy` for repeatable local workflows.
## Project Layout
```
src/
app/__init__.py # Re-exports the FastAPI app and run() helper for uvicorn
app/app.py # FastAPI app, HTTP route, Strawberry schema & GraphQL router
app/settings.py # Pydantic settings (host, port, reload flags)
tests/
test_app.py # End-to-end tests for the HTTP and GraphQL endpoints
pyproject.toml # Project metadata, Ruff & mypy configuration
uv.lock # Reproducible dependency lock generated by uv
```
## Requirements
- Python 3.14 or newer (project targets `py314`).
- [uv](https://github.com/astral-sh/uv) 0.8+ for dependency management
(recommended). If you prefer `pip`, create a virtual environment manually and
install the dependencies via `pip install -e .` plus any tooling you need.
## Getting Started
```bash
# Install dependencies (includes dev tools such as pytest, ruff, mypy)
uv sync --all-extras --dev
# Run the development server with auto-reload
uv run uvicorn app:app --reload --host 127.0.0.1 --port 8020
```
The server listens on by default (configurable via
environment variables, see `src/app/settings.py`).
## Available Endpoints
### HTTP
```
GET /
```
Example:
```bash
curl http://127.0.0.1:8020/
# => Hello, world!
```
### GraphQL
```
POST /graphql
```
Query the schema with any GraphQL client or plain `curl`:
```bash
curl -X POST http://127.0.0.1:8020/graphql \
-H 'content-type: application/json' \
-d '{"query": "query { hello }"}'
# => {"data":{"hello":"Hello World"}}
```
The schema lives in `Query`, and the router is provided by
`strawberry.fastapi.GraphQLRouter`. FastAPI mounts it directly on the
application instance so Strawberry receives a fresh `Query` object for each
request.
## Quality Checks
```bash
# Tests
uv run pytest
# Ruff linting (same flags used by CI experiments)
uv run ruff check --select ALL . --fix --unsafe-fixes --preview --show-fixes
# Ruff formatting
uv run ruff format .
# Static typing
uv run mypy .
```
## Design Notes
- The GraphQL `Query` type stores its greeting on a `strawberry.Private` field,
keeping configuration server-side while exposing a typed resolver in the schema.
- The HTTP handler and GraphQL resolvers remain synchronous and CPU-light, so
they run directly on the event loop without extra thread dispatch.
- All configuration, tooling, and dependency metadata live in `pyproject.toml`
to reduce dotfile churn.
## Next Steps
Ideas for extending the playground:
- Add mutations or subscriptions to the Strawberry schema.
- Introduce persistence (e.g., SQLModel) and showcase FastAPI dependencies for
database sessions.
- Experiment with background tasks, WebSocket endpoints, or dependency overrides.
- Wire up a front-end (HTMX, React, etc.) and consume the GraphQL endpoint.
Happy exploring FastAPI and Strawberry!
## License
Released under the [MIT License](./LICENSE).