|
| 1 | +use ruff_macros::{ViolationMetadata, derive_message_formats}; |
| 2 | +use ruff_python_ast::helpers::map_callable; |
| 3 | +use ruff_python_ast::{self as ast, Expr, Stmt}; |
| 4 | +use ruff_python_semantic::ScopeKind; |
| 5 | +use ruff_text_size::Ranged; |
| 6 | + |
| 7 | +use crate::Violation; |
| 8 | +use crate::checkers::ast::Checker; |
| 9 | + |
| 10 | +/// ## What it does |
| 11 | +/// Checks for `yield` inside a context manager in an async generator. |
| 12 | +/// |
| 13 | +/// ## Why is this bad? |
| 14 | +/// Yielding inside a context manager in an async generator is unsafe because |
| 15 | +/// the cleanup of the context manager may be delayed until the generator is |
| 16 | +/// closed, at which point `await` is no longer allowed. This can lead to |
| 17 | +/// resource leaks or other bugs. |
| 18 | +/// |
| 19 | +/// For more information, see [PEP 533](https://peps.python.org/pep-0533/). |
| 20 | +/// |
| 21 | +/// If the function is intended to yield only once and act as a context |
| 22 | +/// manager, use `@asynccontextmanager`. If it's a true async generator |
| 23 | +/// that yields multiple values, consumers should use `contextlib.aclosing` to |
| 24 | +/// ensure timely cleanup, or the generator should be refactored to avoid |
| 25 | +/// holding context managers open across yields. |
| 26 | +/// |
| 27 | +/// The rule also suppresses diagnostics for functions decorated with |
| 28 | +/// `@pytest.fixture` or `@pytest_asyncio.fixture`, as the pytest runner |
| 29 | +/// handles generator cleanup automatically. |
| 30 | +/// |
| 31 | +/// ## Example |
| 32 | +/// |
| 33 | +/// The following function yields once inside a context manager, but without |
| 34 | +/// `@asynccontextmanager`, cleanup of the connection may be delayed: |
| 35 | +/// ```python |
| 36 | +/// async def open_connection(): |
| 37 | +/// async with connect() as conn: |
| 38 | +/// yield conn |
| 39 | +/// ``` |
| 40 | +/// |
| 41 | +/// If the function is intended to yield exactly once (i.e., it's a context |
| 42 | +/// manager), add `@asynccontextmanager`: |
| 43 | +/// ```python |
| 44 | +/// from contextlib import asynccontextmanager |
| 45 | +/// |
| 46 | +/// |
| 47 | +/// @asynccontextmanager |
| 48 | +/// async def open_connection(): |
| 49 | +/// async with connect() as conn: |
| 50 | +/// yield conn |
| 51 | +/// ``` |
| 52 | +/// |
| 53 | +/// For async generators that yield multiple values, `@asynccontextmanager` |
| 54 | +/// is not appropriate. Instead, refactor to avoid holding context managers |
| 55 | +/// open across yields, or ensure consumers use `contextlib.aclosing` for timely |
| 56 | +/// cleanup. |
| 57 | +/// |
| 58 | +/// ## Known problems |
| 59 | +/// Using `contextlib.aclosing` around all call sites of an async generator is a |
| 60 | +/// valid way to guarantee timely cleanup, but this rule cannot verify that |
| 61 | +/// all callers use `aclosing`. As a result, it may flag generators that |
| 62 | +/// are always consumed safely. |
| 63 | +/// |
| 64 | +/// ## References |
| 65 | +/// - [PEP 533 – Deterministic cleanup for iterators](https://peps.python.org/pep-0533/) |
| 66 | +/// - [`contextlib.aclosing`](https://docs.python.org/3/library/contextlib.html#contextlib.aclosing) |
| 67 | +/// - [trio.as_safe_channel](https://trio.readthedocs.io/en/latest/reference-core.html#trio.as_safe_channel) |
| 68 | +#[derive(ViolationMetadata)] |
| 69 | +#[violation_metadata(preview_since = "NEXT_RUFF_VERSION")] |
| 70 | +pub(crate) struct YieldInContextManagerInAsyncGenerator; |
| 71 | + |
| 72 | +impl Violation for YieldInContextManagerInAsyncGenerator { |
| 73 | + #[derive_message_formats] |
| 74 | + fn message(&self) -> String { |
| 75 | + "Yield in context manager in async generator may not trigger cleanup".to_string() |
| 76 | + } |
| 77 | + |
| 78 | + fn fix_title(&self) -> Option<String> { |
| 79 | + Some("Use `@asynccontextmanager` if appropriate, or refactor".to_string()) |
| 80 | + } |
| 81 | +} |
| 82 | + |
| 83 | +/// ASYNC119 |
| 84 | +pub(crate) fn yield_in_context_manager_in_async_generator(checker: &Checker, expr: &Expr) { |
| 85 | + // Check that the enclosing scope is an async function. |
| 86 | + let Some(function_def) = enclosing_async_function(checker) else { |
| 87 | + return; |
| 88 | + }; |
| 89 | + |
| 90 | + // If the function is decorated with `@asynccontextmanager` or `@pytest.fixture`, |
| 91 | + // the yield is safe — these decorators handle async generator cleanup properly. |
| 92 | + if has_safe_decorator(checker, function_def) { |
| 93 | + return; |
| 94 | + } |
| 95 | + |
| 96 | + // Walk up the statement hierarchy to check if this yield is inside a `with` block. |
| 97 | + // Stop at function/class boundaries, since nested definitions create a new scope. |
| 98 | + for stmt in checker.semantic().current_statements() { |
| 99 | + match stmt { |
| 100 | + Stmt::With(_) => { |
| 101 | + checker.report_diagnostic(YieldInContextManagerInAsyncGenerator, expr.range()); |
| 102 | + return; |
| 103 | + } |
| 104 | + Stmt::FunctionDef(_) | Stmt::ClassDef(_) => return, |
| 105 | + _ => {} |
| 106 | + } |
| 107 | + } |
| 108 | +} |
| 109 | + |
| 110 | +/// Returns the enclosing `async` function definition, if any. |
| 111 | +fn enclosing_async_function<'a>(checker: &Checker<'a>) -> Option<&'a ast::StmtFunctionDef> { |
| 112 | + for scope in checker.semantic().current_scopes() { |
| 113 | + match scope.kind { |
| 114 | + ScopeKind::Function(function_def) if function_def.is_async => { |
| 115 | + return Some(function_def); |
| 116 | + } |
| 117 | + // Nested functions, lambdas, and classes break the chain. |
| 118 | + ScopeKind::Function(_) | ScopeKind::Lambda(_) | ScopeKind::Class(_) => return None, |
| 119 | + _ => {} |
| 120 | + } |
| 121 | + } |
| 122 | + None |
| 123 | +} |
| 124 | + |
| 125 | +/// Returns `true` if the function is decorated with `@asynccontextmanager` |
| 126 | +/// or `@pytest.fixture`, which are known to handle async generator cleanup |
| 127 | +/// safely. |
| 128 | +fn has_safe_decorator(checker: &Checker, function_def: &ast::StmtFunctionDef) -> bool { |
| 129 | + function_def.decorator_list.iter().any(|decorator| { |
| 130 | + checker |
| 131 | + .semantic() |
| 132 | + .resolve_qualified_name(map_callable(&decorator.expression)) |
| 133 | + .is_some_and(|qualified_name| { |
| 134 | + matches!( |
| 135 | + qualified_name.segments(), |
| 136 | + ["contextlib", "asynccontextmanager"] |
| 137 | + | ["pytest" | "pytest_asyncio", "fixture"] |
| 138 | + ) |
| 139 | + }) |
| 140 | + }) |
| 141 | +} |
0 commit comments