How we author Python code.
File Headers
Import Organization
Module Structure
from __future__ import annotations
when needed, and organize imports in four distinct groups with alphabetical ordering within each group. Related imports are grouped together, and we prefer absolute imports for clarity.
Import Style
from __future__ import annotations
at the top of files that use forward referencessnake_case
for variables and functions, PascalCase
for classes, UPPER_SNAKE_CASE
for constants, and single leading underscores for private members. Names should be descriptive and avoid abbreviations unless they’re well-known in the domain.
Variables and Functions
snake_case
for variables, functions, and module namesClasses
PascalCase
for class namesConstants
UPPER_SNAKE_CASE
for module-level constantsPrivate Members
Function Signatures
Class Definitions
ABC
, BaseModel
, etc.)Basic Types
Union Types
|
syntax for union types (Python 3.10+):Generic Types
Forward References
from __future__ import annotations
for forward references over string annotations:Docstrings
Inline Comments
# CHECK
for areas that need review# INCOMPLETE
for unfinished functionalityLine Length
Spacing
=
in keyword argumentsBlock Comments
String Formatting
Exception Classes
Error Messages
Exception Handling
raise ... from ex
to preserve context.test/
directory that mirrors the source code structure.
Test Structure
test_
prefixTest Files
_test.py
test/
directoryExternal Dependencies
Internal Dependencies