lint
Lint and Type-Check
Run the full static-analysis suite on the project and fix any issues found.
uv run ruff check src— lint the codeuv run ruff format --check src— verify formattinguv run pyrefly check src— static type analysis
Fix every issue reported (re-run until clean) and report a short summary of what changed when done. If a failure is not auto-fixable, explain what needs human judgement rather than silencing it.
Pyrefly + Django gotchas
Pyrefly has built-in Django support (via django-stubs), but a few things aren't covered yet. Recognize these before reaching for # type: ignore:
- Reverse relations (
user.order_set,author.article_set) are not supported. This is a known pyrefly limitation, not a real bug. The right fix is to query the child model directly from its repository (OrderRepository().list_for_user(user_id)) — push the access down into the repo layer rather than suppressing it. Only if that's impossible, narrow it with# type: ignore[attr-defined]at a single call site. ManyRelatedManageris generic over[Parent, Model], not the concrete child. Don't rely on pyrefly to catch a mistyped M2M target — cover it with a test instead.- Chained QuerySet methods beyond
.all()are thinly typed. Keep chains inside the repository where the return type is an annotatedlist[SomeDTO]; don't let querysets leak out into services.
See pyrefly.org/en/docs/django for the current support matrix. Pyrefly's Django support is actively evolving — re-check when upgrading.
More from dvf/opinionated-django
services
Structure Django business logic as plain services that receive their dependencies via constructor injection, and wire them through an svcs registry so they can be resolved anywhere — views, Celery tasks, management commands, tests. Use when adding a new service, refactoring fat views or model methods into a service, wiring a service into the registry, or explaining where business logic should live in this project.
11architecture
Implement a Django feature following the opinionated architecture — prefixed ULID IDs, repository pattern, Pydantic DTOs, svcs service locator, project-scoped django-ninja API, Celery reliable signals, and layered tests. Use when the user asks to add a new entity, endpoint, app, or business logic in a Django project that follows these conventions.
11pytest
Set up and write pytest tests for an op-django project — pytest-django configuration, Celery eager mode for reliable-signal tests, freezegun for time-sensitive logic, shared conftest fixtures for DTOs and svcs overrides, and the three-layer test convention (repository against a real DB, service against mocked repos, API through HTTP). Use when adding tests to a new project, writing tests for a new feature, setting up test infrastructure, or explaining how tests should be organized.
10scaffold
Set up a Django project into the op-django layout so the architecture, signals, and settings skills have a foundation to build on. Use when starting a new project from scratch, or when converting an existing Django project to follow this opinionated structure. Creates the src/project/ shell (ids, services registry, api, reliable signals), installs dependencies with uv, and establishes the per-app directory conventions.
10signals
Add reliable signals (async side-effects via Celery) to a Django feature. Use when a business operation needs to trigger post-commit work like notifications, cache invalidation, analytics, or cross-service coordination — any time the user mentions side-effects, events, or async processing tied to a business action.
10settings
Organize Django settings.py into clearly sectioned blocks with banner-style headers. Use proactively whenever modifying src/project/settings.py — adding new settings, removing settings, or restructuring sections.
10