Skip to content

mm-api-ref-docs-fixes-wip #690

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Feb 4, 2020
Merged

mm-api-ref-docs-fixes-wip #690

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
f3033f3
mm-api-ref-docs-fixes-wip
Feb 3, 2020
e7721f2
Update bot_state.py
Feb 3, 2020
8e1ef4f
Update conversation_state.py
Feb 3, 2020
1702348
Update activity_handler.py
Feb 3, 2020
030a346
Update bot_framework_adapter.py
Feb 3, 2020
aa571ed
Fixed ref links and comments
Feb 3, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 26 additions & 30 deletions libraries/botbuilder-core/botbuilder/core/activity_handler.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,20 +13,17 @@ async def on_turn(self, turn_context: TurnContext):
in order to process an inbound :class:`botbuilder.schema.Activity`.

:param turn_context: The context object for this turn
:type turn_context: :class:`TurnContext`
:type turn_context: :class:`botbuilder.core.TurnContext`

:returns: A task that represents the work queued to execute

.. remarks::
It calls other methods in this class based on the type of the activity to
process, which allows a derived class to provide type-specific logic in a controlled way.
In a derived class, override this method to add logic that applies to all activity types.

.. note::
- Add logic to apply before the type-specific logic and before the call to the
:meth:`ActivityHandler.on_turn()` method.
- Add logic to apply after the type-specific logic after the call to the
:meth:`ActivityHandler.on_turn()` method.
Also
- Add logic to apply before the type-specific logic and before calling :meth:`ActivityHandler.on_turn()`.
- Add logic to apply after the type-specific logic after calling :meth:`ActivityHandler.on_turn()`.
"""
if turn_context is None:
raise TypeError("ActivityHandler.on_turn(): turn_context cannot be None.")
Expand Down Expand Up @@ -65,10 +62,9 @@ async def on_message_activity( # pylint: disable=unused-argument
such as the conversational logic.

:param turn_context: The context object for this turn
:type turn_context: :class:`TurnContext`
:type turn_context: :class:`botbuilder.core.TurnContext`

:returns: A task that represents the work queued to execute

"""
return

Expand All @@ -78,11 +74,11 @@ async def on_conversation_update_activity(self, turn_context: TurnContext):
:meth:`ActivityHandler.on_turn()` is used.

:param turn_context: The context object for this turn
:type turn_context: :class:`TurnContext`
:type turn_context: :class:`botbuilder.core.TurnContext`

:returns: A task that represents the work queued to execute

