mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
Python: Fix Python pyright package scoping and typing remediation (#4426)
* Fix Python pyright package scoping and typing remediation Implements issue #4407 by removing the root pyright include, adding package-level pyright includes, and resolving pyright/mypy typing issues across Python packages. Also cleans unnecessary casts and applies line-level, rule-specific ignores where external libraries are too dynamic. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Reduce pyright cost in handoff cloning Simplify cloned_options construction in HandoffAgentExecutor to avoid expensive TypedDict narrowing/inference in _handoff.py, which was causing pyright to spend a long time in orchestrations. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix types * Fix lint and type-check regressions Resolve current Python package check failures across lint, pyright, and mypy after recent code changes, including purview/declarative pyright issues and multiple ruff simplification findings. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fixed hooks * Stabilize package tests and test tasks Resolve cross-package non-integration test failures, simplify streaming type flow, harden locale/culture handling, and standardize package test poe tasks to exclude integration tests where applicable. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * lots of small fixes * Fix current Python test regressions Address current failing unit tests in azure-ai, bedrock, and azure-cosmos while keeping Bedrock parsing logic inline (no new static helper methods). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * small fixes * small fixes * removed pydantic from json * final updates * fix core * fix tests * fix obser --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
committed by
GitHub
Unverified
parent
4a043c6c66
commit
55ddd841b7
@@ -27,6 +27,12 @@ Public modules must include a module-level docstring, including `__init__.py` fi
|
||||
|
||||
## Type Annotations
|
||||
|
||||
We use typing as a helper, it is not a goal in and of itself, so be pragmatic about where and when to strictly type, versus when to use a targetted cast or ignore.
|
||||
In general, the public interfaces of our classes, are important to get right, internally it is okay to have loosely typed code, as long as tests cover the code itself.
|
||||
This includes making a conscious choice when to program defensively, you can always do `getattr(item, 'attribute')` but that might end up causing you issues down the road
|
||||
because the type of `item` in this case, should have that attribute and if it doesn't it points to a larger issue, so if the type is expected to have that attribute, you should
|
||||
use `item.attribute` to ensure it fails at that point, rather then somewhere downstream where a value is expected but none was found.
|
||||
|
||||
### Future Annotations
|
||||
|
||||
> **Note:** This convention is being adopted. See [#3578](https://github.com/microsoft/agent-framework/issues/3578) for progress.
|
||||
@@ -79,6 +85,21 @@ def process_config(config: MutableMapping[str, Any]) -> None:
|
||||
...
|
||||
```
|
||||
|
||||
### Typing Ignore and Cast Policy
|
||||
|
||||
Use typing as a helper first and suppressions as a last resort:
|
||||
|
||||
- **Prefer explicit typing before suppression**: Start with clearer type annotations, helper types, overloads,
|
||||
protocols, or refactoring dynamic code into typed helpers. Prioritize performance over completeness of typing, but make a good-faith effort to reduce uncertainty with typing before ignoring. Prefer to use a cast over a typeguard function since that does add overhead.
|
||||
- **Avoid redundant casts**: Do not add `cast(...)` if the type already matches; casts should be reserved for
|
||||
unavoidable narrowing where the runtime contract is known, we will use mypy's check on redundant casts to enforce this.
|
||||
- **Avoid multiple assignments**: Avoid assigning multiple variables just to get typing to pass, that has performance impact while typing should not have that.
|
||||
- **Line-level pyright ignores only**: If suppression is still required, use a line-level rule-specific ignore
|
||||
(`# pyright: ignore[reportGeneralTypeIssues]`), file-level is allowed if there is a compelling reason for it, that should be documented right beneath the ignore.
|
||||
Never change the global suppression flags for mypy and pyright unless the dev team okays it.
|
||||
- **Private usage boundary**: Accessing private members across `agent_framework*` packages can be acceptable for this
|
||||
codebase, but private member usage for non-Agent Framework dependencies should remain flagged.
|
||||
|
||||
## Function Parameter Guidelines
|
||||
|
||||
To make the code easier to use and maintain:
|
||||
|
||||
Reference in New Issue
Block a user