{"id":2428,"library":"celery-types","title":"Type stubs for Celery and its related packages","description":"Celery-types provides PEP 561 compliant type stubs for Celery and its core dependencies, including `kombu`, `amqp`, `billiard`, `vine`, and `django-celery-results`. This library enhances type checking for Celery applications, allowing tools like MyPy to verify correct usage of Celery APIs. It is actively maintained with regular updates to support new Python and Celery versions.","status":"active","version":"0.26.0","language":"en","source_language":"en","source_url":"https://github.com/sbdchd/celery-types","tags":["typing","celery","stubs","type hints","mypy","type checking"],"install":[{"cmd":"pip install celery-types","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Provides backports of features from `typing` module for older Python versions, necessary for comprehensive type hinting.","package":"typing-extensions","optional":false}],"imports":[{"note":"celery-types provides type annotations for the Celery library; you import from 'celery' itself, not 'celery_types'.","symbol":"Celery","correct":"from celery import Celery"},{"note":"celery-types provides type annotations for the Celery library; you import from 'celery' itself, not 'celery_types'.","symbol":"Task","correct":"from celery import Task"},{"note":"celery-types provides type annotations for the Celery library; you import from 'celery' itself, not 'celery_types'.","symbol":"AsyncResult","correct":"from celery.result import AsyncResult"}],"quickstart":{"code":"from celery import Celery, Task\nfrom typing import Any, Dict\n\n# Configure Celery app (replace with your broker/backend)\napp = Celery(\n    'my_app',\n    broker=os.environ.get('CELERY_BROKER_URL', 'redis://localhost:6379/0'),\n    backend=os.environ.get('CELERY_RESULT_BACKEND', 'redis://localhost:6379/0')\n)\n\n# Define a type-hinted task\n@app.task\ndef add(x: int, y: int) -> int:\n    return x + y\n\n# Example of calling the task with type hints\nif __name__ == '__main__':\n    # The type checker (e.g., MyPy) will use celery-types to validate arguments\n    result: AsyncResult[int] = add.delay(10, 20)\n    print(f\"Task ID: {result.id}\")\n    print(f\"Result: {result.get()}\")\n\n    # Incorrect usage (type checker would flag this if celery-types is installed)\n    # add.delay(10, \"20\") # Mypy would warn about this","lang":"python","description":"This quickstart demonstrates a basic Celery application with a type-hinted task. With `celery-types` installed, your type checker will validate the arguments and return types of Celery tasks and related objects like `AsyncResult`."},"warnings":[{"fix":"Refer to the `celery-types` GitHub README for the latest monkey-patching snippet to enable full generic support for relevant Celery classes in your application's entry point. This typically involves iterating over a list of Celery classes and setting their `__class_getitem__` attribute.","message":"For full generic type support in certain Celery classes (e.g., `Celery`, `Task`, `AsyncResult`), `celery-types` suggests a runtime monkey patch for `__class_getitem__`. Without this, generic type hints on these classes might not be fully recognized by type checkers.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always import Celery classes and functions directly from the `celery` (or `kombu`, `django_celery_results`, etc.) packages. `celery-types` is a dependency for your type checker, not for runtime execution.","message":"celery-types provides *type stubs*, not runtime code. You should import Celery symbols from their original packages (e.g., `from celery import Celery`), and the installed `celery-types` package will automatically provide the type information to your type checker (e.g., MyPy). Attempting to import directly from `celery_types` will likely result in an `ImportError` or incorrect behavior.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always ensure your `celery-types` version is compatible with your installed `celery` version. Consult the `celery-types` release notes or `pyproject.toml` for supported `celery` ranges. Upgrade both `celery` and `celery-types` in tandem, following `celery`'s migration guides for runtime breaking changes.","message":"celery-types is designed to provide type hints for specific versions of the underlying Celery library. Celery itself has undergone significant breaking changes, especially regarding Python version support (e.g., Celery 5.0 dropped Python 2.7, Celery 5.6.0 requires Python 3.9+). Using `celery-types` with an incompatible major version of `celery` can lead to incorrect or missing type information.","severity":"breaking","affected_versions":"All versions, especially when upgrading Celery"},{"fix":"For complex objects, ensure they are JSON-serializable, or explicitly configure Celery to use a different serializer (e.g., `pickle` if security is less of a concern for internal communication), or pass only serializable data like IDs and retrieve complex objects within the task itself.","message":"While `celery-types` helps with type checking, it does not resolve runtime serialization issues in Celery. If you pass complex Python objects as task arguments, default JSON serialization might fail. Celery's default serializer changed from `pickle` to `json` in version 4.0. Using `pickle` is possible but less secure.","severity":"gotcha","affected_versions":"Celery 4.0 and later (which celery-types supports)"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}