Celery stubs improvements #210
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Significantly expanded type stubs for the celery package: - Added many new modules: app/annotations, app/autoretry, app/backends, app/builtins, app/defaults, app/trace, apps/beat, apps/multi - Added backend stubs: arangodb, asynchronous, azureblockblob, cache, cassandra, consul, cosmosdbsql, couchbase, couchdb, dynamodb, elasticsearch, filesystem, gcs, mongodb, redis, rpc, s3 - Added bin stubs: amqp, base, beat, call, celery, control, events, graph, list, logtool, migrate, multi, purge, result, shell, upgrade, worker - Added concurrency stubs: asynpool, base, eventlet, gevent, prefork, solo, thread - Added worker stubs: components, consumer/*, control, heartbeat, loops, pidbox, request, state, strategy, worker - Added utils stubs: collections, debug, dispatch, functional, graph, imports, iso8601, log, nodenames, objects, serialization, term, text, threads, time, timer2 - Enhanced existing module type annotations with more complete signatures - Added @OverRide decorators for proper method override annotations
oliverhaas
force-pushed
the
celery-stubs-improvements
branch
from
b0571fe to
e3460ff
Compare
9en9i
reviewed
Jan 8, 2026
| autofinalize: bool = True, | ||
| namespace: str | None = None, | ||
| strict_typing: bool = True, | ||
| broker_connection_retry: bool = ..., |
Contributor
There was a problem hiding this comment.
Are all these arguments really missing? Or is this a mistake? I assume that these arguments are actually present in kwargs, and if so, I think it would be more useful to explicitly mark them as keyword-only using *,.
Contributor
Author
There was a problem hiding this comment.
Celery makes this kind of awkward, since it's not an explicit kwarg in the actual code. I guess keeping it makes more sense from a practical point.
Contributor
There was a problem hiding this comment.
Please check the other places. I have seen it in at least one other class. And, by the way, perhaps it would make sense to mark them with '*,'?
Contributor
There was a problem hiding this comment.
Contributor
Author
There was a problem hiding this comment.
You were totally right. I adjusted this code and checked all other similar cases. Hopefully I got everything.
….apply_async Restore explicit keyword arguments for better IDE autocomplete support: - Celery.__init__: Add config kwargs (imports, broker_*, result_*, task_*, worker_*) - Celery._task_from_fun: Add autoretry and task option kwargs - Signature.apply_async: Add options kwargs (task_id, producer, link, countdown, etc.) Use keyword-only syntax (*,) to satisfy stubtest while still providing typed kwargs for IDE support.
oliverhaas
force-pushed
the
celery-stubs-improvements
branch
from
ed8bf79 to
60d818d
Compare
9en9i
reviewed
Jan 8, 2026
- Remove Proxy wrapper from current_app, current_task, default_app types
- send_task: Add explicit kwargs after * for better IDE autocomplete:
ignore_result, priority, queue, exchange, routing_key, exchange_type,
stamped_headers (all passed through **options at runtime)
- add_periodic_task: Fix kwargs type from tuple[()] to dict[str, Any] | None
(runtime uses empty tuple as falsy default, converted to {} internally)
Improve IDE autocomplete by adding explicit kwargs after * for all major public API methods that accept **options or **kwargs at runtime. canvas.pyi: - Signature.apply: add Task.apply options - _chain.apply_async, run: add Signature.apply_async options - _basemap.apply_async: add options - chunks.__call__, apply_async: add options - group.__init__: consolidate overloads, add options - group.apply_async: add options - chord.run, apply, apply_async, __call__: add options app/task.pyi: - Task.AsyncResult: add backend, app, parent kwargs - Task.signature, subtask: add Signature options result.pyi: - AsyncResult.collect: add get() options
- main: str (always set in __init__) - steps: defaultdict[str, set[Any]] (always initialized) - user_options: defaultdict[str, set[Any]] (fix type and make non-optional) - builtin_fixups: set[str] (already non-optional) These are always set on instances, so typing them as optional was misleading for users who work with Celery app instances.
- AsyncResult.id: str (always set in __init__) - Task.name: str (always set when task is bound) - Signal.receivers: list (always initialized in __init__) - Celery main, steps, user_options, builtin_fixups (always set in __init__) All attributes are None at class level but typed as non-optional since users work with instances, not the class itself.
Control.inspect is a cached_property that returns a CLASS (type[Inspect]), not an instance. Usage is: app.control.inspect(destination=['worker1'])
oliverhaas
commented
Jan 11, 2026
| matcher: Callable[..., Any] | None = ..., | ||
| ) -> Inspect: ... | ||
| @property | ||
| def inspect(self) -> type[Inspect]: ... |
Contributor
Author
There was a problem hiding this comment.
The inspect() change above looks a bit weird but is technically correct and not changing DX behavior. Basically Inspect.init() is just being mapped here.
Both are always resolved to bool from config on task instances, never None. Only None at class level before binding.
- Control.app: Celery (required, __init__ immediately accesses app.conf) - AsyncResult.app: Celery (always resolved via app_or_default()) - AsyncResult.backend: Backend (always resolved via self.app.backend) All are None at class level but always non-None on instances.
The celery.app.beat module doesn't exist at runtime - the correct module is celery.apps.beat (note the 's'). This stub was causing stubtest errors.
Contributor
Author
|
I think this looks good now from my end. If this gets merged I will submit a PR which introduces stubtest and ty into CI, which I think will be important feedback for these and future changes. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Basically same as #207.
CI should pass if #207 and #209 are merged before this...