Vibe Python Style

Conventions for writing Python in the Vibe codebase. Apply whenever writing, reviewing, or refactoring Python code.

Style

• Prefer match / case over long if / elif chains.
• Use the walrus operator := only when it shortens code and improves clarity.
• Be a never-nester: early returns and guard clauses over nested blocks.
• Modern type hints only: built-in generics (list, dict) and | unions. Never import Optional, Union, Dict, List from typing.
• Use pathlib.Path (and anyio.Path in async paths) instead of os.path.
• Use f-strings, comprehensions, and context managers; follow PEP 8.
• Enums: StrEnum / IntEnum with auto() and UPPERCASE members. For type-mixing, the mix-in type comes before Enum in the bases. Add methods or @property rather than parallel lookup tables.
• Write declarative, minimalist code: express intent, drop boilerplate.
• Never call a private method from outside of its class in production code. Accessing private methods in tests is acceptable.
• Avoid comments and docstrings, except for when there's a hard to spot corner case

Typing & imports

• Pyright is strict and gates CI; fix types at the source.
• No relative imports, ban-relative-imports = "all". Always from vibe.core.x import ….
• No inline # type: ignore or # noqa. Fix with refined signatures (TypeVar, Protocol), isinstance guards, typing.cast when control flow guarantees the type, or a small typed wrapper at the boundary.

TYPE_CHECKING and lazy imports

Moving imports under if TYPE_CHECKING: or into function bodies cuts startup time but risks runtime NameError. Before merging any import-deferral change, run: