Python Code Review

Quick Reference

Review Checklist

PEP8 Style

• 4-space indentation (no tabs)
• Line length ≤79 characters (≤72 for docstrings/comments)
• Two blank lines around top-level definitions, one within classes
• Imports grouped: stdlib → third-party → local (blank line between groups)
• No whitespace inside brackets or before colons/commas
• Naming:

  snake_case

  for functions/variables,

  CamelCase

  for classes,

  UPPER_CASE

  for constants
• Inline comments separated by at least two spaces

Type Safety

• Type hints on all function parameters and return types
• No

  Any

  unless necessary (with comment explaining why)
• Proper

  T | None

  syntax (Python 3.10+)

Async Patterns

• No blocking calls (

  time.sleep

  ,

  requests

  ) in async functions
• Proper

  await

  on all coroutines

Error Handling

• No bare

  except:

  clauses
• Specific exception types with context

• raise ... from

  to preserve stack traces

Common Mistakes

• No mutable default arguments
• Using

  logger

  not

  print()

  for output
• f-strings preferred over

  .format()

  or

  %

Valid Patterns (Do NOT Flag)

• Type annotation vs type assertion - Annotations declare types but are not runtime assertions; don't confuse with missing validation
• Using

  Any

  when interacting with untyped libraries - Required when external libraries lack type stubs
• Empty

  __init__.py

  files - Valid for package structure, no code required

• noqa

  comments - Valid when linter rule doesn't apply to specific case
• Using

  cast()

  after runtime type check - Correct pattern to inform type checker of narrowed type

Context-Sensitive Rules

_

When to Load References

• Reviewing code formatting/style → pep8-style.md
• Reviewing function signatures → type-safety.md
• Reviewing

  async def

  functions → async-patterns.md
• Reviewing try/except blocks → error-handling.md
• General Python review → common-mistakes.md

Review Questions

1. Does the code follow PEP8 formatting (indentation, line length, whitespace)?
2. Are imports properly grouped (stdlib → third-party → local)?
3. Do names follow conventions (snake_case, CamelCase, UPPER_CASE)?
4. Are all function signatures fully typed?
5. Are async functions truly non-blocking?
6. Do exceptions include meaningful context?
7. Are there any mutable default arguments?

Before Submitting Findings