[Feature]: Linter

[yaythomas]

What would you like?

The AWS Durable Execution TypeScript SDK has a client-side linter to parse for best practices and avoid common issues:

https://github.com/aws/aws-durable-execution-sdk-js/tree/main/packages/aws-durable-execution-sdk-js-eslint-plugin

Investigate how or if this can integrate with a modern Python IDE experience. Pylint does support custom plugins, but the newer/faster linter environment Ruff does not (astral-sh/ruff#283)

Possible Implementation

No response

Is this a breaking change?

No

Does this require an RFC?

No

Additional Context

No response

[leandrodamascena]

This is a really nice idea @yaythomas and I really like the lint project in Durable SDK TS.

I think Flake8 could work well here. It has good adoption (1M+ downloads/day), a mature plugin API, and fits nicely into CI/pre-commit workflows. Users who prefer Ruff for general linting can still run Flake8 just for the SDK-specific rules.

As you said, Ruff doesn't support custom plugins yet and that issue doesn't seem to be going anywhere soon. I think we can do the same with flake8.

Maybe we should think about both Flake8 and Pyright to cover different scenarios:

• Flake8 for CI, pre-commit hooks - catches non-determinism issues, best practices
• Pyright/Pylance for real-time IDE feedback - catches type errors, improper API usage
• Both should have the same types of checks, but working in different space in the development lifecycle journey

I think we can start with a basic Flake8 plugin - just AST visitors that flag violations like random.random() or datetime.now() inside durable functions. We can see if this works and then think about all the rules we want to cover.

We could also update our docs and maybe write a blog post explaining how to set up the plugins and why they matter for Durable execution.

I'd like to hear your opinion here. I can create a small PoC with this.

[leandrodamascena]

I built a working prototype and pushed it to branch feat/add-linter. This is a work in progress and I need to improve tests and code patterns, but this give an idea how it can work.

Went full with Flake8 because as mentioned Ruff doesn't support custom plugins (astral-sh/ruff#283 - open since 2023, no movement). Also, Flake8's plugin API works fine with CI, pre-commit, IDEs. If customers uses Ruff for general linting, they can run Flake8 for these SDK-specific rules.

The plugin is simple and walks the AST looking for functions with @durable_execution or @durable_step, then flags problematic patterns. It skips anything inside ctx.step(), ctx.invoke(), etc. since those are checkpointed.

Rules I created

Flake8 requires each rule to have a unique code (like DAR001). The prefix identifies the plugin (DAR = durable), and users can disable specific rules with # noqa: DAR001 or in their config. That's how Flake8 works - no way around it.

Code	What it catches
DAR001	random.random(), random.randint(), etc. outside steps
DAR002	datetime.now(), datetime.today(), datetime.utcnow() outside steps
DAR003	uuid.uuid1(), uuid.uuid4() outside steps
DAR004	time.time(), time.monotonic() outside steps
DAR005	os.environ access
DAR006	Network calls (requests.get, httpx.post, etc.) outside steps
DAR007	Durable ops inside @durable_step
DAR008	Mutating closure variables in steps

Each rule is a separate file under src/flake8_durable_execution/rules/. Adding new rules is just creating a new file that extends BaseRule and adding it to ALL_RULES in __init__.py.

For example:

# DAR001, DAR002
@durable_execution
def handler(event, ctx):
    value = random.randint(1, 100)
    now = datetime.now()

Separate package

This should be published as flake8-durable-execution (or any other name) on PyPI, not bundled with the SDK. Different dependencies, independent release cycle, optional install. This also doesn't need to be shipped to production as part of the durable function deployment. That's how all Flake8 plugins work (flake8-bugbear, flake8-comprehensions, etc.).

pip install flake8-durable-execution
flake8 my_durable_functions.py

Or with pre-commit:

repos:
  - repo: https://github.com/pycqa/flake8
    rev: 7.0.0
    hooks:
      - id: flake8
        additional_dependencies: [flake8-durable-execution]

With CI (GitHub Actions):

- name: Lint
  run: |
    pip install flake8 flake8-durable-execution
    flake8 src/

Works in IDEs too - VS Code with the Python extension picks it up automatically once flake8-durable-execution is installed:

Please let me know what you think.