From feb1c5afef7d2861c7ece02a11091e9d88552d3c Mon Sep 17 00:00:00 2001 From: Emily Olshefski Date: Tue, 21 Jan 2020 13:49:30 -0800 Subject: [PATCH 1/4] emolsh/api-ref-docs-activityprompt --- .../dialogs/prompts/activity_prompt.py | 89 ++++++++++++++----- 1 file changed, 65 insertions(+), 24 deletions(-) diff --git a/libraries/botbuilder-dialogs/botbuilder/dialogs/prompts/activity_prompt.py b/libraries/botbuilder-dialogs/botbuilder/dialogs/prompts/activity_prompt.py index 5930441e1..0cfa4739f 100644 --- a/libraries/botbuilder-dialogs/botbuilder/dialogs/prompts/activity_prompt.py +++ b/libraries/botbuilder-dialogs/botbuilder/dialogs/prompts/activity_prompt.py @@ -24,9 +24,15 @@ class ActivityPrompt(Dialog, ABC): """ Waits for an activity to be received. - This prompt requires a validator be passed in and is useful when waiting for non-message - activities like an event to be received. The validator can ignore received events until the - expected activity is received. + ..remarks: + This prompt requires a validator be passed in and is useful when waiting for non-message + activities like an event to be received. The validator can ignore received events until the + expected activity is received. + + :var persisted_options: ? + :typevar persisted_options: str + :var persisted_state: ? + :vartype persisted_state: str """ persisted_options = "options" @@ -36,13 +42,12 @@ def __init__( self, dialog_id: str, validator: Callable[[PromptValidatorContext], bool] ): """ - Initializes a new instance of the ActivityPrompt class. + Initializes a new instance of the :class:`ActivityPrompt` class. - Parameters: - ---------- - dialog_id (str): Unique ID of the dialog within its parent DialogSet or ComponentDialog. - - validator: Validator that will be called each time a new activity is received. + :param dialog_id: Unique ID of the dialog within its parent :class:`DialogSet` or :class:`ComponentDialog`. + :type dialog_id: str + :param validator: Validator that will be called each time a new activity is received. + :type validator: Callable[[PromptValidatorContext], bool] """ Dialog.__init__(self, dialog_id) @@ -53,6 +58,16 @@ def __init__( async def begin_dialog( self, dialog_context: DialogContext, options: PromptOptions = None ) -> DialogTurnResult: + """ + Called when a prompt dialog is pushed onto the dialog stack and is being activated. + + :param dialog_context: The dialog context for the current turn of the conversation. + :type dialog_context: :class:`DialogContext` + :param options: Optional, additional information to pass to the prompt being started. + :type options: :class:`PromptOptions` + :return Dialog.end_of_turn: + :rtype Dialog.end_of_turn: :class:`Dialog.DialogTurnResult` + """ if not dialog_context: raise TypeError("ActivityPrompt.begin_dialog(): dc cannot be None.") if not isinstance(options, PromptOptions): @@ -84,6 +99,14 @@ async def begin_dialog( async def continue_dialog(self, dialog_context: DialogContext) -> DialogTurnResult: if not dialog_context: + """ + Called when a prompt dialog is the active dialog and the user replied with a new activity. + + :param dialog_context: The dialog context for the current turn of the conversation. + :type dialog_context: :class:`DialogContext` + :return Dialog.end_of_turn: + :rtype Dialog.end_of_turn: :class:`Dialog.DialogTurnResult` + """ raise TypeError( "ActivityPrompt.continue_dialog(): DialogContext cannot be None." ) @@ -130,11 +153,19 @@ async def resume_dialog( # pylint: disable=unused-argument self, dialog_context: DialogContext, reason: DialogReason, result: object = None ): """ - Prompts are typically leaf nodes on the stack but the dev is free to push other dialogs - on top of the stack which will result in the prompt receiving an unexpected call to - resume_dialog() when the pushed on dialog ends. - To avoid the prompt prematurely ending, we need to implement this method and - simply re-prompt the user + Called when a prompt dialog resumes being the active dialog on the dialog stack, such as when the previous active dialog on the stack completes. + ..remarks: + Prompts are typically leaf nodes on the stack but the dev is free to push other dialogs + on top of the stack which will result in the prompt receiving an unexpected call to + resume_dialog() when the pushed on dialog ends. + To avoid the prompt prematurely ending, we need to implement this method and + simply re-prompt the user. + :param dialog_context: The dialog context for the current turn of the conversation + :type dialog_context: :class:`DialogContext` + :param reason: An enum indicating why the dialog resumed. + :type reason: :class:`DialogReason` + :param result: >Optional, value returned from the previous dialog on the stack. The type of the value returned is dependent on the previous dialog. + :type result: object """ await self.reprompt_dialog(dialog_context.context, dialog_context.active_dialog) @@ -155,15 +186,14 @@ async def on_prompt( """ Called anytime the derived class should send the user a prompt. - Parameters: - ---------- - context: Context for the current turn of conversation with the user. - - state: Additional state being persisted for the prompt. - - options: Options that the prompt started with in the call to `DialogContext.prompt()`. - - isRetry: If `true` the users response wasn't recognized and the re-prompt should be sent. + :param dialog_context: The dialog context for the current turn of the conversation + :type dialog_context: :class:`DialogContext` + :param state: Additional state being persisted for the prompt. + :type state: Dict[str, dict] + :param options: Options that the prompt started with in the call to `DialogContext.prompt()`. + :type options: :class:`PromptOptions` + :param isRetry: If `true` the users response wasn't recognized and the re-prompt should be sent. + :type isRetry: bool """ if is_retry and options.retry_prompt: options.retry_prompt.input_hint = InputHints.expecting_input @@ -175,7 +205,18 @@ async def on_prompt( async def on_recognize( # pylint: disable=unused-argument self, context: TurnContext, state: Dict[str, object], options: PromptOptions ) -> PromptRecognizerResult: - + """ + When overridden in a derived class, attempts to recognize the incoming activity. + + :param context: Context for the current turn of conversation with the user. + :type context: :class:`TurnContext` + :param state: Contains state for the current instance of the prompt on the dialog stack. + :type state: Dict[str, object] + :param options: A prompt options object + :type options: :class:`PromptOptions` + :return result: constructed from the options initially provided in the call to `async def on_prompt()` + :rtype result: :class:`PromptRecognizerResult` + """ result = PromptRecognizerResult() result.succeeded = (True,) result.value = context.activity From ff0b5c3d64365ad384f4404dbad38593e5d5c2b6 Mon Sep 17 00:00:00 2001 From: Emily Olshefski Date: Tue, 21 Jan 2020 13:51:47 -0800 Subject: [PATCH 2/4] Update activity_prompt.py --- .../botbuilder/dialogs/prompts/activity_prompt.py | 1 - 1 file changed, 1 deletion(-) diff --git a/libraries/botbuilder-dialogs/botbuilder/dialogs/prompts/activity_prompt.py b/libraries/botbuilder-dialogs/botbuilder/dialogs/prompts/activity_prompt.py index 0cfa4739f..3a70d17cc 100644 --- a/libraries/botbuilder-dialogs/botbuilder/dialogs/prompts/activity_prompt.py +++ b/libraries/botbuilder-dialogs/botbuilder/dialogs/prompts/activity_prompt.py @@ -19,7 +19,6 @@ from .prompt_recognizer_result import PromptRecognizerResult from .prompt_validator_context import PromptValidatorContext - class ActivityPrompt(Dialog, ABC): """ Waits for an activity to be received. From 7e72b0fe83e13d5e34c2e014a613a7c0b2a504a1 Mon Sep 17 00:00:00 2001 From: Emily Olshefski Date: Fri, 24 Jan 2020 14:24:42 -0800 Subject: [PATCH 3/4] Fixed formatting --- .../dialogs/prompts/activity_prompt.py | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/libraries/botbuilder-dialogs/botbuilder/dialogs/prompts/activity_prompt.py b/libraries/botbuilder-dialogs/botbuilder/dialogs/prompts/activity_prompt.py index 3a70d17cc..e849e47c0 100644 --- a/libraries/botbuilder-dialogs/botbuilder/dialogs/prompts/activity_prompt.py +++ b/libraries/botbuilder-dialogs/botbuilder/dialogs/prompts/activity_prompt.py @@ -23,14 +23,14 @@ class ActivityPrompt(Dialog, ABC): """ Waits for an activity to be received. - ..remarks: + .. remarks: This prompt requires a validator be passed in and is useful when waiting for non-message activities like an event to be received. The validator can ignore received events until the expected activity is received. - :var persisted_options: ? + :var persisted_options: :typevar persisted_options: str - :var persisted_state: ? + :var persisted_state: :vartype persisted_state: str """ @@ -153,17 +153,19 @@ async def resume_dialog( # pylint: disable=unused-argument ): """ Called when a prompt dialog resumes being the active dialog on the dialog stack, such as when the previous active dialog on the stack completes. - ..remarks: + + .. note: Prompts are typically leaf nodes on the stack but the dev is free to push other dialogs on top of the stack which will result in the prompt receiving an unexpected call to - resume_dialog() when the pushed on dialog ends. + :meth:resume_dialog() when the pushed on dialog ends. To avoid the prompt prematurely ending, we need to implement this method and - simply re-prompt the user. + simply re-prompt the user. + :param dialog_context: The dialog context for the current turn of the conversation :type dialog_context: :class:`DialogContext` :param reason: An enum indicating why the dialog resumed. :type reason: :class:`DialogReason` - :param result: >Optional, value returned from the previous dialog on the stack. The type of the value returned is dependent on the previous dialog. + :param result: Optional, value returned from the previous dialog on the stack. The type of the value returned is dependent on the previous dialog. :type result: object """ await self.reprompt_dialog(dialog_context.context, dialog_context.active_dialog) From 63ff9814ddd79fa9509a983c4b54b94a83cda142 Mon Sep 17 00:00:00 2001 From: Emily Olshefski Date: Fri, 24 Jan 2020 14:25:51 -0800 Subject: [PATCH 4/4] Update activity_prompt.py --- .../botbuilder/dialogs/prompts/activity_prompt.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/libraries/botbuilder-dialogs/botbuilder/dialogs/prompts/activity_prompt.py b/libraries/botbuilder-dialogs/botbuilder/dialogs/prompts/activity_prompt.py index e849e47c0..15f7f9cdc 100644 --- a/libraries/botbuilder-dialogs/botbuilder/dialogs/prompts/activity_prompt.py +++ b/libraries/botbuilder-dialogs/botbuilder/dialogs/prompts/activity_prompt.py @@ -152,7 +152,8 @@ async def resume_dialog( # pylint: disable=unused-argument self, dialog_context: DialogContext, reason: DialogReason, result: object = None ): """ - Called when a prompt dialog resumes being the active dialog on the dialog stack, such as when the previous active dialog on the stack completes. + Called when a prompt dialog resumes being the active dialog on the dialog stack, such + as when the previous active dialog on the stack completes. .. note: Prompts are typically leaf nodes on the stack but the dev is free to push other dialogs @@ -165,7 +166,7 @@ async def resume_dialog( # pylint: disable=unused-argument :type dialog_context: :class:`DialogContext` :param reason: An enum indicating why the dialog resumed. :type reason: :class:`DialogReason` - :param result: Optional, value returned from the previous dialog on the stack. The type of the value returned is dependent on the previous dialog. + :param result: Optional, value returned from the previous dialog on the stack. :type result: object """ await self.reprompt_dialog(dialog_context.context, dialog_context.active_dialog)