8000 botbuilder-adapter-slack reference comment updates · itsmokha/botbuilder-python@c44e273 · GitHub
[go: up one dir, main page]
Skip to content

Commit c44e273

Browse files
author
Emily Olshefski
committed
botbuilder-adapter-slack reference comment updates
1 parent e88913b commit c44e273

File tree

3 files changed

+86
-42
lines changed

3 files changed

+86
-42
lines changed

‎libraries/botbuilder-adapters-slack/botbuilder/adapters/slack/slack_adapter.py

Lines changed: 31 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,7 @@
2424

2525
class SlackAdapter(BotAdapter, ABC):
2626
"""
27-
BotAdapter that can handle incoming slack events. Incoming slack events are deserialized to an Activity
28-
that is dispatch through the middleware and bot pipeline.
27+
BotAdapter that can handle incoming Slack events. Incoming Slack events are deserialized to an Activity that is dispatched through the middleware and bot pipeline.
2928
"""
3029

3130
def __init__(
@@ -41,11 +40,14 @@ async def send_activities(
4140
self, context: TurnContext, activities: List[Activity]
4241
) -> List[ResourceResponse]:
4342
"""
44-
Standard BotBuilder adapter method to send a message from the bot to the messaging API.
43+
Send a message from the bot to the messaging API.
4544
4645
:param context: A TurnContext representing the current incoming message and environment.
46+
:type context: :class:`botbuilder.core.TurnContext`
4747
:param activities: An array of outgoing activities to be sent back to the messaging API.
48+
:type activities: :class:`typing.List`
4849
:return: An array of ResourceResponse objects containing the IDs that Slack assigned to the sent messages.
50+
:rtype: :class:`typing.List`
4951
"""
5052

5153
if not context:
@@ -76,11 +78,14 @@ async def send_activities(
7678

7779
async def update_activity(self, context: TurnContext, activity: Activity):
7880
"""
79-
Standard BotBuilder adapter method to update a previous message with new content.
81+
Update a previous message with new content.
8082
8183
:param context: A TurnContext representing the current incoming message and environment.
84+
:type context: :class:`botbuilder.core.TurnContext`
8285
:param activity: The updated activity in the form '{id: `id of activity to update`, ...}'.
83-
:return: A resource response with the Id of the updated activity.
86+
:type activity: :class:`botbuilder.schema.Activity`
87+
:return: A resource response with the ID of the updated activity.
88+
:rtype: :class:`botbuilder.schema.ResourceResponse`
8489
"""
8590

8691
if not context:
@@ -106,11 +111,13 @@ async def delete_activity(
106111
self, context: TurnContext, reference: ConversationReference
107112
):
108113
"""
109-
Standard BotBuilder adapter method to delete a previous message.
114+
Delete a previous message.
110115
111116
:param context: A TurnContext representing the current incoming message and environment.
117+
:type context: :class:`botbuilder.core.TurnContext`
112118
:param reference: An object in the form "{activityId: `id of message to delete`,
113-
conversation: { id: `id of slack channel`}}".
119+
conversation: { id: `id of Slack channel`}}".
120+
:type reference: :class:`botbuilder.schema.ConversationReference`
114121
"""
115122

116123
if not context:
@@ -135,15 +142,22 @@ async def continue_conversation(
135142
audience: str = None,
136143
):
137144
"""
138-
Sends a proactive message to a conversation. Call this method to proactively send a message to a conversation.
139-
Most _channels require a user to initiate a conversation with a bot before the bot can send activities
140-
to the user.
145+
Send a proactive message to a conversation.
146+
147+
.. remarks::
148+
149+
Most channels require a user to initiate a conversation with a bot before the bot can send activities to the user.
141150
142-
:param bot_id: Unused for this override.
143151
:param reference: A reference to the conversation to continue.
152+
:type reference: :class:`botbuilder.schema.ConversationReference`
144153
:param callback: The method to call for the resulting bot turn.
154+
:type callback: :class:`typing.Callable`
155+
:param bot_id: Unused for this override.
156+
:type bot_id: str
145157
:param claims_identity: A ClaimsIdentity for the conversation.
158+
:type claims_identity: :class:`botframework.connector.auth.ClaimsIdentity`
146159
:param audience: Unused for this override.
160+
:type audience: str
147161
"""
148162

149163
if not reference:
@@ -171,10 +185,14 @@ async def process(self, req: Request, logic: Callable) -> Response:
171185
"""
172186
Accept an incoming webhook request and convert it into a TurnContext which can be processed by the bot's logic.
173187
174-
:param req: The aoihttp Request object
188+
:param req: The aiohttp Request object.
189+
:type req: :class:`aiohttp.web_request.Request`
175190
:param logic: The method to call for the resulting bot turn.
176-
:return: The aoihttp Response
191+
:type logic: :class:`typing.List`
192+
:return: The aiohttp Response.
193+
:rtype: :class:`aiohttp.web_response.Response`
177194
"""
195+
178196
if not req:
179197
raise Exception("Request is required")
180198

‎libraries/botbuilder-adapters-slack/botbuilder/adapters/slack/slack_helper.py

Lines changed: 38 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,12 @@ class SlackHelper:
2727
@staticmethod
2828
def activity_to_slack(activity: Activity) -> SlackMessage:
2929
"""
30-
Formats a BotBuilder activity into an outgoing Slack message.
30+
Formats a BotBuilder Activity into an outgoing Slack message.
31+
3132
:param activity: A BotBuilder Activity object.
32-
:return: A Slack message object with {text, attachments, channel, thread ts} as well
33-
as any fields found in activity.channelData
33+
:type activity: :class:`botbuilder.schema.Activity`
34+
:return: A Slack message object with {text, attachments, channel, thread ts} and any fields found in activity.channelData.
35+
:rtype: :class:`SlackMessage`
3436
"""
3537

3638
if not activity:
@@ -83,13 +85,18 @@ def response( # pylint: disable=unused-argument
8385
req: Request, code: int, text: str = None, encoding: str = None
8486
) -> Response:
8587
"""
86-
Formats an aiohttp Response
87-
88-
:param req: The original aoihttp Request
89-
:param code: The HTTP result code to return
90-
:param text: The text to return
91-
:param encoding: The text encoding. Defaults to utf-8
88+
Formats an aiohttp Response.
89+
90+
:param req: The original aiohttp Request.
91+
:type req: :class:`aiohttp.web_request.Request`
92+
:param code: The HTTP result code to return.
93+
:type code: int
94+
:param text: The text to return.
95+
:type text: str
96+
:param encoding: The text encoding. Defaults to UTF-8.
97+
:type encoding: str
9298
:return: The aoihttp Response
99+
:rtype: :class:`aiohttp.web_response.Response`
93100
"""
94101

95102
response = Response(status=code)
@@ -103,10 +110,12 @@ def response( # pylint: disable=unused-argument
103110
@staticmethod
104111
def payload_to_activity(payload: SlackPayload) -> Activity:
105112
"""
106-
Creates an activity based on the slack event payload.
113+
Creates an activity based on the Slack event payload.
107114
108-
:param payload: The payload of the slack event.
115+
:param payload: The payload of the Slack event.
116+
:type payload: :class:`SlackPayload`
109117
:return: An activity containing the event data.
118+
:rtype: :class:`botbuilder.schema.Activity`
110119
"""
111120

112121
if not payload:
@@ -138,11 +147,14 @@ def payload_to_activity(payload: SlackPayload) -> Activity:
138147
@staticmethod
139148
async def event_to_activity(event: SlackEvent, client: SlackClient) -> Activity:
140149
"""
141-
Creates an activity based on the slack event data.
150+
Creates an activity based on the Slack event data.
142151
143-
:param event: The data of the slack event.
152+
:param event: The data of the Slack event.
153+
:type event: :class:`SlackEvent`
144154
:param client: The Slack client.
155+
:type client: :class:`SlackClient`
145156
:return: An activity containing the event data.
157+
:rtype: :class:`botbuilder.schema.Activity`
146158
"""
147159

148160
if not event:
@@ -191,11 +203,14 @@ async def command_to_activity(
191203
body: SlackRequestBody, client: SlackClient
192204
) -> Activity:
193205
"""
194-
Creates an activity based on a slack event related to a slash command.
206+
Creates an activity based on a Slack event related to a slash command.
195207
196-
:param body: The data of the slack event.
208+
:param body: The data of the Slack event.
209+
:type body: :class:`SlackRequestBody`
197210
:param client: The Slack client.
211+
:type client: :class:`SlackClient`
198212
:return: An activity containing the event data.
213+
:rtype: :class:`botbuilder.schema.Activity`
199214
"""
200215

201216
if not body:
@@ -223,7 +238,9 @@ def query_string_to_dictionary(query: str) -> {}:
223238
Converts a query string to a dictionary with key-value pairs.
224239
225240
:param query: The query string to convert.
241+
:type query: str
226242
:return: A dictionary with the query values.
243+
:rtype: :class:`typing.Dict`
227244
"""
228245

229246
values = {}
@@ -247,9 +264,12 @@ def deserialize_body(content_type: str, request_body: str) -> SlackRequestBody:
247264
"""
248265
Deserializes the request's body as a SlackRequestBody object.
249266
250-
:param content_type: The content type of the body
251-
:param request_body: The body of the request
252-
:return: A SlackRequestBody object
267+
:param content_type: The content type of the body.
268+
:type content_type: str
269+
:param request_body: The body of the request.
270+
:type request_body: str
271+
:return: A SlackRequestBody object.
272+
:rtype: :class:`SlackRequestBody`
253273
"""
254274

255275
if not request_body:

‎libraries/botbuilder-adapters-slack/botbuilder/adapters/slack/slack_options.py

Lines changed: 17 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
class SlackAdapterOptions:
66
"""
7-
Class for defining implementation of the SlackAdapter Options.
7+
Defines the implementation of the SlackAdapter options.
88
"""
99

1010
def __init__(
@@ -14,10 +14,14 @@ def __init__(
1414
slack_client_signing_secret: str,
1515
):
1616
"""
17-
Initializes new instance of SlackAdapterOptions
17+
Initializes a new instance of SlackAdapterOptions.
18+
1819
:param slack_verification_token: A token for validating the origin of incoming webhooks.
20+
:type slack_verification_token: str
1921
:param slack_bot_token: A token for a bot to work on a single workspace.
20-
:param slack_client_signing_secret: The token used to validate that incoming webhooks are originated from Slack.
22+
:type slack_bot_token: str
23+
:param slack_client_signing_secret: The token used to validate that incoming webhooks originated from Slack.
24+
:type slack_client_signing_secret: str
2125
"""
2226
self.slack_verification_token = slack_verification_token
2327
self.slack_bot_token = slack_bot_token
@@ -29,18 +33,20 @@ def __init__(
2933

3034
async def get_token_for_team(self, team_id: str) -> str:
3135
"""
32-
A method that receives a Slack team id and returns the bot token associated with that team. Required for
33-
multi-team apps.
34-
:param team_id:Team ID.
35-
:return:The bot token associated with the team.
36+
Receives a Slack team ID and returns the bot token associated with that team. Required for multi-team apps.
37+
38+
:param team_id: The team ID.
39+
:type team_id: str
40+
:raises: :func:`NotImplementedError`
3641
"""
3742
raise NotImplementedError()
3843

3944
async def get_bot_user_by_team(self, team_id: str) -> str:
4045
"""
41-
A method that receives a Slack team id and returns the bot user id associated with that team. Required for
42-
multi-team apps.
43-
:param team_id:Team ID.
44-
:return:The bot user id associated with that team.
46+
A method that receives a Slack team ID and returns the bot user ID associated with that team. Required for multi-team apps.
47+
48+
:param team_id: The team ID.
49+
:type team_id: str
50+
:raises: :func:`NotImplementedError`
4551
"""
4652
raise NotImplementedError()

0 commit comments

Comments
 (0)
0