Python Django

Python & Django for Saleor

Before writing code

Fetch live docs:

1. Web-search site:docs.djangoproject.com topics models querysets for current Django ORM documentation
2. Web-search site:docs.djangoproject.com topics signals for Django signals reference
3. Web-search site:docs.celeryq.dev userguide tasks for Celery task patterns and configuration
4. Web-search site:docs.saleor.io developer for Saleor-specific Django conventions
5. Fetch https://docs.python.org/3/library/typing.html for Python type hints reference

Django ORM Patterns for Saleor

QuerySet Operations

F and Q Objects

• Use F() for atomic field updates without race conditions
• Combine Q() objects with | (OR), & (AND), ~ (NOT) for complex filters

Model Relationships in Saleor

• Always set on_delete explicitly (CASCADE, PROTECT, SET_NULL)
• Use related_name for reverse lookups
• Index foreign keys used in frequent queries

Django Signals

• Saleor uses webhooks as the primary event mechanism, not Django signals
• Use signals sparingly for internal side effects only
• Never perform expensive I/O in signal handlers (use Celery tasks instead)
• Connect signals in AppConfig.ready() to avoid import issues

Celery Task Patterns

Defining Tasks

Retry and Error Handling

• Pass serializable arguments (IDs, not model instances)
• Keep tasks idempotent — safe to retry without side effects
• Set reasonable timeouts with soft_time_limit and time_limit

Python Type Hints

• Use from __future__ import annotations for postponed evaluation
• Type all function parameters, return values, and class attributes
• Use mypy or pyright for static type checking

Database Migrations

• Review generated migrations before applying to production
• Use RunPython for data migrations (separate from schema migrations)
• Test migrations on a copy of production data before deploying

Management Commands

• Use management commands for one-off scripts, data fixes, and admin tasks
• Always add help text to commands for documentation

Async Django Views (ASGI)

• Saleor runs via ASGI with Uvicorn workers under Gunicorn
• Django ORM is synchronous — use sync_to_async or QuerySet.aiterator()
• Use httpx.AsyncClient for non-blocking HTTP requests

Django Settings and Virtual Environments

Best Practices

• Use select_related and prefetch_related to avoid N+1 query problems
• Keep Django signals lightweight — offload heavy work to Celery tasks
• Type all function signatures and use mypy for static analysis
• Make Celery tasks idempotent and pass only serializable arguments
• Review migration SQL before applying to production databases
• Use F() expressions for atomic field updates instead of read-modify-write
• Follow Saleor's existing code style when contributing to the core
• Use async views and httpx for I/O-heavy endpoints
• Store all configuration in environment variables following twelve-factor methodology

Fetch the Python and Django documentation for current ORM patterns, Celery task configuration, and async view setup before implementing.