[tjkuson]

Summary

Document asyncio.to_thread and loop.run_in_executor as alternatives for ASYNC240 and make the diagnostic library-neutral.

I noticed that ASYNC240's message and documentation recommended anyio and trio as alternatives to blocking path operations. This is confusing in projects where anyio or trio are not used. When making the change I also noticed some other issues (the rule reports os.path functions rather than methods and the docs referenced a nonexistent pathlib.Path.dirname method).

Adds a reference to aiofiles which is a very popular library for async path operations.

Test Plan

Built the docs and looked at it.

[astral-sh-bot]

ruff-ecosystem results

Linter (stable)

ℹ️ ecosystem check detected linter changes. (+2 -2 violations, +0 -0 fixes in 1 projects; 58 projects unchanged)

bokeh/bokeh (+2 -2 violations, +0 -0 fixes)

ruff check --no-cache --exit-zero --no-fix --output-format concise --no-preview --select ALL

+ src/bokeh/server/asgi.py:391:21: ASYNC240 Async functions should not perform blocking pathlib.Path operations
- src/bokeh/server/asgi.py:391:21: ASYNC240 Async functions should not use pathlib.Path methods, use trio.Path or anyio.path
+ src/bokeh/server/views/static_handler.py:145:16: ASYNC240 Async functions should not perform blocking os.path operations
- src/bokeh/server/views/static_handler.py:145:16: ASYNC240 Async functions should not use os.path methods, use trio.Path or anyio.path

Changes by rule (1 rules affected)

code	total	+ violation	- violation	+ fix	- fix
ASYNC240	4	2	2	0	0

Linter (preview)

ℹ️ ecosystem check detected linter changes. (+91 -91 violations, +0 -0 fixes in 2 projects; 57 projects unchanged)

bokeh/bokeh (+2 -2 violations, +0 -0 fixes)

ruff check --no-cache --exit-zero --no-fix --output-format concise --preview --select ALL

+ src/bokeh/server/asgi.py:391:21: blocking-path-method-in-async-function Async functions should not perform blocking pathlib.Path operations
- src/bokeh/server/asgi.py:391:21: blocking-path-method-in-async-function Async functions should not use pathlib.Path methods, use trio.Path or anyio.path
+ src/bokeh/server/views/static_handler.py:145:16: blocking-path-method-in-async-function Async functions should not perform blocking os.path operations
- src/bokeh/server/views/static_handler.py:145:16: blocking-path-method-in-async-function Async functions should not use os.path methods, use trio.Path or anyio.path

prefecthq/prefect (+89 -89 violations, +0 -0 fixes)

ruff check --no-cache --exit-zero --no-fix --output-format concise --preview

