|
1 | 1 | --- |
2 | 2 | name: python-development |
3 | 3 | description: > |
4 | | - Coding standards, conventions, and patterns for developing Python code in the |
5 | | - Agent Framework repository. Use this when writing or modifying Python source |
6 | | - files in the python/ directory. |
| 4 | + Workflow guidance for developing Python code in the Agent Framework |
| 5 | + repository. Use this when writing or modifying Python source files under |
| 6 | + python/. |
7 | 7 | --- |
8 | 8 |
|
9 | | -# Python Development Standards |
10 | | - |
11 | | -## File Header |
12 | | - |
13 | | -Every `.py` file must start with: |
14 | | - |
15 | | -```python |
16 | | -# Copyright (c) Microsoft. All rights reserved. |
17 | | -``` |
18 | | - |
19 | | -## Type Annotations |
20 | | - |
21 | | -- Always specify return types and parameter types |
22 | | -- Use `Type | None` instead of `Optional[Type]` |
23 | | -- Use `from __future__ import annotations` to enable postponed evaluation |
24 | | -- Use suffix `T` for TypeVar names: `ChatResponseT = TypeVar("ChatResponseT", bound=ChatResponse)` |
25 | | -- Use `Mapping` instead of `MutableMapping` for read-only input parameters |
26 | | -- Prefer `# type: ignore[...]` over unnecessary casts, or `isinstance` checks, when these are internally called and executed methods |
27 | | - But make sure the ignore is specific for both mypy and pyright so that we don't miss other mistakes |
28 | | -- Internal private helpers may be used across `agent_framework*` modules when intentional; use a targeted |
29 | | - `# pyright: ignore[reportPrivateUsage]` instead of making the helper public just to satisfy pyright. |
30 | | -- Do not add trivial pass-through or one-line helper functions solely to appease typing. Prefer targeted ignores, |
31 | | - casts, or clearer annotations over adding runtime overhead without a design benefit. |
32 | | - |
33 | | -## Function Parameters |
34 | | - |
35 | | -- Positional parameters: up to 3 fully expected parameters |
36 | | -- Use keyword-only arguments (after `*`) for optional parameters |
37 | | -- Provide string-based overrides to avoid requiring extra imports: |
38 | | - |
39 | | -```python |
40 | | -def create_agent(name: str, tool_mode: Literal['auto', 'required', 'none'] | ChatToolMode) -> Agent: |
41 | | - if isinstance(tool_mode, str): |
42 | | - tool_mode = ChatToolMode(tool_mode) |
43 | | -``` |
44 | | - |
45 | | -- Avoid shadowing built-ins (use `next_handler` instead of `next`) |
46 | | -- Avoid `**kwargs` unless needed for subclass extensibility; prefer named parameters |
47 | | - |
48 | | -## Docstrings |
49 | | - |
50 | | -Use Google-style docstrings for all public APIs: |
51 | | - |
52 | | -```python |
53 | | -def equal(arg1: str, arg2: str) -> bool: |
54 | | - """Compares two strings and returns True if they are the same. |
55 | | -
|
56 | | - Args: |
57 | | - arg1: The first string to compare. |
58 | | - arg2: The second string to compare. |
59 | | -
|
60 | | - Returns: |
61 | | - True if the strings are the same, False otherwise. |
62 | | -
|
63 | | - Raises: |
64 | | - ValueError: If one of the strings is empty. |
65 | | - """ |
66 | | -``` |
67 | | - |
68 | | -- Always document Agent Framework specific exceptions |
69 | | -- Explicitly use `Keyword Args` when applicable |
70 | | -- Only document standard Python exceptions when the condition is non-obvious |
71 | | - |
72 | | -## Import Structure |
73 | | - |
74 | | -```python |
75 | | -# Core |
76 | | -from agent_framework import Agent, Message, tool |
77 | | - |
78 | | -# Components |
79 | | -from agent_framework.observability import enable_sensitive_telemetry |
80 | | - |
81 | | -# Connectors (lazy-loaded) |
82 | | -from agent_framework.openai import OpenAIChatClient |
83 | | -from agent_framework.foundry import FoundryChatClient |
84 | | -``` |
85 | | - |
86 | | -## Public API and Exports |
87 | | - |
88 | | -In `__init__.py` files that define package-level public APIs, use direct re-export imports plus an explicit |
89 | | -`__all__`. Avoid identity aliases like `from ._agents import Agent as Agent`, and avoid |
90 | | -`from module import *`. |
91 | | - |
92 | | -Do not define `__all__` in internal non-`__init__.py` modules. Exception: modules intentionally exposed as a |
93 | | -public import surface (for example, `agent_framework.observability`) should define `__all__`. |
94 | | - |
95 | | -```python |
96 | | -__all__ = ["Agent", "Message", "ChatResponse"] |
97 | | - |
98 | | -from ._agents import Agent |
99 | | -from ._types import Message, ChatResponse |
100 | | -``` |
101 | | - |
102 | | -Special case: the root `agent_framework/__init__.py` uses lazy runtime exports. For root public API changes: |
103 | | -- Add the symbol to `_LAZY_MODULE_EXPORTS` and keep `_LAZY_EXPORTS` derived from it. |
104 | | -- Keep the explicit runtime `__all__` synchronized; it is still required for `from agent_framework import *`. |
105 | | -- Add the same public symbol to `agent_framework/__init__.pyi` so pyright, mypy, and editors see the typed surface. |
106 | | -- Put runtime deprecation behavior in the owning module via that module's `__getattr__`; avoid root-level |
107 | | - special-case branches for individual deprecated exports. |
108 | | -- Identity aliases are appropriate in `.pyi` stubs because they mark re-exported names for type checkers; avoid them |
109 | | - in runtime `.py` modules unless there is a specific compatibility reason. |
110 | | - |
111 | | -## Performance Guidelines |
112 | | - |
113 | | -- Cache expensive computations (e.g., JSON schema generation) |
114 | | -- Prefer `match/case` on `.type` attribute over `isinstance()` in hot paths |
115 | | -- Avoid redundant serialization — compute once, reuse |
116 | | - |
117 | | -## Style |
118 | | - |
119 | | -- Line length: 120 characters |
120 | | -- Format only files you changed, not the entire codebase |
121 | | -- Prefer attributes over inheritance when parameters are mostly the same |
122 | | -- Async by default — assume everything is asynchronous |
123 | | - |
124 | | -## Naming Conventions for Connectors |
125 | | - |
126 | | -- `_prepare_<object>_for_<purpose>` for methods that prepare data for external services |
127 | | -- `_parse_<object>_from_<source>` for methods that process data from external services |
| 9 | +# Python Development Workflow |
| 10 | + |
| 11 | +The canonical engineering rules are in |
| 12 | +[`python/CODING_STANDARD.md`](../../../CODING_STANDARD.md). Read and apply that |
| 13 | +document before changing Python source. Do not create or maintain a competing |
| 14 | +copy of the standards in this skill. |
| 15 | + |
| 16 | +## Before Editing |
| 17 | + |
| 18 | +1. Read `python/AGENTS.md` and the nearest package `AGENTS.md`. |
| 19 | +2. Identify whether the change affects package source, tests, samples, public |
| 20 | + exports, package governance, or more than one of those surfaces. |
| 21 | +3. Read the task-specific skill when applicable: |
| 22 | + - `python-testing` for test design, integration markers, and test commands. |
| 23 | + - `python-code-quality` for formatting, linting, and type checking. |
| 24 | + - `python-package-management` for package creation, dependencies, public |
| 25 | + lazy exports, and package lifecycle. |
| 26 | + - `python-feature-lifecycle` for staged API decorators and promotion. |
| 27 | + |
| 28 | +## Implementing Changes |
| 29 | + |
| 30 | +- Follow established patterns in the owning package unless they conflict with |
| 31 | + `python/CODING_STANDARD.md`. |
| 32 | +- Keep the common public path import-light and review public API changes for |
| 33 | + compatibility and ergonomics. |
| 34 | +- Update source, typing surfaces, tests, samples, and documentation together |
| 35 | + when they represent the same contract. |
| 36 | +- For root `agent_framework` export changes, follow the synchronized runtime, |
| 37 | + `__all__`, and `.pyi` workflow in `python-package-management`. |
| 38 | +- Do not broaden a change into unrelated cleanup solely because nearby code |
| 39 | + predates the current standard. |
| 40 | + |
| 41 | +## Validation |
| 42 | + |
| 43 | +Run the smallest relevant commands from `python/`. Use |
| 44 | +`python-code-quality` and `python-testing` to select package-scoped syntax, |
| 45 | +typing, and test commands before escalating to broader checks. |
| 46 | + |
| 47 | +When a convention, command, or workflow changes, update the canonical document |
| 48 | +or owning task-specific skill rather than duplicating the new guidance here. |
0 commit comments