python-coding-standards

Python Guidelines

Imports - NON-NEGOTIABLE

ALL imports go at the top of the file. Every single one. If you're even thinking about putting an import inside a function, stop.

Exception: circular import issues (genuinely rare).

Don't abbreviate packages ("pandas" not "pd", "numpy" not "np").

Modern Python

We use python 3.13+ and follow modern best practices:

• Use Path lib for files instead of open
• Use var!s instead of str(var)
• Prefer walrus operator (:=) to reduce repetition in code
• Use modern union syntax X | Y instead of Union[X, Y]
• Use underscore separators in large numbers: Decimal(1_000_000) not Decimal("1000000")

Attribute and Method Naming

We make everything public by default. We're all consenting adults here.

Only use underscore prefix (_internal) when accessing something would genuinely break functionality - like thread locks or internal state that must be accessed through methods. This is extremely rare.

Async vs Sync

Default to synchronous code. We use Celery for background jobs with multiple workers, so we don't need async to free up CPU. Synchronous code is simpler, easier to debug, and easier to maintain.

When given a choice between sync and async, we choose sync.

def fetch_data(url: str) -> dict:
    response = requests.get(url)
    return response.json()

If a library only provides async API, we can wrap it with asyncio.run():

import asyncio

def sync_wrapper(param: str) -> dict:
    """Synchronous wrapper for async-only library"""
    return asyncio.run(async_library_call(param))

Async is appropriate for WebSocket connections, async-only libraries that can't be easily wrapped, or specific performance-critical paths where async provides clear, measured benefits. Ask for confirmation before introducing async patterns.

Exception Handling - READ THIS COMPLETELY

DO NOT SWALLOW ERRORS. This is the hill we die on.

Default: let exceptions bubble up. We use Sentry/Honeybadger for centralized error tracking, so exceptions that bubble up get caught and reported automatically - we get alerted and can fix them. Write functions with NO try/except: