Keeping a Python service easy to operate

Make the environment boring

Pin dependencies, document the supported runtime and make local startup predictable. If every machine has a slightly different Python environment, production issues become harder to reproduce than they need to be.

Be explicit about the service boundary

Small Python applications often grow through convenience: another script, another background task, another direct database call. Clear entry points and ownership keep that convenience from becoming confusion.

• Use one repeatable dependency workflow
• Validate inputs at the edge
• Separate background work from request handling
• Log enough context to explain failures

from typing import Protocol

class UserRepository(Protocol):
    def find(self, user_id: str) -> User | None: ...

def load_user(user_id: str, repository: UserRepository) -> User:
    user = repository.find(user_id)
    if user is None:
        raise UserNotFound(user_id)
    return user