Welcome to Django Cloud Tasks!¶
Django Cloud Tasks is your go-to Django app for effortlessly running asynchronous tasks on Google Cloud Platform. It makes it a breeze to work with Google Cloud Tasks, Cloud Scheduler, and Cloud Pub/Sub right from your Django project.
Think of it as a way to offload heavy work (like image processing or report generation), schedule future jobs (like nightly cleanups), or react to events in a decoupled way (like sending a welcome email when a new user signs up) – all without making your users wait or bogging down your web servers.
This documentation will guide you through setting up and using its powerful features.
Installation¶
Getting this bad boy into your project is super easy. Just pip install it:
Django Setup¶
- Add
'django_cloud_tasks'
to yourINSTALLED_APPS
insettings.py
:
- Include the Django Cloud Tasks URLs in your main
urls.py
. These URLs are the endpoints that Google Cloud services will call to trigger your tasks.
from django.urls import path, include
urlpatterns = [
# ... other urls
path('my-tasks-prefix/', include('django_cloud_tasks.urls')),
# ...
]
- Make sure this endpoint is publicly accessible if you're not running in a private VPC, as Google Cloud services need to reach it.
Required Google Cloud APIs¶
To use django-cloud-tasks
effectively, you'll need to enable the following APIs in your Google Cloud Project:
- Cloud Tasks API
- Cloud Scheduler API
- Pub/Sub API
- Optional: Admin SDK API (Needed for some advanced features or if you are working with domain-wide delegation for service accounts, though typically not required for basic task and pub/sub operations with OIDC or standard service account authentication).
Core Configuration (settings.py
)¶
You can tweak how Django Cloud Tasks behaves through your Django settings.py
file. All settings are prefixed with DJANGO_CLOUD_TASKS_
. You can also set these as environment variables (which will take precedence if both are set).
Here are some of the main ones to get you started:
-
DJANGO_CLOUD_TASKS_ENDPOINT
: The full base URL of your application (e.g.,https://your-cool-app.com
). This is crucial because Cloud Tasks, Scheduler, and Pub/Sub push subscriptions need to know the exact URL to send HTTP requests to trigger your tasks. It's often your Cloud Run service URL.- Default:
"http://localhost:8080"
- Example:
DJANGO_CLOUD_TASKS_ENDPOINT = "https://myapp.com"
- Default:
-
DJANGO_CLOUD_TASKS_APP_NAME
: A unique name for your application or service. This is used to prefix and organize resources in GCP, such as Cloud Scheduler job names or Pub/Sub topic/subscription names, making it easier to manage them, especially if you have multiple applications in the same GCP project.- Default:
None
(reads fromAPP_NAME
environment variable if set) - Example:
DJANGO_CLOUD_TASKS_APP_NAME = "user-service"
- Default:
-
DJANGO_CLOUD_TASKS_EAGER
: If set toTrue
, tasks will run synchronously (i.e., immediately in the same process) instead of being sent to Google Cloud. This is incredibly useful for local development and testing, as it bypasses the need for GCP setup and lets you debug tasks like regular function calls.- Default:
False
- Example:
DJANGO_CLOUD_TASKS_EAGER = settings.DEBUG
# (1)
- Default:
-
DJANGO_CLOUD_TASKS_URL_NAME
: The specific Django URL name (not path) within the includeddjango_cloud_tasks.urls
that is used as the endpoint for on-demand tasks triggered by Cloud Tasks and scheduled tasks triggered by Cloud Scheduler.- Default:
"tasks-endpoint"
- Default:
-
DJANGO_CLOUD_TASKS_DELIMITER
: A string used to join parts of names, for example, when constructing default queue names, scheduler job names, or Pub/Sub topic/subscription names (e.g.,my-app--my-task
).- Default:
"--"
- Default:
-
Header Propagation: Settings related to header propagation are covered in detail in the "Header Propagation" section.
There are more settings for fine-tuning retries, Pub/Sub behavior, and specific service interactions. We'll touch upon many of these in the relevant sections. For a comprehensive list, you can always refer to the django_cloud_tasks.apps.DjangoCloudTasksAppConfig
class.
With this foundational setup, you're ready to dive into defining and using the different types of tasks!