Skip to content

Commit b414522

Browse files
CopilotJimDaly
Copilot
and
JimDaly
committed
Replace doctest >>> format with RST code-block directives in docstring examples
Co-authored-by: JimDaly <6353736+JimDaly@users.noreply.github.com>
1 parent 0e3573a commit b414522

3 files changed

Lines changed: 118 additions & 82 deletions

File tree

‎libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/agent_notification.py‎

Lines changed: 90 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -29,14 +29,17 @@
2929
#: notification: The typed notification activity with parsed entities.
3030
#:
3131
#: Example:
32-
#: >>> async def handle_email(
33-
#: ... context: TurnContext,
34-
#: ... state: TurnState,
35-
#: ... notification: AgentNotificationActivity,
36-
#: ... ) -> None:
37-
#: ... email = notification.email
38-
#: ... if email:
39-
#: ... print(f"Processing email: {email.id}")
32+
#:
33+
#: .. code-block:: python
34+
#:
35+
#: async def handle_email(
36+
#: context: TurnContext,
37+
#: state: TurnState,
38+
#: notification: AgentNotificationActivity,
39+
#: ) -> None:
40+
#: email = notification.email
41+
#: if email:
42+
#: print(f"Processing email: {email.id}")
4043
AgentHandler = Callable[[TContext, TState, AgentNotificationActivity], Awaitable[None]]
4144

4245