.. note::
.. remarks::
When the :meth:'ActivityHandler.on_turn()` method receives a conversation update activity, it calls this
method.
If the conversation update activity indicates that members other than the bot joined the conversation,
Expand Down Expand Up @@ -119,11 +115,11 @@ async def on_members_added_activity(
conversation update activity
:type members_added: :class:`typing.List`
:param turn_context: The context object for this turn
:type turn_context: :class:`TurnContext`
:type turn_context: :class:`botbuilder.core.TurnContext`

:returns: A task that represents the work queued to execute

.. note::
.. remarks::
When the :meth:'ActivityHandler.on_conversation_update_activity()` method receives a conversation
update activity that indicates
one or more users other than the bot are joining the conversation, it calls this method.
Expand All @@ -141,11 +137,11 @@ async def on_members_removed_activity(
conversation update activity
:type members_added: :class:`typing.List`
:param turn_context: The context object for this turn
:type turn_context: :class:`TurnContext`
:type turn_context: :class:`botbuilder.core.TurnContext`

:returns: A task that represents the work queued to execute

.. note::
.. remarks::
When the :meth:'ActivityHandler.on_conversation_update_activity()` method receives a conversation
update activity that indicates one or more users other than the bot are leaving the conversation,
it calls this method.
Expand All @@ -159,11 +155,11 @@ async def on_message_reaction_activity(self, turn_context: TurnContext):
:meth:'ActivityHandler.on_turn()` is used.

:param turn_context: The context object for this turn
:type turn_context: :class:`TurnContext`
:type turn_context: :class:`botbuilder.core.TurnContext`

:returns: A task that represents the work queued to execute

.. note::
.. remarks::
Message reactions correspond to the user adding a 'like' or 'sad' etc. (often an emoji) to a previously
sent activity.
Message reactions are only supported by a few channels. The activity that the message reaction corresponds
Expand Down Expand Up @@ -200,11 +196,11 @@ async def on_reactions_added( # pylint: disable=unused-argument
:param message_reactions: The list of reactions added
:type message_reactions: :class:`typing.List`
:param turn_context: The context object for this turn
:type turn_context: :class:`TurnContext`
:type turn_context: :class:`botbuilder.core.TurnContext`

:returns: A task that represents the work queued to execute

.. note::
.. remarks::
Message reactions correspond to the user adding a 'like' or 'sad' etc. (often an emoji)
to a previously sent message on the conversation. Message reactions are supported by only a few channels.
The activity that the message is in reaction to is identified by the activity's reply to Id property.
Expand All @@ -223,11 +219,11 @@ async def on_reactions_removed( # pylint: disable=unused-argument
:param message_reactions: The list of reactions removed
:type message_reactions: :class:`typing.List`
:param turn_context: The context object for this turn
:type turn_context: :class:`TurnContext`
:type turn_context: :class:`botbuilder.core.TurnContext`

:returns: A task that represents the work queued to execute

.. note::
.. remarks::
Message reactions correspond to the user adding a 'like' or 'sad' etc. (often an emoji)
to a previously sent message on the conversation. Message reactions are supported by only a few channels.
The activity that the message is in reaction to is identified by the activity's reply to Id property.
Expand All @@ -242,11 +238,11 @@ async def on_event_activity(self, turn_context: TurnContext):
:meth:'ActivityHandler.on_turn()` is used.

:param turn_context: The context object for this turn
:type turn_context: :class:`TurnContext`
:type turn_context: :class:`botbuilder.core.TurnContext`

:returns: A task that represents the work queued to execute

.. note::
.. remarks::
When the :meth:'ActivityHandler.on_turn()` method receives an event activity, it calls this method.
If the activity name is `tokens/response`, it calls :meth:'ActivityHandler.on_token_response_event()`;
otherwise, it calls :meth:'ActivityHandler.on_event()`.
Expand All @@ -273,11 +269,11 @@ async def on_token_response_event( # pylint: disable=unused-argument
If using an `oauth_prompt`, override this method to forward this activity to the current dialog.

:param turn_context: The context object for this turn
:type turn_context: :class:`TurnContext`
:type turn_context: :class:`botbuilder.core.TurnContext`

:returns: A task that represents the work queued to execute

.. note::
.. remarks::
When the :meth:'ActivityHandler.on_event()` method receives an event with an activity name of
`tokens/response`, it calls this method. If your bot uses an `oauth_prompt`, forward the incoming
activity to the current dialog.
Expand All @@ -293,11 +289,11 @@ async def on_event( # pylint: disable=unused-argument


:param turn_context: The context object for this turn
:type turn_context: :class:`TurnContext`
:type turn_context: :class:`botbuilder.core.TurnContext`

:returns: A task that represents the work queued to execute

.. note::
.. remarks::
When the :meth:'ActivityHandler.on_event_activity()` is used method receives an event with an
activity name other than `tokens/response`, it calls this method.
This method could optionally be overridden if the bot is meant to handle miscellaneous events.
Expand All @@ -311,7 +307,7 @@ async def on_end_of_conversation_activity( # pylint: disable=unused-argument
Invoked when a conversation end activity is received from the channel.

:param turn_context: The context object for this turn
:type turn_context: :class:`TurnContext`
:type turn_context: :class:`botbuilder.core.TurnContext`
:returns: A task that represents the work queued to execute
"""
return
Expand All @@ -325,11 +321,11 @@ async def on_unrecognized_activity_type( # pylint: disable=unused-argument
If overridden, this method could potentially respond to any of the other activity types.

:param turn_context: The context object for this turn
:type turn_context: :class:`TurnContext`
:type turn_context: :class:`botbuilder.core.TurnContext`

:returns: A task that represents the work queued to execute

.. note::
.. remarks::
When the :meth:`ActivityHandler.on_turn()` method receives an activity that is not a message,
conversation update, message reaction, or event activity, it calls this method.
"""
Expand Down
57 changes: 26 additions & 31 deletions libraries/botbuilder-core/botbuilder/core/bot_framework_adapter.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,11 +87,9 @@ def __init__(
"""
Contains the settings used to initialize a :class:`BotFrameworkAdapter` instance.

:param app_id: The bot application ID. This is the appId returned by the Azure portal registration, and is
the value of the `MicrosoftAppId` parameter in the `config.py` file.
:param app_id: The bot application ID.
:type app_id: str
:param app_password: The bot application password. This is the password returned by the Azure portal
registration, and is
:param app_password: The bot application password.
the value os the `MicrosoftAppPassword` parameter in the `config.py` file.
:type app_password: str
:param channel_auth_tenant: The channel tenant to use in conversation
Expand Down Expand Up @@ -201,7 +199,7 @@ async def continue_conversation(

:return: A task that represents the work queued to execute.

.. note::
.. remarks::
This is often referred to as the bots *proactive messaging* flow as it lets the bot proactively
send messages to a conversation or user that are already in a communication.
Scenarios such as sending notifications or coupons to a user are enabled by this function.
Expand Down Expand Up @@ -247,7 +245,7 @@ async def create_conversation(

:return: A task representing the work queued to execute.

.. note::
.. remarks::
To start a conversation, your bot must know its account information and the user's
account information on that channel.
Most channels only support initiating a direct message (non-group) conversation.
Expand Down Expand Up @@ -306,9 +304,7 @@ async def create_conversation(

async def process_activity(self, req, auth_header: str, logic: Callable):
"""
Creates a turn context and runs the middleware pipeline for an incoming activity,
Processes an activity received by the bots web server. This includes any messages sent from a
user and is the method that drives what's often referred to as the bots *reactive messaging* flow.
Creates a turn context and runs the middleware pipeline for an incoming activity.

:param req: The incoming activity
:type req: :class:`typing.str`
Expand All @@ -317,15 +313,15 @@ async def process_activity(self, req, auth_header: str, logic: Callable):
:param logic: The logic to execute at the end of the adapter's middleware pipeline.
:type logic: :class:`typing.Callable`

:return: A task that represents the work queued to execute. If the activity type
was `Invoke` and the corresponding key (`channelId` + `activityId`) was found then
an :class:`InvokeResponse` is returned; otherwise, `null` is returned.
:return: A task that represents the work queued to execute.

.. note::
.. remarks::
This class processes an activity received by the bots web server. This includes any messages
sent from a user and is the method that drives what's often referred to as the
bots *reactive messaging* flow.
Call this method to reactively send a message to a conversation.
If the task completes successfully, then an :class:`InvokeResponse` is returned;
otherwise. `null` is returned.

"""
activity = await self.parse_request(req)
auth_header = auth_header or ""
Expand Down Expand Up @@ -457,7 +453,7 @@ async def update_activity(self, context: TurnContext, activity: Activity):

:return: A task that represents the work queued to execute

.. note::
.. remarks::
If the activity is successfully sent, the task result contains
a :class:`botbuilder.schema.ResourceResponse` object containing the ID that
the receiving channel assigned to the activity.
Expand Down Expand Up @@ -490,6 +486,7 @@ async def delete_activity(
:return: A task that represents the work queued to execute

.. note::

The activity_id of the :class:`botbuilder.schema.ConversationReference` identifies the activity to delete.
"""
try:
Expand Down Expand Up @@ -565,7 +562,7 @@ async def delete_conversation_member(
Deletes a member from the current conversation.

:param context: The context object for the turn
:type context: :class:`TurnContext`
:type context: :class:`botbuilder.core.TurnContext`
:param member_id: The ID of the member to remove from the conversation
:type member_id: str

Expand Down Expand Up @@ -603,7 +600,7 @@ async def get_activity_members(self, context: TurnContext, activity_id: str):
Lists the members of a given activity.

:param context: The context object for the turn
:type context: :class:`TurnContext`
:type context: :class:`botbuilder.core.TurnContext`
:param activity_id: (Optional) Activity ID to enumerate.
If not specified the current activities ID will be used.

Expand Down Expand Up @@ -645,7 +642,7 @@ async def get_conversation_members(self, context: TurnContext):
Lists the members of a current conversation.

:param context: The context object for the turn
:type context: :class:`TurnContext`
:type context: :class:`botbuilder.core.TurnContext`

:raises: An exception error

Expand Down Expand Up @@ -674,9 +671,7 @@ async def get_conversation_members(self, context: TurnContext):

async def get_conversations(self, service_url: str, continuation_token: str = None):
"""
Lists the Conversations in which this bot has participated for a given channel server. The channel server
returns results in pages and each page will include a `continuationToken` that can be used to fetch the next
page of results from the server.
Lists the Conversations in which this bot has participated for a given channel server.

:param service_url: The URL of the channel server to query. This can be retrieved from
`context.activity.serviceUrl`
Expand All @@ -689,8 +684,10 @@ async def get_conversations(self, service_url: str, continuation_token: str = No

:return: A task that represents the work queued to execute

.. note:: If the task completes successfully, the result contains a page of the members of the current
conversation.
.. remarks::
The channel server returns results in pages and each page will include a `continuationToken` that
can be used to fetch the next page of results from the server.
If the task completes successfully, the result contains a page of the members of the current conversation.
This overload may be called from outside the context of a conversation, as only the bot's service URL and
credentials are required.
"""
Expand All @@ -705,7 +702,7 @@ async def get_user_token(
Attempts to retrieve the token for a user that's in a login flow.

:param context: Context for the current turn of conversation with the user
:type context: :class:`TurnContext`
:type context: :class:`botbuilder.core.TurnContext`
:param connection_name: Name of the auth connection to use
:type connection_name: str
:param magic_code" (Optional) user entered code to validate
Expand Down Expand Up @@ -752,7 +749,7 @@ async def sign_out_user(
Signs the user out with the token server.

:param context: Context for the current turn of conversation with the user
:type context: :class:`TurnContext`
:type context: :class:`botbuilder.core.TurnContext`
:param connection_name: Name of the auth connection to use
:type connection_name: str
:param user_id: User id of user to sign out
Expand Down Expand Up @@ -781,13 +778,14 @@ async def get_oauth_sign_in_link(
Gets the raw sign-in link to be sent to the user for sign-in for a connection name.

:param context: Context for the current turn of conversation with the user
:type context: :class:`TurnContext`
:type context: :class:`botbuilder.core.TurnContext`
:param connection_name: Name of the auth connection to use
:type connection_name: str

:returns: A task that represents the work queued to execute

.. note::

If the task completes successfully, the result contains the raw sign-in link
"""
self.check_emulating_oauth_cards(context)
Expand All @@ -814,7 +812,7 @@ async def get_token_status(
Retrieves the token status for each configured connection for the given user.

:param context: Context for the current turn of conversation with the user
:type context: :class:`TurnContext`
:type context: :class:`botbuilder.core.TurnContext`
:param user_id: The user Id for which token status is retrieved
:type user_id: str
:param include_filter: (Optional) Comma separated list of connection's to include.
Expand Down Expand Up @@ -848,14 +846,11 @@ async def get_aad_tokens(
Retrieves Azure Active Directory tokens for particular resources on a configured connection.

:param context: Context for the current turn of conversation with the user
:type context: :class:`TurnContext`

:type context: :class:`botbuilder.core.TurnContext`
:param connection_name: The name of the Azure Active Directory connection configured with this bot
:type connection_name: str

:param resource_urls: The list of resource URLs to retrieve tokens for
:type resource_urls: :class:`typing.List`

:returns: Dictionary of resource Urls to the corresponding :class:'botbuilder.schema.TokenResponse`
:rtype: :class:`typing.Dict`
"""
Expand Down
Loading