diff --git a/python/CODING_STANDARD.md b/python/CODING_STANDARD.md index e052b60669..df143ce62a 100644 --- a/python/CODING_STANDARD.md +++ b/python/CODING_STANDARD.md @@ -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 +# from ._types import ``` +**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 diff --git a/python/packages/core/agent_framework/__init__.py b/python/packages/core/agent_framework/__init__.py index 48095326de..f433df94b8 100644 --- a/python/packages/core/agent_framework/__init__.py +++ b/python/packages/core/agent_framework/__init__.py @@ -9,13 +9,284 @@ _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", +] diff --git a/python/packages/core/agent_framework/openai/__init__.py b/python/packages/core/agent_framework/openai/__init__.py index 008e2cb54c..c5e196b022 100644 --- a/python/packages/core/agent_framework/openai/__init__.py +++ b/python/packages/core/agent_framework/openai/__init__.py @@ -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", +] diff --git a/python/packages/lab/namespace/agent_framework/lab/gaia/__init__.py b/python/packages/lab/namespace/agent_framework/lab/gaia/__init__.py index 391a57b4a3..a6e7da4cdc 100644 --- a/python/packages/lab/namespace/agent_framework/lab/gaia/__init__.py +++ b/python/packages/lab/namespace/agent_framework/lab/gaia/__init__.py @@ -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", +] diff --git a/python/packages/lab/namespace/agent_framework/lab/lightning/__init__.py b/python/packages/lab/namespace/agent_framework/lab/lightning/__init__.py index 3a857f38da..21ad032b70 100644 --- a/python/packages/lab/namespace/agent_framework/lab/lightning/__init__.py +++ b/python/packages/lab/namespace/agent_framework/lab/lightning/__init__.py @@ -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"] diff --git a/python/packages/lab/namespace/agent_framework/lab/tau2/__init__.py b/python/packages/lab/namespace/agent_framework/lab/tau2/__init__.py index 56fda49217..7229589746 100644 --- a/python/packages/lab/namespace/agent_framework/lab/tau2/__init__.py +++ b/python/packages/lab/namespace/agent_framework/lab/tau2/__init__.py @@ -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", +]