@@ -55,15 +58,19 @@ class AgentNotification:
5558
defaults to all values in the AgentLifecycleEvent enum.
5659
5760
Example:
58-
>>> from microsoft_agents.hosting import Application
59-
>>> from microsoft_agents_a365.notifications import AgentNotification
60-
>>> app = Application()
61-
>>> notifications = AgentNotification(app)
62-
>>> @notifications.on_email()
63-
... async def handle_email(context, state, notification):
64-
... email = notification.email
65-
... if email:
66-
... await context.send_activity(f"Received email: {email.id}")
61+
.. code-block:: python
62+
63+
from microsoft_agents.hosting import Application
64+
from microsoft_agents_a365.notifications import AgentNotification
65+
66+
app = Application()
67+
notifications = AgentNotification(app)
68+
69+
@notifications.on_email()
70+
async def handle_email(context, state, notification):
71+
email = notification.email
72+
if email:
73+
await context.send_activity(f"Received email: {email.id}")
6774
"""
6875

6976
def __init__(
@@ -120,12 +127,15 @@ def on_agent_notification(
120127
A decorator function that registers the handler with the application.
121128
122129
Example:
123-
>>> from microsoft_agents.activity import ChannelId
124-
>>> @notifications.on_agent_notification(
125-
... ChannelId(channel="agents", sub_channel="email")
126-
... )
127-
... async def handle_custom_channel(context, state, notification):
128-
... print(f"Received notification on {notification.channel}/{notification.sub_channel}")
130+
.. code-block:: python
131+
132+
from microsoft_agents.activity import ChannelId
133+
134+
@notifications.on_agent_notification(
135+
ChannelId(channel="agents", sub_channel="email")
136+
)
137+
async def handle_custom_channel(context, state, notification):
138+
print(f"Received notification on {notification.channel}/{notification.sub_channel}")
129139
"""
130140
registered_channel = channel_id.channel.lower()
131141
registered_subchannel = (channel_id.sub_channel or "*").lower()
@@ -175,9 +185,11 @@ def on_agent_lifecycle_notification(
175185
A decorator function that registers the handler with the application.
176186
177187
Example:
178-
>>> @notifications.on_agent_lifecycle_notification("agenticuseridentitycreated")
179-
... async def handle_user_created(context, state, notification):
180-
... print("New user created")
188+
.. code-block:: python
189+
190+
@notifications.on_agent_lifecycle_notification("agenticuseridentitycreated")
191+
async def handle_user_created(context, state, notification):
192+
print("New user created")
181193
"""
182194

183195
def route_selector(context: TurnContext) -> bool:
@@ -223,15 +235,17 @@ def on_email(
223235
A decorator function that registers the handler with the application.
224236
225237
Example:
226-
>>> @notifications.on_email()
227-
... async def handle_email(context, state, notification):
228-
... email = notification.email
229-
... if email:
230-
... print(f"Received email: {email.id}")
231-
... response = EmailResponse.create_email_response_activity(
232-
... "<p>Thank you for your email.</p>"
233-
... )
234-
... await context.send_activity(response)
238+
.. code-block:: python
239+
240+
@notifications.on_email()
241+
async def handle_email(context, state, notification):
242+
email = notification.email
243+
if email:
244+
print(f"Received email: {email.id}")
245+
response = EmailResponse.create_email_response_activity(
246+
"<p>Thank you for your email.</p>"
247+
)
248+
await context.send_activity(response)
235249
"""
236250
return self.on_agent_notification(
237251
ChannelId(channel="agents", sub_channel=AgentSubChannel.EMAIL), **kwargs
@@ -252,11 +266,13 @@ def on_word(
252266
A decorator function that registers the handler with the application.
253267
254268
Example:
255-
>>> @notifications.on_word()
256-
... async def handle_word_comment(context, state, notification):
257-
... comment = notification.wpx_comment
258-
... if comment:
259-
... print(f"Received Word comment: {comment.comment_id}")
269+
.. code-block:: python
270+
271+
@notifications.on_word()
272+
async def handle_word_comment(context, state, notification):
273+
comment = notification.wpx_comment
274+
if comment:
275+
print(f"Received Word comment: {comment.comment_id}")
260276
"""
261277
return self.on_agent_notification(
262278
ChannelId(channel="agents", sub_channel=AgentSubChannel.WORD), **kwargs
@@ -277,11 +293,13 @@ def on_excel(
277293
A decorator function that registers the handler with the application.
278294
279295
Example:
280-
>>> @notifications.on_excel()
281-
... async def handle_excel_comment(context, state, notification):
282-
... comment = notification.wpx_comment
283-
... if comment:
284-
... print(f"Received Excel comment: {comment.comment_id}")
296+
.. code-block:: python
297+
298+
@notifications.on_excel()
299+
async def handle_excel_comment(context, state, notification):
300+
comment = notification.wpx_comment
301+
if comment:
302+
print(f"Received Excel comment: {comment.comment_id}")
285303
"""
286304
return self.on_agent_notification(
287305
ChannelId(channel="agents", sub_channel=AgentSubChannel.EXCEL), **kwargs
@@ -302,11 +320,13 @@ def on_powerpoint(
302320
A decorator function that registers the handler with the application.
303321
304322
Example:
305-
>>> @notifications.on_powerpoint()
306-
... async def handle_powerpoint_comment(context, state, notification):
307-
... comment = notification.wpx_comment
308-
... if comment:
309-
... print(f"Received PowerPoint comment: {comment.comment_id}")
323+
.. code-block:: python
324+
325+
@notifications.on_powerpoint()
326+
async def handle_powerpoint_comment(context, state, notification):
327+
comment = notification.wpx_comment
328+
if comment:
329+
print(f"Received PowerPoint comment: {comment.comment_id}")
310330
"""
311331
return self.on_agent_notification(
312332
ChannelId(channel="agents", sub_channel=AgentSubChannel.POWERPOINT), **kwargs
@@ -327,9 +347,11 @@ def on_lifecycle(
327347
A decorator function that registers the handler with the application.
328348
329349
Example:
330-
>>> @notifications.on_lifecycle()
331-
... async def handle_any_lifecycle_event(context, state, notification):
332-
... print(f"Lifecycle event type: {notification.notification_type}")
350+
.. code-block:: python
351+
352+
@notifications.on_lifecycle()
353+
async def handle_any_lifecycle_event(context, state, notification):
354+
print(f"Lifecycle event type: {notification.notification_type}")
333355
"""
334356
return self.on_lifecycle_notification("*", **kwargs)
335357

@@ -348,9 +370,11 @@ def on_user_created(
348370
A decorator function that registers the handler with the application.
349371
350372
Example:
351-
>>> @notifications.on_user_created()
352-
... async def handle_user_created(context, state, notification):
353-
... print("New agentic user identity created")
373+
.. code-block:: python
374+
375+
@notifications.on_user_created()
376+
async def handle_user_created(context, state, notification):
377+
print("New agentic user identity created")
354378
"""
355379
return self.on_lifecycle_notification(AgentLifecycleEvent.USERCREATED, **kwargs)
356380

@@ -369,9 +393,11 @@ def on_user_workload_onboarding(
369393
A decorator function that registers the handler with the application.
370394
371395
Example:
372-
>>> @notifications.on_user_workload_onboarding()
373-
... async def handle_onboarding_update(context, state, notification):
374-
... print("User workload onboarding status updated")
396+
.. code-block:: python
397+
398+
@notifications.on_user_workload_onboarding()
399+
async def handle_onboarding_update(context, state, notification):
400+
print("User workload onboarding status updated")
375401
"""
376402
return self.on_lifecycle_notification(
377403
AgentLifecycleEvent.USERWORKLOADONBOARDINGUPDATED, **kwargs
@@ -392,9 +418,11 @@ def on_user_deleted(
392418
A decorator function that registers the handler with the application.
393419
394420
Example:
395-
>>> @notifications.on_user_deleted()
396-
... async def handle_user_deleted(context, state, notification):
397-
... print("Agentic user identity deleted")
421+
.. code-block:: python
422+
423+
@notifications.on_user_deleted()
424+
async def handle_user_deleted(context, state, notification):
425+
print("Agentic user identity deleted")
398426
"""
399427
return self.on_lifecycle_notification(AgentLifecycleEvent.USERDELETED, **kwargs)
400428

‎libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/models/agent_notification_activity.py‎

Lines changed: 22 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -28,15 +28,17 @@ class AgentNotificationActivity:
2828
activity: The underlying Activity object.
2929
3030
Example:
31-
>>> async def email_handler(
32-
... context: TurnContext,
33-
... state: TurnState,
34-
... notification: AgentNotificationActivity,
35-
... ) -> None:
36-
... email = notification.email
37-
... if email:
38-
... print(f"Received email: {email.id}")
39-
... print(f"Body: {email.html_body}")
31+
.. code-block:: python
32+
33+
async def email_handler(
34+
context: TurnContext,
35+
state: TurnState,
36+
notification: AgentNotificationActivity,
37+
) -> None:
38+
email = notification.email
39+
if email:
40+
print(f"Received email: {email.id}")
41+
print(f"Body: {email.html_body}")
4042
"""
4143

4244
def __init__(self, activity: Activity):
@@ -160,13 +162,17 @@ def as_model(self, model: Type[TModel]) -> Optional[TModel]:
160162
An instance of the specified model type if validation succeeds, otherwise None.
161163
162164
Example:
163-
>>> from pydantic import BaseModel
164-
>>> class CustomNotification(BaseModel):
165-
... custom_field: str
166-
>>> notification = AgentNotificationActivity(activity)
167-
>>> custom = notification.as_model(CustomNotification)
168-
>>> if custom:
169-
... print(custom.custom_field)
165+
.. code-block:: python
166+
167+
from pydantic import BaseModel
168+
169+
class CustomNotification(BaseModel):
170+
custom_field: str
171+
172+
notification = AgentNotificationActivity(activity)
173+
custom = notification.as_model(CustomNotification)
174+
if custom:
175+
print(custom.custom_field)
170176
"""
171177
try:
172178
return model.model_validate(self.value or {})

‎libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/models/email_response.py‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -36,10 +36,12 @@ def create_email_response_activity(email_response_html_body: str) -> Activity:
3636
entity attached to its entities list.
3737
3838
Example:
39-
>>> activity = EmailResponse.create_email_response_activity(
40-
... "<p>Thank you for your email. I'll get back to you soon.</p>"
41-
... )
42-
>>> await context.send_activity(activity)
39+
.. code-block:: python
40+
41+
activity = EmailResponse.create_email_response_activity(
42+
"<p>Thank you for your email. I'll get back to you soon.</p>"
43+
)
44+
await context.send_activity(activity)
4345
"""
4446
working_activity = Activity(type="message")
4547
email_response = EmailResponse(html_body=email_response_html_body)

0 commit comments

Comments
 (0)