Thank you for your email.
" - ) - await context.send_activity(response) - ``` + >>> @notifications.on_email() + ... async def handle_email(context, state, notification): + ... email = notification.email + ... if email: + ... print(f"Received email: {email.id}") + ... response = EmailResponse.create_email_response_activity( + ... "Thank you for your email.
" + ... ) + ... await context.send_activity(response) """ return self.on_agent_notification( ChannelId(channel="agents", sub_channel=AgentSubChannel.EMAIL), **kwargs @@ -266,13 +252,11 @@ def on_word( A decorator function that registers the handler with the application. Example: - ```python - @notifications.on_word() - async def handle_word_comment(context, state, notification): - comment = notification.wpx_comment - if comment: - print(f"Received Word comment: {comment.comment_id}") - ``` + >>> @notifications.on_word() + ... async def handle_word_comment(context, state, notification): + ... comment = notification.wpx_comment + ... if comment: + ... print(f"Received Word comment: {comment.comment_id}") """ return self.on_agent_notification( ChannelId(channel="agents", sub_channel=AgentSubChannel.WORD), **kwargs @@ -293,13 +277,11 @@ def on_excel( A decorator function that registers the handler with the application. Example: - ```python - @notifications.on_excel() - async def handle_excel_comment(context, state, notification): - comment = notification.wpx_comment - if comment: - print(f"Received Excel comment: {comment.comment_id}") - ``` + >>> @notifications.on_excel() + ... async def handle_excel_comment(context, state, notification): + ... comment = notification.wpx_comment + ... if comment: + ... print(f"Received Excel comment: {comment.comment_id}") """ return self.on_agent_notification( ChannelId(channel="agents", sub_channel=AgentSubChannel.EXCEL), **kwargs @@ -320,13 +302,11 @@ def on_powerpoint( A decorator function that registers the handler with the application. Example: - ```python - @notifications.on_powerpoint() - async def handle_powerpoint_comment(context, state, notification): - comment = notification.wpx_comment - if comment: - print(f"Received PowerPoint comment: {comment.comment_id}") - ``` + >>> @notifications.on_powerpoint() + ... async def handle_powerpoint_comment(context, state, notification): + ... comment = notification.wpx_comment + ... if comment: + ... print(f"Received PowerPoint comment: {comment.comment_id}") """ return self.on_agent_notification( ChannelId(channel="agents", sub_channel=AgentSubChannel.POWERPOINT), **kwargs @@ -347,11 +327,9 @@ def on_lifecycle( A decorator function that registers the handler with the application. Example: - ```python - @notifications.on_lifecycle() - async def handle_any_lifecycle_event(context, state, notification): - print(f"Lifecycle event type: {notification.notification_type}") - ``` + >>> @notifications.on_lifecycle() + ... async def handle_any_lifecycle_event(context, state, notification): + ... print(f"Lifecycle event type: {notification.notification_type}") """ return self.on_lifecycle_notification("*", **kwargs) @@ -370,11 +348,9 @@ def on_user_created( A decorator function that registers the handler with the application. Example: - ```python - @notifications.on_user_created() - async def handle_user_created(context, state, notification): - print("New agentic user identity created") - ``` + >>> @notifications.on_user_created() + ... async def handle_user_created(context, state, notification): + ... print("New agentic user identity created") """ return self.on_lifecycle_notification(AgentLifecycleEvent.USERCREATED, **kwargs) @@ -393,11 +369,9 @@ def on_user_workload_onboarding( A decorator function that registers the handler with the application. Example: - ```python - @notifications.on_user_workload_onboarding() - async def handle_onboarding_update(context, state, notification): - print("User workload onboarding status updated") - ``` + >>> @notifications.on_user_workload_onboarding() + ... async def handle_onboarding_update(context, state, notification): + ... print("User workload onboarding status updated") """ return self.on_lifecycle_notification( AgentLifecycleEvent.USERWORKLOADONBOARDINGUPDATED, **kwargs @@ -418,11 +392,9 @@ def on_user_deleted( A decorator function that registers the handler with the application. Example: - ```python - @notifications.on_user_deleted() - async def handle_user_deleted(context, state, notification): - print("Agentic user identity deleted") - ``` + >>> @notifications.on_user_deleted() + ... async def handle_user_deleted(context, state, notification): + ... print("Agentic user identity deleted") """ return self.on_lifecycle_notification(AgentLifecycleEvent.USERDELETED, **kwargs) diff --git a/libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/models/agent_notification_activity.py b/libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/models/agent_notification_activity.py index 010b53a4..8011148e 100644 --- a/libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/models/agent_notification_activity.py +++ b/libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/models/agent_notification_activity.py @@ -28,13 +28,15 @@ class AgentNotificationActivity: activity: The underlying Activity object. Example: - ```python - async def email_handler(context: TurnContext, state: TurnState, notification: AgentNotificationActivity): - email = notification.email - if email: - print(f"Received email: {email.id}") - print(f"Body: {email.html_body}") - ``` + >>> async def email_handler( + ... context: TurnContext, + ... state: TurnState, + ... notification: AgentNotificationActivity, + ... ) -> None: + ... email = notification.email + ... if email: + ... print(f"Received email: {email.id}") + ... print(f"Body: {email.html_body}") """ def __init__(self, activity: Activity): @@ -158,17 +160,13 @@ def as_model(self, model: Type[TModel]) -> Optional[TModel]: An instance of the specified model type if validation succeeds, otherwise None. Example: - ```python - from pydantic import BaseModel - - class CustomNotification(BaseModel): - custom_field: str - - notification = AgentNotificationActivity(activity) - custom = notification.as_model(CustomNotification) - if custom: - print(custom.custom_field) - ``` + >>> from pydantic import BaseModel + >>> class CustomNotification(BaseModel): + ... custom_field: str + >>> notification = AgentNotificationActivity(activity) + >>> custom = notification.as_model(CustomNotification) + >>> if custom: + ... print(custom.custom_field) """ try: return model.model_validate(self.value or {}) diff --git a/libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/models/email_response.py b/libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/models/email_response.py index c9efbe70..8fadf000 100644 --- a/libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/models/email_response.py +++ b/libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/models/email_response.py @@ -36,12 +36,10 @@ def create_email_response_activity(email_response_html_body: str) -> Activity: entity attached to its entities list. Example: - ```python - activity = EmailResponse.create_email_response_activity( - "Thank you for your email. I'll get back to you soon.
" - ) - await context.send_activity(activity) - ``` + >>> activity = EmailResponse.create_email_response_activity( + ... "Thank you for your email. I'll get back to you soon.
" + ... ) + >>> await context.send_activity(activity) """ working_activity = Activity(type="message") email_response = EmailResponse(html_body=email_response_html_body) diff --git a/libraries/microsoft-agents-a365-observability-extensions-openai/microsoft_agents_a365/observability/extensions/openai/trace_instrumentor.py b/libraries/microsoft-agents-a365-observability-extensions-openai/microsoft_agents_a365/observability/extensions/openai/trace_instrumentor.py index dae8786e..e7454876 100644 --- a/libraries/microsoft-agents-a365-observability-extensions-openai/microsoft_agents_a365/observability/extensions/openai/trace_instrumentor.py +++ b/libraries/microsoft-agents-a365-observability-extensions-openai/microsoft_agents_a365/observability/extensions/openai/trace_instrumentor.py @@ -22,11 +22,9 @@ class OpenAIAgentsTraceInstrumentor(BaseInstrumentor): - """ - Custom Trace Processor for OpenAI Agents SDK using Microsoft Agent 365. - Forwards OpenAI Agents SDK traces and spans to Microsoft Agent 365's tracing scopes. + """Custom Trace Processor for OpenAI Agents SDK using Microsoft Agent 365. - ``` + Forwards OpenAI Agents SDK traces and spans to Microsoft Agent 365's tracing scopes. """ def __init__(self): From b41452209c2ca492d60d5928f3b3b7618e2030f9 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 25 Feb 2026 18:25:13 +0000 Subject: [PATCH 3/3] Replace doctest >>> format with RST code-block directives in docstring examples Co-authored-by: JimDaly <6353736+JimDaly@users.noreply.github.com> --- .../notifications/agent_notification.py | 152 +++++++++++------- .../models/agent_notification_activity.py | 38 +++-- .../notifications/models/email_response.py | 10 +- 3 files changed, 118 insertions(+), 82 deletions(-) diff --git a/libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/agent_notification.py b/libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/agent_notification.py index 54813333..034f3fb5 100644 --- a/libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/agent_notification.py +++ b/libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/agent_notification.py @@ -29,14 +29,17 @@ #: notification: The typed notification activity with parsed entities. #: #: Example: -#: >>> async def handle_email( -#: ... context: TurnContext, -#: ... state: TurnState, -#: ... notification: AgentNotificationActivity, -#: ... ) -> None: -#: ... email = notification.email -#: ... if email: -#: ... print(f"Processing email: {email.id}") +#: +#: .. code-block:: python +#: +#: async def handle_email( +#: context: TurnContext, +#: state: TurnState, +#: notification: AgentNotificationActivity, +#: ) -> None: +#: email = notification.email +#: if email: +#: print(f"Processing email: {email.id}") AgentHandler = Callable[[TContext, TState, AgentNotificationActivity], Awaitable[None]] @@ -55,15 +58,19 @@ class AgentNotification: defaults to all values in the AgentLifecycleEvent enum. Example: - >>> from microsoft_agents.hosting import Application - >>> from microsoft_agents_a365.notifications import AgentNotification - >>> app = Application() - >>> notifications = AgentNotification(app) - >>> @notifications.on_email() - ... async def handle_email(context, state, notification): - ... email = notification.email - ... if email: - ... await context.send_activity(f"Received email: {email.id}") + .. code-block:: python + + from microsoft_agents.hosting import Application + from microsoft_agents_a365.notifications import AgentNotification + + app = Application() + notifications = AgentNotification(app) + + @notifications.on_email() + async def handle_email(context, state, notification): + email = notification.email + if email: + await context.send_activity(f"Received email: {email.id}") """ def __init__( @@ -120,12 +127,15 @@ def on_agent_notification( A decorator function that registers the handler with the application. Example: - >>> from microsoft_agents.activity import ChannelId - >>> @notifications.on_agent_notification( - ... ChannelId(channel="agents", sub_channel="email") - ... ) - ... async def handle_custom_channel(context, state, notification): - ... print(f"Received notification on {notification.channel}/{notification.sub_channel}") + .. code-block:: python + + from microsoft_agents.activity import ChannelId + + @notifications.on_agent_notification( + ChannelId(channel="agents", sub_channel="email") + ) + async def handle_custom_channel(context, state, notification): + print(f"Received notification on {notification.channel}/{notification.sub_channel}") """ registered_channel = channel_id.channel.lower() registered_subchannel = (channel_id.sub_channel or "*").lower() @@ -175,9 +185,11 @@ def on_agent_lifecycle_notification( A decorator function that registers the handler with the application. Example: - >>> @notifications.on_agent_lifecycle_notification("agenticuseridentitycreated") - ... async def handle_user_created(context, state, notification): - ... print("New user created") + .. code-block:: python + + @notifications.on_agent_lifecycle_notification("agenticuseridentitycreated") + async def handle_user_created(context, state, notification): + print("New user created") """ def route_selector(context: TurnContext) -> bool: @@ -223,15 +235,17 @@ def on_email( A decorator function that registers the handler with the application. Example: - >>> @notifications.on_email() - ... async def handle_email(context, state, notification): - ... email = notification.email - ... if email: - ... print(f"Received email: {email.id}") - ... response = EmailResponse.create_email_response_activity( - ... "Thank you for your email.
" - ... ) - ... await context.send_activity(response) + .. code-block:: python + + @notifications.on_email() + async def handle_email(context, state, notification): + email = notification.email + if email: + print(f"Received email: {email.id}") + response = EmailResponse.create_email_response_activity( + "Thank you for your email.
" + ) + await context.send_activity(response) """ return self.on_agent_notification( ChannelId(channel="agents", sub_channel=AgentSubChannel.EMAIL), **kwargs @@ -252,11 +266,13 @@ def on_word( A decorator function that registers the handler with the application. Example: - >>> @notifications.on_word() - ... async def handle_word_comment(context, state, notification): - ... comment = notification.wpx_comment - ... if comment: - ... print(f"Received Word comment: {comment.comment_id}") + .. code-block:: python + + @notifications.on_word() + async def handle_word_comment(context, state, notification): + comment = notification.wpx_comment + if comment: + print(f"Received Word comment: {comment.comment_id}") """ return self.on_agent_notification( ChannelId(channel="agents", sub_channel=AgentSubChannel.WORD), **kwargs @@ -277,11 +293,13 @@ def on_excel( A decorator function that registers the handler with the application. Example: - >>> @notifications.on_excel() - ... async def handle_excel_comment(context, state, notification): - ... comment = notification.wpx_comment - ... if comment: - ... print(f"Received Excel comment: {comment.comment_id}") + .. code-block:: python + + @notifications.on_excel() + async def handle_excel_comment(context, state, notification): + comment = notification.wpx_comment + if comment: + print(f"Received Excel comment: {comment.comment_id}") """ return self.on_agent_notification( ChannelId(channel="agents", sub_channel=AgentSubChannel.EXCEL), **kwargs @@ -302,11 +320,13 @@ def on_powerpoint( A decorator function that registers the handler with the application. Example: - >>> @notifications.on_powerpoint() - ... async def handle_powerpoint_comment(context, state, notification): - ... comment = notification.wpx_comment - ... if comment: - ... print(f"Received PowerPoint comment: {comment.comment_id}") + .. code-block:: python + + @notifications.on_powerpoint() + async def handle_powerpoint_comment(context, state, notification): + comment = notification.wpx_comment + if comment: + print(f"Received PowerPoint comment: {comment.comment_id}") """ return self.on_agent_notification( ChannelId(channel="agents", sub_channel=AgentSubChannel.POWERPOINT), **kwargs @@ -327,9 +347,11 @@ def on_lifecycle( A decorator function that registers the handler with the application. Example: - >>> @notifications.on_lifecycle() - ... async def handle_any_lifecycle_event(context, state, notification): - ... print(f"Lifecycle event type: {notification.notification_type}") + .. code-block:: python + + @notifications.on_lifecycle() + async def handle_any_lifecycle_event(context, state, notification): + print(f"Lifecycle event type: {notification.notification_type}") """ return self.on_lifecycle_notification("*", **kwargs) @@ -348,9 +370,11 @@ def on_user_created( A decorator function that registers the handler with the application. Example: - >>> @notifications.on_user_created() - ... async def handle_user_created(context, state, notification): - ... print("New agentic user identity created") + .. code-block:: python + + @notifications.on_user_created() + async def handle_user_created(context, state, notification): + print("New agentic user identity created") """ return self.on_lifecycle_notification(AgentLifecycleEvent.USERCREATED, **kwargs) @@ -369,9 +393,11 @@ def on_user_workload_onboarding( A decorator function that registers the handler with the application. Example: - >>> @notifications.on_user_workload_onboarding() - ... async def handle_onboarding_update(context, state, notification): - ... print("User workload onboarding status updated") + .. code-block:: python + + @notifications.on_user_workload_onboarding() + async def handle_onboarding_update(context, state, notification): + print("User workload onboarding status updated") """ return self.on_lifecycle_notification( AgentLifecycleEvent.USERWORKLOADONBOARDINGUPDATED, **kwargs @@ -392,9 +418,11 @@ def on_user_deleted( A decorator function that registers the handler with the application. Example: - >>> @notifications.on_user_deleted() - ... async def handle_user_deleted(context, state, notification): - ... print("Agentic user identity deleted") + .. code-block:: python + + @notifications.on_user_deleted() + async def handle_user_deleted(context, state, notification): + print("Agentic user identity deleted") """ return self.on_lifecycle_notification(AgentLifecycleEvent.USERDELETED, **kwargs) diff --git a/libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/models/agent_notification_activity.py b/libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/models/agent_notification_activity.py index 8011148e..8ff0bdd4 100644 --- a/libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/models/agent_notification_activity.py +++ b/libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/models/agent_notification_activity.py @@ -28,15 +28,17 @@ class AgentNotificationActivity: activity: The underlying Activity object. Example: - >>> async def email_handler( - ... context: TurnContext, - ... state: TurnState, - ... notification: AgentNotificationActivity, - ... ) -> None: - ... email = notification.email - ... if email: - ... print(f"Received email: {email.id}") - ... print(f"Body: {email.html_body}") + .. code-block:: python + + async def email_handler( + context: TurnContext, + state: TurnState, + notification: AgentNotificationActivity, + ) -> None: + email = notification.email + if email: + print(f"Received email: {email.id}") + print(f"Body: {email.html_body}") """ def __init__(self, activity: Activity): @@ -160,13 +162,17 @@ def as_model(self, model: Type[TModel]) -> Optional[TModel]: An instance of the specified model type if validation succeeds, otherwise None. Example: - >>> from pydantic import BaseModel - >>> class CustomNotification(BaseModel): - ... custom_field: str - >>> notification = AgentNotificationActivity(activity) - >>> custom = notification.as_model(CustomNotification) - >>> if custom: - ... print(custom.custom_field) + .. code-block:: python + + from pydantic import BaseModel + + class CustomNotification(BaseModel): + custom_field: str + + notification = AgentNotificationActivity(activity) + custom = notification.as_model(CustomNotification) + if custom: + print(custom.custom_field) """ try: return model.model_validate(self.value or {}) diff --git a/libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/models/email_response.py b/libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/models/email_response.py index 8fadf000..cbb0e362 100644 --- a/libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/models/email_response.py +++ b/libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/models/email_response.py @@ -36,10 +36,12 @@ def create_email_response_activity(email_response_html_body: str) -> Activity: entity attached to its entities list. Example: - >>> activity = EmailResponse.create_email_response_activity( - ... "Thank you for your email. I'll get back to you soon.
" - ... ) - >>> await context.send_activity(activity) + .. code-block:: python + + activity = EmailResponse.create_email_response_activity( + "Thank you for your email. I'll get back to you soon.
" + ) + await context.send_activity(activity) """ working_activity = Activity(type="message") email_response = EmailResponse(html_body=email_response_html_body)