# Writing Idiomatic Python with Clear Intent

> Write idiomatic Python by choosing readable iteration, explicit error behavior, and local conventions over compressed expressions that hide ownership or business rules.

- Canonical HTML: [https://unrust.dev/languages/python/idiomatic-code](https://unrust.dev/languages/python/idiomatic-code)
- Markdown representation: [https://unrust.dev/languages/python/idiomatic-code/index.md](https://unrust.dev/languages/python/idiomatic-code/index.md)

Published: 2026-07-14

## Direct answer

Idiomatic Python favors code that a reader can understand in the context of the language and the repository: clear iteration, appropriately scoped comprehensions, explicit error behavior, and straightforward data ownership. It is not a contest to use the most language features. Prefer the version that makes the next change safer, especially when a compact expression would hide a policy decision, side effect, or failure path.

## Use Python's concise forms when they remain legible

Comprehensions, unpacking, context managers, and enumerate can clarify common work, but each has a point where a named loop or helper is easier to test. Ask whether a reader can see the filtering rule, error path, and ownership of mutable data without mentally expanding a dense expression.

## Let local code answer style questions

Python projects vary in their approaches to exceptions, dataclasses, typing, imports, and I/O. Read the surrounding modules, linters, and tests before introducing a pattern, then justify deviations with a concrete benefit such as clearer failure behavior or a simpler API for callers.

## Original example

### Make an index's purpose visible while iterating

```python
for position, record in enumerate(records, start=1):
    log_position(position, record["id"])
```

This original Python example uses enumerate because position has a clear reader-facing purpose. It would not be more idiomatic if the index were unused or if record could lack an id without handling. The surrounding logging and validation contract decides whether this concise form remains the clearest option.

## Checklist

- Does this Python shorthand make the policy clearer than a few named lines?
- Where are exceptions and mutable ownership visible to the next reader?
- Does this match the repository's existing typing and error conventions?

## Practice loop

1. Rewrite one manual Python counter loop using enumerate only if it makes the index purpose clearer.
2. Compare a comprehension and a named loop for a rule with validation or error handling.
3. Check nearby Python modules before labeling a valid pattern idiomatic for this project.

## Limits of this page

Python idioms depend on the version, team conventions, performance constraints, and the surrounding application. A short code-style exercise can prompt a useful explanation, but it cannot determine why a convention was unfamiliar or rank someone's engineering judgment.

## Source context

Editorially reviewed for Unrust using public language documentation, common code-review practice, and small original examples written for this resource system.

## Related resources

- [How to Prepare for a Focused Code Review](https://unrust.dev/use-cases/prepare-for-code-review/index.md): Prepare a small, evidence-rich code review by clarifying the contract, reducing unrelated changes, and showing tests that cover the risky behavior.
- [How to Test an AI-Suggested Refactor](https://unrust.dev/use-cases/test-an-ai-suggested-refactor/index.md): Test an AI-suggested refactor by preserving observable behavior, specifying invariants, and comparing before-and-after cases instead of trusting cleaner-looking code.

Next step: [Take the free diagnostic](https://unrust.dev/diagnostic/index.md)