python-development

Python Development Standards

File Header

Every .py file must start with:

# Copyright (c) Microsoft. All rights reserved.

Type Annotations

• Always specify return types and parameter types
• Use Type | None instead of Optional[Type]
• Use from __future__ import annotations to enable postponed evaluation
• Use suffix T for TypeVar names: ChatResponseT = TypeVar("ChatResponseT", bound=ChatResponse)
• Use Mapping instead of MutableMapping for read-only input parameters
• Prefer # type: ignore[...] over unnecessary casts, or isinstance checks, when these are internally called and executed methods But make sure the ignore is specific for both mypy and pyright so that we don't miss other mistakes
• Internal private helpers may be used across agent_framework* modules when intentional; use a targeted # pyright: ignore[reportPrivateUsage] instead of making the helper public just to satisfy pyright.
• Do not add trivial pass-through or one-line helper functions solely to appease typing. Prefer targeted ignores, casts, or clearer annotations over adding runtime overhead without a design benefit.

Function Parameters

• Positional parameters: up to 3 fully expected parameters
• Use keyword-only arguments (after *) for optional parameters
• Provide string-based overrides to avoid requiring extra imports:

def create_agent(name: str, tool_mode: Literal['auto', 'required', 'none'] | ChatToolMode) -> Agent:
    if isinstance(tool_mode, str):
        tool_mode = ChatToolMode(tool_mode)

• Avoid shadowing built-ins (use next_handler instead of next)
• Avoid **kwargs unless needed for subclass extensibility; prefer named parameters

Docstrings

Use Google-style docstrings for all public APIs:

def equal(arg1: str, arg2: str) -> bool:
    """Compares two strings and returns True if they are the same.

    Args:
        arg1: The first string to compare.
        arg2: The second string to compare.

    Returns:
        True if the strings are the same, False otherwise.

    Raises:
        ValueError: If one of the strings is empty.
    """