+ benches/bench_count_flow_runs.py:190:12: blocking-path-method-in-async-function Async functions should not perform blocking os.path operations
- benches/bench_count_flow_runs.py:190:12: blocking-path-method-in-async-function Async functions should not use os.path methods, use trio.Path or anyio.path
+ client/client_deploy.py:32:20: blocking-path-method-in-async-function Async functions should not perform blocking pathlib.Path operations
- client/client_deploy.py:32:20: blocking-path-method-in-async-function Async functions should not use pathlib.Path methods, use trio.Path or anyio.path
+ integration-tests/test_nested_cancellation.py:120:12: blocking-path-method-in-async-function Async functions should not perform blocking pathlib.Path operations
- integration-tests/test_nested_cancellation.py:120:12: blocking-path-method-in-async-function Async functions should not use pathlib.Path methods, use trio.Path or anyio.path
+ integration-tests/test_nested_cancellation.py:53:5: blocking-path-method-in-async-function Async functions should not perform blocking pathlib.Path operations
- integration-tests/test_nested_cancellation.py:53:5: blocking-path-method-in-async-function Async functions should not use pathlib.Path methods, use trio.Path or anyio.path
+ integration-tests/test_nested_cancellation.py:64:5: blocking-path-method-in-async-function Async functions should not perform blocking pathlib.Path operations
- integration-tests/test_nested_cancellation.py:64:5: blocking-path-method-in-async-function Async functions should not use pathlib.Path methods, use trio.Path or anyio.path
+ integration-tests/test_nested_cancellation.py:69:9: blocking-path-method-in-async-function Async functions should not perform blocking pathlib.Path operations
- integration-tests/test_nested_cancellation.py:69:9: blocking-path-method-in-async-function Async functions should not use pathlib.Path methods, use trio.Path or anyio.path
+ integration-tests/test_runner_resilience.py:90:12: blocking-path-method-in-async-function Async functions should not perform blocking pathlib.Path operations
- integration-tests/test_runner_resilience.py:90:12: blocking-path-method-in-async-function Async functions should not use pathlib.Path methods, use trio.Path or anyio.path
+ src/integrations/prefect-aws/prefect_aws/s3.py:1047:32: blocking-path-method-in-async-function Async functions should not perform blocking pathlib.Path operations
- src/integrations/prefect-aws/prefect_aws/s3.py:1047:32: blocking-path-method-in-async-function Async functions should not use pathlib.Path methods, use trio.Path or anyio.path
+ src/integrations/prefect-aws/prefect_aws/s3.py:1462:23: blocking-path-method-in-async-function Async functions should not perform blocking pathlib.Path operations
- src/integrations/prefect-aws/prefect_aws/s3.py:1462:23: blocking-path-method-in-async-function Async functions should not use pathlib.Path methods, use trio.Path or anyio.path
+ src/integrations/prefect-aws/prefect_aws/s3.py:1690:21: blocking-path-method-in-async-function Async functions should not perform blocking pathlib.Path operations
- src/integrations/prefect-aws/prefect_aws/s3.py:1690:21: blocking-path-method-in-async-function Async functions should not use pathlib.Path methods, use trio.Path or anyio.path
+ src/integrations/prefect-aws/prefect_aws/s3.py:1950:25: blocking-path-method-in-async-function Async functions should not perform blocking pathlib.Path operations
- src/integrations/prefect-aws/prefect_aws/s3.py:1950:25: blocking-path-method-in-async-function Async functions should not use pathlib.Path methods, use trio.Path or anyio.path
+ src/integrations/prefect-aws/prefect_aws/s3.py:960:30: blocking-path-method-in-async-function Async functions should not perform blocking pathlib.Path operations
- src/integrations/prefect-aws/prefect_aws/s3.py:960:30: blocking-path-method-in-async-function Async functions should not use pathlib.Path methods, use trio.Path or anyio.path
+ src/integrations/prefect-aws/prefect_aws/s3.py:962:30: blocking-path-method-in-async-function Async functions should not perform blocking pathlib.Path operations
- src/integrations/prefect-aws/prefect_aws/s3.py:962:30: blocking-path-method-in-async-function Async functions should not use pathlib.Path methods, use trio.Path or anyio.path
+ src/integrations/prefect-aws/prefect_aws/s3.py:971:17: blocking-path-method-in-async-function Async functions should not perform blocking os.path operations
- src/integrations/prefect-aws/prefect_aws/s3.py:971:17: blocking-path-method-in-async-function Async functions should not use os.path methods, use trio.Path or anyio.path
+ src/integrations/prefect-aws/tests/test_s3.py:616:22: blocking-path-method-in-async-function Async functions should not perform blocking pathlib.Path operations
- src/integrations/prefect-aws/tests/test_s3.py:616:22: blocking-path-method-in-async-function Async functions should not use pathlib.Path methods, use trio.Path or anyio.path
+ src/integrations/prefect-azure/prefect_azure/blob_storage.py:602:24: blocking-path-method-in-async-function Async functions should not perform blocking pathlib.Path operations
- src/integrations/prefect-azure/prefect_azure/blob_storage.py:602:24: blocking-path-method-in-async-function Async functions should not use pathlib.Path methods, use trio.Path or anyio.path
+ src/integrations/prefect-azure/prefect_azure/blob_storage.py:604:29: blocking-path-method-in-async-function Async functions should not perform blocking pathlib.Path operations
- src/integrations/prefect-azure/prefect_azure/blob_storage.py:604:29: blocking-path-method-in-async-function Async functions should not use pathlib.Path methods, use trio.Path or anyio.path
+ src/integrations/prefect-azure/prefect_azure/blob_storage.py:670:32: blocking-path-method-in-async-function Async functions should not perform blocking pathlib.Path operations
- src/integrations/prefect-azure/prefect_azure/blob_storage.py:670:32: blocking-path-method-in-async-function Async functions should not use pathlib.Path methods, use trio.Path or anyio.path
+ src/integrations/prefect-azure/prefect_azure/bundles/execute.py:88:17: blocking-path-method-in-async-function Async functions should not perform blocking pathlib.Path operations
- src/integrations/prefect-azure/prefect_azure/bundles/execute.py:88:17: blocking-path-method-in-async-function Async functions should not use pathlib.Path methods, use trio.Path or anyio.path
+ src/integrations/prefect-azure/prefect_azure/bundles/upload.py:26:12: blocking-path-method-in-async-function Async functions should not perform blocking pathlib.Path operations
- src/integrations/prefect-azure/prefect_azure/bundles/upload.py:26:12: blocking-path-method-in-async-function Async functions should not use pathlib.Path methods, use trio.Path or anyio.path
+ src/integrations/prefect-azure/prefect_azure/ml_datastore.py:185:34: blocking-path-method-in-async-function Async functions should not perform blocking os.path operations
- src/integrations/prefect-azure/prefect_azure/ml_datastore.py:185:34: blocking-path-method-in-async-function Async functions should not use os.path methods, use trio.Path or anyio.path
+ src/integrations/prefect-gcp/prefect_gcp/bigquery.py:873:12: blocking-path-method-in-async-function Async functions should not perform blocking os.path operations
- src/integrations/prefect-gcp/prefect_gcp/bigquery.py:873:12: blocking-path-method-in-async-function Async functions should not use os.path methods, use trio.Path or anyio.path
+ src/integrations/prefect-gcp/prefect_gcp/bigquery.py:875:14: blocking-path-method-in-async-function Async functions should not perform blocking os.path operations
- src/integrations/prefect-gcp/prefect_gcp/bigquery.py:875:14: blocking-path-method-in-async-function Async functions should not use os.path methods, use trio.Path or anyio.path
+ src/integrations/prefect-gcp/prefect_gcp/cloud_storage.py:1179:26: blocking-path-method-in-async-function Async functions should not perform blocking os.path operations
- src/integrations/prefect-gcp/prefect_gcp/cloud_storage.py:1179:26: blocking-path-method-in-async-function Async functions should not use os.path methods, use trio.Path or anyio.path
... 130 additional changes omitted for project

Changes by rule (1 rules affected)

code	total	+ violation	- violation	+ fix	- fix
blocking-path-method-in-async-function	182	91	91	0	0

[ntBre]

Wow, thank you! This would have helped me when I enabled this rule on Ruff itself in #28112. I ended up ignoring it because I didn't want to add a third-party dependency.

Our usage isn't too performance-sensitive, so I think it's okay to leave it ignored, but I probably would have applied this fix if I had known!