temporalint

Static checks for Temporal Python SDK code. Temporal's workflow APIs fail at runtime for mistakes Python will not catch: a missing activity timeout, a discarded coroutine, a workflow class the worker will reject, or a nondeterministic call that breaks replay.

Install

pip install temporalint

Usage

temporalint [paths...] [--select TPL001,TPL007] [--ignore TPL009]

Rules

Configuration

Settings can live in temporalint.toml, .temporalint.toml, or pyproject.toml. Discovery starts at the working directory and walks toward the filesystem root. In each directory, temporalint.toml wins over .temporalint.toml, which wins over pyproject.toml. Every rule except TPL003 is enabled when select and ignore are omitted. List TPL003 in select to turn it on.

temporalint.toml and .temporalint.toml put the keys at the top level:

select = ["TPL001", "TPL002", "TPL003", "TPL004", "TPL005", "TPL006", "TPL007", "TPL008", "TPL009", "TPL010"]
ignore = ["TPL009"]
exclude = ["tests/**", "**/migrations/**"]

The same settings in pyproject.toml sit under [tool.temporalint]:

[tool.temporalint]
select = ["TPL001", "TPL002", "TPL003", "TPL004", "TPL005", "TPL006", "TPL007", "TPL008", "TPL009", "TPL010"]
ignore = ["TPL009"]
exclude = ["tests/**", "**/migrations/**"]

--select and --ignore replace the corresponding config values when you pass them. exclude is a list of glob patterns matched against the path relative to the config file's directory. An explicit file argument is still linted when it matches an exclude pattern.

Limitations

• Helper functions called from a workflow are not analyzed. Keep determinism-sensitive code in the workflow class, or review helpers separately.
• from temporalio.workflow import * and relative imports are not resolved.
• The timeout check looks for the keyword, not the value. start_to_close_timeout=None is not reported, and **kwargs suppresses TPL001.
• Argument counts, payload types, and activity names passed as strings are not checked yet.
• TPL004 only follows activities and helpers defined in the same module. It stays quiet when the activity has another decorator or calls an imported non-stdlib function or an unknown name, because those may heartbeat. Method calls on objects other than self are assumed not to heartbeat.
• TPL010 cannot see workflow_failure_exception_types on the worker. A type allowed only there is still reported.