agent/agent-framework
1
0
Fork 0
mirror of https://github.com/microsoft/agent-framework.git synced 2026-06-16 21:04:09 +08:00
Code Issues Packages Projects Releases Wiki Activity

Python: Replace wildcard imports with explicit imports (#3908)

Browse Source 
* Python: Replace wildcard imports with explicit imports

- Replace all 'from ... import *' with explicit symbol imports
- Add __all__ declarations to namespace packages for re-exports
- Update CODING_STANDARD.md to prohibit wildcard imports
- Maintain exported API and preserve all functionality

fixes #3605

* Refine wildcard guidance example text

* Simplify explicit exports without self-aliases
This commit is contained in:
Eduard van Valkenburg
2026-02-13 15:02:36 +01:00
committed by GitHub
Unverified
parent a39fd69f76
commit 4452997e8d
6 changed files with 378 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
python/CODING_STANDARD.md
+21 -6
View File
@@ -403,22 +403,37 @@ If in doubt, use the link above to read much more considerations of what to do a
### Explicit Exports
> **Note:** This convention is being adopted. See [#3605](https://github.com/microsoft/agent-framework/issues/3605) for progress.
**All wildcard imports (`from ... import *`) are prohibited** in production code, including both `.py` and `.pyi` files. Always use explicit import lists to maintain clarity and avoid namespace pollution.
Define `__all__` in each module to explicitly declare the public API. Avoid using `from module import *` in `__init__.py` files as it can impact performance and makes the public API unclear:
Define `__all__` in each module to explicitly declare the public API, then import specific symbols by name:
```python
# ✅ Preferred - explicit __all__ and imports
# ✅ Preferred - explicit __all__ and named imports
__all__ = ["Agent", "Message", "ChatResponse"]
from ._agents import Agent
from ._types import Message, ChatResponse
# ❌ Avoid - star imports
from ._agents import *
from ._types import *
# ✅ For many exports, use parenthesized multi-line imports
from ._types import (
AgentResponse,
ChatResponse,
Message,
ResponseStream,
)
# ❌ Prohibited pattern: wildcard/star imports (do not use)
# from ._agents import <all public symbols>
# from ._types import <all public symbols>
```
**Rationale:**
- **Clarity**: Explicit imports make it clear exactly what is being exported and used
- **IDE Support**: Enables better autocomplete, go-to-definition, and refactoring
- **Type Checking**: Improves static analysis and type checker accuracy
- **Maintenance**: Makes it easier to track symbol usage and detect breaking changes
- **Performance**: Avoids unnecessary symbol resolution during module import
## Performance considerations
### Cache Expensive Computations
python/packages/core/agent_framework/__init__.py
+281 -10
View File
@@ -9,13 +9,284 @@ except importlib.metadata.PackageNotFoundError:
_version = "0.0.0" # Fallback for development mode
__version__: Final[str] = _version
from ._agents import * # noqa: F403
from ._clients import * # noqa: F403
from ._logging import * # noqa: F403
from ._mcp import * # noqa: F403
from ._middleware import * # noqa: F403
from ._sessions import * # noqa: F403
from ._telemetry import * # noqa: F403
from ._tools import * # noqa: F403
from ._types import * # noqa: F403
from ._workflows import * # noqa: F403
from ._agents import Agent, BaseAgent, RawAgent, SupportsAgentRun
from ._clients import (
BaseChatClient,
SupportsChatGetResponse,
SupportsCodeInterpreterTool,
SupportsFileSearchTool,
SupportsImageGenerationTool,
SupportsMCPTool,
SupportsWebSearchTool,
)
from ._logging import get_logger, setup_logging
from ._mcp import MCPStdioTool, MCPStreamableHTTPTool, MCPWebsocketTool
from ._middleware import (
AgentContext,
AgentMiddleware,
AgentMiddlewareLayer,
AgentMiddlewareTypes,
ChatAndFunctionMiddlewareTypes,
ChatContext,
ChatMiddleware,
ChatMiddlewareLayer,
ChatMiddlewareTypes,
FunctionInvocationContext,
FunctionMiddleware,
FunctionMiddlewareTypes,
MiddlewareException,
MiddlewareTermination,
MiddlewareType,
MiddlewareTypes,
agent_middleware,
chat_middleware,
function_middleware,
)
from ._sessions import (
AgentSession,
BaseContextProvider,
BaseHistoryProvider,
InMemoryHistoryProvider,
SessionContext,
register_state_type,
)
from ._telemetry import (
AGENT_FRAMEWORK_USER_AGENT,
APP_INFO,
USER_AGENT_KEY,
USER_AGENT_TELEMETRY_DISABLED_ENV_VAR,
prepend_agent_framework_to_user_agent,
)
from ._tools import (
FunctionInvocationConfiguration,
FunctionInvocationLayer,
FunctionTool,
normalize_function_invocation_configuration,
tool,
)
from ._types import (
AgentResponse,
AgentResponseUpdate,
Annotation,
ChatOptions,
ChatResponse,
ChatResponseUpdate,
Content,
ContinuationToken,
FinalT,
FinishReason,
FinishReasonLiteral,
Message,
OuterFinalT,
OuterUpdateT,
ResponseStream,
Role,
RoleLiteral,
TextSpanRegion,
ToolMode,
UpdateT,
UsageDetails,
add_usage_details,
detect_media_type_from_base64,
map_chat_to_agent_update,
merge_chat_options,
normalize_messages,
normalize_tools,
prepend_instructions_to_messages,
validate_chat_options,
validate_tool_mode,
validate_tools,
)
from ._workflows import (
DEFAULT_MAX_ITERATIONS,
AgentExecutor,
AgentExecutorRequest,
AgentExecutorResponse,
Case,
CheckpointStorage,
Default,
Edge,
EdgeCondition,
EdgeDuplicationError,
Executor,
FanInEdgeGroup,
FanOutEdgeGroup,
FileCheckpointStorage,
FunctionExecutor,
GraphConnectivityError,
InMemoryCheckpointStorage,
InProcRunnerContext,
Runner,
RunnerContext,
SingleEdgeGroup,
SubWorkflowRequestMessage,
SubWorkflowResponseMessage,
SwitchCaseEdgeGroup,
SwitchCaseEdgeGroupCase,
SwitchCaseEdgeGroupDefault,
TypeCompatibilityError,
ValidationTypeEnum,
Workflow,
WorkflowAgent,
WorkflowBuilder,
WorkflowCheckpoint,
WorkflowCheckpointException,
WorkflowContext,
WorkflowConvergenceException,
WorkflowErrorDetails,
WorkflowEvent,
WorkflowEventSource,
WorkflowEventType,
WorkflowException,
WorkflowExecutor,
WorkflowMessage,
WorkflowRunnerException,
WorkflowRunResult,
WorkflowRunState,
WorkflowValidationError,
WorkflowViz,
create_edge_runner,
executor,
handler,
resolve_agent_id,
response_handler,
validate_workflow_graph,
)
__all__ = [
"AGENT_FRAMEWORK_USER_AGENT",
"APP_INFO",
"DEFAULT_MAX_ITERATIONS",
"USER_AGENT_KEY",
"USER_AGENT_TELEMETRY_DISABLED_ENV_VAR",
"Agent",
"AgentContext",
"AgentExecutor",
"AgentExecutorRequest",
"AgentExecutorResponse",
"AgentMiddleware",
"AgentMiddlewareLayer",
"AgentMiddlewareTypes",
"AgentResponse",
"AgentResponseUpdate",
"AgentSession",
"Annotation",
"BaseAgent",
"BaseChatClient",
"BaseContextProvider",
"BaseHistoryProvider",
"Case",
"ChatAndFunctionMiddlewareTypes",
"ChatContext",
"ChatMiddleware",
"ChatMiddlewareLayer",
"ChatMiddlewareTypes",
"ChatOptions",
"ChatResponse",
"ChatResponseUpdate",
"CheckpointStorage",
"Content",
"ContinuationToken",
"Default",
"Edge",
"EdgeCondition",
"EdgeDuplicationError",
"Executor",
"FanInEdgeGroup",
"FanOutEdgeGroup",
"FileCheckpointStorage",
"FinalT",
"FinishReason",
"FinishReasonLiteral",
"FunctionExecutor",
"FunctionInvocationConfiguration",
"FunctionInvocationContext",
"FunctionInvocationLayer",
"FunctionMiddleware",
"FunctionMiddlewareTypes",
"FunctionTool",
"GraphConnectivityError",
"InMemoryCheckpointStorage",
"InMemoryHistoryProvider",
"InProcRunnerContext",
"MCPStdioTool",
"MCPStreamableHTTPTool",
"MCPWebsocketTool",
"Message",
"MiddlewareException",
"MiddlewareTermination",
"MiddlewareType",
"MiddlewareTypes",
"OuterFinalT",
"OuterUpdateT",
"RawAgent",
"ResponseStream",
"Role",
"RoleLiteral",
"Runner",
"RunnerContext",
"SessionContext",
"SingleEdgeGroup",
"SubWorkflowRequestMessage",
"SubWorkflowResponseMessage",
"SupportsAgentRun",
"SupportsChatGetResponse",
"SupportsCodeInterpreterTool",
"SupportsFileSearchTool",
"SupportsImageGenerationTool",
"SupportsMCPTool",
"SupportsWebSearchTool",
"SwitchCaseEdgeGroup",
"SwitchCaseEdgeGroupCase",
"SwitchCaseEdgeGroupDefault",
"TextSpanRegion",
"ToolMode",
"TypeCompatibilityError",
"UpdateT",
"UsageDetails",
"ValidationTypeEnum",
"Workflow",
"WorkflowAgent",
"WorkflowBuilder",
"WorkflowCheckpoint",
"WorkflowCheckpointException",
"WorkflowContext",
"WorkflowConvergenceException",
"WorkflowErrorDetails",
"WorkflowEvent",
"WorkflowEventSource",
"WorkflowEventType",
"WorkflowException",
"WorkflowExecutor",
"WorkflowMessage",
"WorkflowRunResult",
"WorkflowRunState",
"WorkflowRunnerException",
"WorkflowValidationError",
"WorkflowViz",
"add_usage_details",
"agent_middleware",
"chat_middleware",
"create_edge_runner",
"detect_media_type_from_base64",
"executor",
"function_middleware",
"get_logger",
"handler",
"map_chat_to_agent_update",
"merge_chat_options",
"normalize_function_invocation_configuration",
"normalize_messages",
"normalize_tools",
"prepend_agent_framework_to_user_agent",
"prepend_instructions_to_messages",
"register_state_type",
"resolve_agent_id",
"response_handler",
"setup_logging",
"tool",
"validate_chat_options",
"validate_tool_mode",
"validate_tools",
"validate_workflow_graph",
]
python/packages/core/agent_framework/openai/__init__.py
+31 -6
View File
@@ -1,8 +1,33 @@
# Copyright (c) Microsoft. All rights reserved.
from ._assistant_provider import * # noqa: F403
from ._assistants_client import * # noqa: F403
from ._chat_client import * # noqa: F403
from ._exceptions import * # noqa: F403
from ._responses_client import * # noqa: F403
from ._shared import * # noqa: F403
from ._assistant_provider import OpenAIAssistantProvider
from ._assistants_client import (
AssistantToolResources,
OpenAIAssistantsClient,
OpenAIAssistantsOptions,
)
from ._chat_client import OpenAIChatClient, OpenAIChatOptions
from ._exceptions import ContentFilterResultSeverity, OpenAIContentFilterException
from ._responses_client import (
OpenAIContinuationToken,
OpenAIResponsesClient,
OpenAIResponsesOptions,
RawOpenAIResponsesClient,
)
from ._shared import OpenAISettings
__all__ = [
"AssistantToolResources",
"ContentFilterResultSeverity",
"OpenAIAssistantProvider",
"OpenAIAssistantsClient",
"OpenAIAssistantsOptions",
"OpenAIChatClient",
"OpenAIChatOptions",
"OpenAIContentFilterException",
"OpenAIContinuationToken",
"OpenAIResponsesClient",
"OpenAIResponsesOptions",
"OpenAISettings",
"RawOpenAIResponsesClient",
]
python/packages/lab/namespace/agent_framework/lab/gaia/__init__.py
+25 -1
View File
@@ -1,4 +1,28 @@
# Copyright (c) Microsoft. All rights reserved.
# Import and re-export from the actual implementation
from agent_framework_lab_gaia import * # noqa: F403
from agent_framework_lab_gaia import (
GAIA,
Evaluation,
Evaluator,
GAIATelemetryConfig,
Prediction,
Task,
TaskResult,
TaskRunner,
gaia_scorer,
viewer_main,
)
__all__ = [
"GAIA",
"Evaluation",
"Evaluator",
"GAIATelemetryConfig",
"Prediction",
"Task",
"TaskResult",
"TaskRunner",
"gaia_scorer",
"viewer_main",
]
python/packages/lab/namespace/agent_framework/lab/lightning/__init__.py
+3 -1
View File
@@ -1,4 +1,6 @@
# Copyright (c) Microsoft. All rights reserved.
# Import and re-export from the actual implementation
from agent_framework_lab_lightning import * # noqa: F403
from agent_framework_lab_lightning import AgentFrameworkTracer
__all__ = ["AgentFrameworkTracer"]
python/packages/lab/namespace/agent_framework/lab/tau2/__init__.py
+17 -1
View File
@@ -1,4 +1,20 @@
# Copyright (c) Microsoft. All rights reserved.
# Import and re-export from the actual implementation
from agent_framework_lab_tau2 import * # noqa: F403
from agent_framework_lab_tau2 import (
ASSISTANT_AGENT_ID,
ORCHESTRATOR_ID,
USER_SIMULATOR_ID,
TaskRunner,
patch_env_set_state,
unpatch_env_set_state,
)
__all__ = [
"ASSISTANT_AGENT_ID",
"ORCHESTRATOR_ID",
"USER_SIMULATOR_ID",
"TaskRunner",
"patch_env_set_state",
"unpatch_env_set_state",
]