Skip to content

Add stubs for APScheduler - #16855

Closed
kbr- wants to merge 1 commit into
python:mainfrom
kbr-:apscheduler-stubs
Closed

kbr- wants to merge 1 commit into
python:mainfrom
kbr-:apscheduler-stubs

Conversation

@kbr-

@kbr- kbr- commented Nov 18, 2026 •

Copy link
Copy Markdown

Add stubs for APScheduler

APScheduler 3.11 ships no type information; this adds partial stubs for its scheduler, job, interval
trigger, job store and executor bases, and events.

Upstream: the 3.x source and
documentation.

Written with Claude Code (Claude Opus 5.5).

@github-actions

This comment has been minimized.

@kbr-
kbr- force-pushed the apscheduler-stubs branch from 8885469 to 2e6aaea Compare November 18, 2026 10:04
@github-actions

This comment has been minimized.

@kbr-
kbr- force-pushed the apscheduler-stubs branch from 2e6aaea to 27fbf56 Compare November 18, 2026 10:23
@github-actions

This comment has been minimized.

@kbr-

kbr- commented Nov 18, 2026

Copy link
Copy Markdown
Author

The mypy_primer hit in dragonchain is a true positive of dragonchain's code.
timing_event_utest.py
does only import apscheduler, then reads apscheduler.jobstores.base.ConflictingIdError at line 101.
APScheduler's __init__.py imports no submodule, so that attribute exists at runtime only because
another import (here dragonchain/scheduler/timing_event.py's from apscheduler.jobstores.base import ConflictingIdError)
loaded the submodule first. mypy reports the same error for that pattern with apscheduler.jobstores.base
stubbed, so no change to these stubs removes it.

@srittau srittau left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please remove the tests. In typeshed, we only add regression tests for functions and classes which are known to have caused complex problems in the past, or where stubs are difficult to get right. 100% test coverage for typeshed is neither necessary nor desirable, as it would lead to code duplication.

See tests/REGRESSION.md for more information.

Generally, any non-obvious Any needs to be explained. See here. I've noted a few instances below, but there are more.

Comment on lines +24 to +25
def __init__(self, gconfig: Mapping[str, Any] = {}, **options: Any) -> None: ...
def configure(self, gconfig: Mapping[str, Any] = {}, prefix: str | None = "apscheduler.", **options: Any) -> None: ...

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As far as I can see, there are a few concrete options, meaning that we should either list there here with their concrete types or just leave options unannotated for now.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

options is now Unpack[_SchedulerOptions], a TypedDict of the six options _configure reads (logger, timezone, jobstore_retry_interval, job_defaults, executors, jobstores), each with the types it converts from. gconfig is Mapping[str, object]: its dotted keys hold the same options.

@property
def running(self) -> bool: ...
# An executor is an apscheduler.executors.base.BaseExecutor or the name of an executor plugin.
def add_executor(self, executor, alias: str = "default", **executor_opts: Any) -> None: ...

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

executor_opts needs a short explanation for why Any is needed. (Might be something like "options are passed to ...".)

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

executor_opts is object now, with a comment: they go to the constructor of the executor plugin that executor names, and an executor instance ignores them. executor itself is BaseExecutor | str, with stubs for apscheduler.executors.base.

def add_executor(self, executor, alias: str = "default", **executor_opts: Any) -> None: ...
def remove_executor(self, alias: str, shutdown: bool = True) -> None: ...
# A job store, or the name of a job store plugin.
def add_jobstore(self, jobstore: BaseJobStore | str, alias: str = "default", **jobstore_opts: Any) -> None: ...

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same here.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same here: object, with a comment that they go to the constructor of the job store plugin that jobstore names, and that a job store instance ignores them.

Comment on lines +46 to +47
args: Iterable[Any] | None = None,
kwargs: Mapping[str, Any] | None = None,

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same here for args and kwargs. Probably something like "args and kwargs are passed to func".

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Iterable[object] and Mapping[str, object] now, with the comment "args and kwargs are passed to func when the job runs"; Job.args and Job.kwargs likewise.

@kbr-
kbr- force-pushed the apscheduler-stubs branch from 27fbf56 to 27739db Compare November 18, 2026 13:21
@kbr-

kbr- commented Nov 18, 2026

Copy link
Copy Markdown
Author

Thanks. The tests are removed, and no annotation in the package is Any or Incomplete now: each value has the type the runtime gives it, or object where the value is handed to a signature the stubs can't know, with a comment saying where it goes. Beyond the ones noted below: Job's constructor, Job.modify and modify_job take a TypedDict of the attributes Job._modify accepts; Job.func is Callable[..., object]; add_listener's callback takes an apscheduler.events.SchedulerEvent, with stubs for apscheduler.events; and trigger_args are object, with a comment that they go to the constructor of the trigger class the name selects.

@github-actions

This comment has been minimized.

APScheduler 3.11 ships no type information; this adds partial stubs for its scheduler, job, interval
trigger, job store and executor bases, and events.

Upstream: [the 3.x source](https://github.com/agronholm/apscheduler/tree/3.x/src/apscheduler) and
[documentation](https://apscheduler.readthedocs.io/en/3.x/).

Written with Claude Code (Claude Opus 5.5).
@kbr-
kbr- force-pushed the apscheduler-stubs branch from 27739db to 4386794 Compare November 18, 2026 13:41
@kbr-

kbr- commented Nov 18, 2026

Copy link
Copy Markdown
Author

On mypy_primer's dragonchain hits: the two add_listener errors were the stub's, since a listener receives the event class its mask selects; add_listener and remove_listener now take a callback of any SchedulerEvent subclass. The four event.exception errors are true positives: JobExecutionEvent.exception is None for EVENT_JOB_EXECUTED and EVENT_JOB_MISSED events, and run_job catches BaseException, so a job raising SystemExit reports one, while dragonchain passes it where Exception is expected. The jobstores hit is the one explained above.

@github-actions

Copy link
Copy Markdown
Contributor

Diff from mypy_primer, showing the effect of this PR on open source code:

dragonchain (https://github.com/dragonchain/dragonchain)
+ dragonchain/scheduler/background_scheduler.py:28:52: error: Argument 1 to "get_exception_message" has incompatible type "BaseException | None"; expected "Exception"  [arg-type]
+ dragonchain/scheduler/background_scheduler.py:29:37: error: Argument 1 to "report_exception" has incompatible type "BaseException | None"; expected "Exception"  [arg-type]
+ dragonchain/scheduler/timing_event_utest.py:101:21: error: Module has no attribute "jobstores"  [attr-defined]
+ dragonchain/transaction_processor/transaction_processor.py:63:52: error: Argument 1 to "get_exception_message" has incompatible type "BaseException | None"; expected "Exception"  [arg-type]
+ dragonchain/transaction_processor/transaction_processor.py:64:37: error: Argument 1 to "report_exception" has incompatible type "BaseException | None"; expected "Exception"  [arg-type]

@srittau

srittau commented Nov 18, 2026

Copy link
Copy Markdown
Collaborator

each value has the type the runtime gives it, or object where the value is handed to a signature the stubs can't know, with a comment saying where it goes.

Please note that this actually not correct. object should only be used when every value is accepted (like for str()). Any is the correct type to express "this type can't be expressed properly using the type system.

@kbr- kbr- closed this Nov 18, 2026
@kbr-

kbr- commented Nov 18, 2026

Copy link
Copy Markdown
Author

Please note that this actually not correct. object should only be used when every value is accepted (like for str()). Any is the correct type to express "this type can't be expressed properly using the type system.

Right.
I'll close this PR, since I force-pushed it, and open a new one with corrected typing.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants