python-guidelines

Add type hints wherever you can. Think more like static typing, avoid changing the type of the same variable. Define complex (nested) types separately if they are used in more than one place in the code. Omit type hints when the type is obvious from the context (e.g., x = 1).

Write clean, human-readable code. Avoid spaghetti code; keep it structured. Refactor the code as a separate step before making further changes whenever it would become too nested. Too much nesting means more than 2 levels inside functions and methods.

Avoid adding too many parameters to functions and methods. In such cases introduce a data model class to store that information, especially if they are used together more than once. The same applies to return values.

Prefer using data model classes to dictionaries, Pydantic is good, but can also use a dataclass if you have to. For converting between naming schemes, always use explicit from_something and to_something methods instead of hardcoding the external names of fields everywhere in the code. It typically happens while loading/saving data from/to JSON with a different naming convention than the fields of the corresponding Pydantic model class.

Do not use catch-all exception handling (except Exception), except to cover retryable processing, like request handlers or batch data processing. In all other cases use explicit exception handling wherever required. Disable catch-all error handling in development, especially if a debugger is connected.