python-development

# Python Development Standards ## File Header Every `.py` file must start with: ```python # 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: ```python 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: ```python 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. """ ``` - Always document Agent Framework specific exceptions - Explicitly use `Keyword Args` when applicable - Only document standard Python exceptions when the condition is non-obvious ## Import Structure ```python # Core from agent_framework import Agent, Message, tool # Components from agent_framework.observability import enable_sensitive_telemetry # Connectors (lazy-loaded) from agent_framework.openai import OpenAIChatClient from agent_framework.foundry import FoundryChatClient ``` ## Public API and Exports In `__init__.py` files that define package-level public APIs, use direct re-export imports plus an explicit `__all__`. Avoid identity aliases like `from ._agents import Agent as Agent`, and avoid `from module import *`. Do not define `__all__` in internal non-`__init__.py` modules. Exception: modules intentionally exposed as a public import surface (for example, `agent_framework.observability`) should define `__all__`. ```python __all__ = ["Agent", "Message", "ChatResponse"] from ._agents import Agent from ._types import Message, ChatResponse ``` Special case: the root `agent_framework/__init__.py` uses lazy runtime exports. For root public API changes: - Add the symbol to `_LAZY_MODULE_EXPORTS` and keep `_LAZY_EXPORTS` derived from it. - Keep the explicit runtime `__all__` synchronized; it is still required for `from agent_framework import *`. - Add the same public symbol to `agent_framework/__init__.pyi` so pyright, mypy, and editors see the typed surface. - Put runtime deprecation behavior in the owning module via that module's `__getattr__`; avoid root-level special-case branches for individual deprecated exports. - Identity aliases are appropriate in `.pyi` stubs because they mark re-exported names for type checkers; avoid them in runtime `.py` modules unless there is a specific compatibility reason. ## Performance Guidelines - Cache expensive computations (e.g., JSON schema generation) - Prefer `match/case` on `.type` attribute over `isinstance()` in hot paths - Avoid redundant serialization — compute once, reuse ## Style - Line length: 120 characters - Format only files you changed, not the entire codebase - Prefer attributes over inheritance when parameters are mostly the same - Async by default — assume everything is asynchronous ## Naming Conventions for Connectors - `_prepare_<object>_for_<purpose>` for methods that prepare data for external services - `_parse_<object>_from_<source>` for methods that process data from external services