U g@sdZddlZddlZddlmZddlmZmZmZm Z m Z m Z m Z m Z mZmZmZmZddlmZddlmZmZddlmZddlmZdd lmZdd lmZdd lm Z dd l!m"Z"dd l#m$Z$ddl%m&Z&ddl'm(Z(ddl)m*Z*ddl+m,Z,ddl-m.Z.ddl/m0Z0ddl1m2Z2ddl3m4Z4m5Z5m6Z6erJddl7m8Z8m9Z9m:Z:ee;e6e$ee4e;fe;fZeGddde e4Z?eGdddZ@Gddde$ee4e;fZAdS)z-This module contains the ConversationHandler.N) dataclass) TYPE_CHECKINGAnyDictFinalGenericListNoReturnOptionalSetTupleUnioncast)Update) DEFAULT_TRUE DefaultValue) get_logger)build_repr_with_selected_attrs)DVType)warn)ApplicationHandlerStop)ExtBot) BaseHandler)CallbackQueryHandler)ChosenInlineResultHandler)InlineQueryHandler)StringCommandHandler)StringRegexHandler) TypeHandler) TrackingDict)CCTConversationDictConversationKey) ApplicationJobJobQueueConversationHandler) class_namec@s6eZdZUdZdZeed<eed<ded<eed<dS) _ConversationTimeoutContextzUsed as a datastore for conversation timeouts. Passed in the :paramref:`JobQueue.run_once.data` parameter. See :meth:`_trigger_timeout`. ) applicationcallback_contextconversation_keyupdater+r,.Application[Any, CCT, Any, Any, Any, JobQueue]r)r*N) __name__ __module__ __qualname____doc__ __slots__r"__annotations__rr r4r4N/tmp/pip-unpacked-wheel-swnnwir2/telegram/ext/_handlers/conversationhandler.pyr(?s r(c@sDeZdZUdZdZejed<eed<e dddZ eddd Z d S) PendingStatea Thin wrapper around :class:`asyncio.Task` to handle block=False handlers. Note that this is a public class of this module, since :meth:`Application.update_persistence` needs to access it. It's still hidden from users, since this module itself is private.  old_statetaskr9r8returncCs |jSN)r9doneselfr4r4r5r=YszPendingState.donecCsj|jstd|j}|r4td|j|jS|j}|dkrX|jdkrXtj}n|dkrf|jS|S)aReturns the new state of the :class:`ConversationHandler` if available. If there was an exception during the task execution, then return the old state. If both the new and old state are :obj:`None`, return `CH.END`. If only the new state is :obj:`None`, return the old state. Raises: :exc:`RuntimeError`: If the current task has not yet finished. zNew state is not yet availablezd?Z0ed`, :class:`ConversationHandler` uses :attr:`update.callback_query.message.message_id ` when :attr:`per_chat=True ` and :attr:`update.callback_query.inline_message_id <.CallbackQuery.inline_message_id>` when :attr:`per_chat=False `. For a more detailed explanation, please see our `FAQ`_. Finally, :class:`ConversationHandler`, does *not* handle (edited) channel posts. .. _`FAQ`: https://github.com/python-telegram-bot/python-telegram-bot/wiki /Frequently-Asked-Questions#what-do-the-per_-settings-in-conversation handler-do The first collection, a :obj:`list` named :attr:`entry_points`, is used to initiate the conversation, for example with a :class:`telegram.ext.CommandHandler` or :class:`telegram.ext.MessageHandler`. The second collection, a :obj:`dict` named :attr:`states`, contains the different conversation steps and one or more associated handlers that should be used if the user sends a message when the conversation with them is currently in that state. Here you can also define a state for :attr:`TIMEOUT` to define the behavior when :attr:`conversation_timeout` is exceeded, and a state for :attr:`WAITING` to define behavior when a new update is received while the previous :attr:`block=False ` handler is not finished. The third collection, a :obj:`list` named :attr:`fallbacks`, is used if the user is currently in a conversation but the state has either no associated handler or the handler that is associated to the state is inappropriate for the update, for example if the update contains a command, but a regular text message is expected. You could use this for a ``/cancel`` command or to let the user know their message was not recognized. To change the state of conversation, the callback function of a handler must return the new state after responding to the user. If it does not return anything (returning :obj:`None` by default), the state will not change. If an entry point callback function returns :obj:`None`, the conversation ends immediately after the execution of this callback function. To end the conversation, the callback function must return :attr:`END` or ``-1``. To handle the conversation timeout, use handler :attr:`TIMEOUT` or ``-2``. Finally, :class:`telegram.ext.ApplicationHandlerStop` can be used in conversations as described in its documentation. Note: In each of the described collections of handlers, a handler may in turn be a :class:`ConversationHandler`. In that case, the child :class:`ConversationHandler` should have the attribute :attr:`map_to_parent` which allows returning to the parent conversation at specified states within the child conversation. Note that the keys in :attr:`map_to_parent` must not appear as keys in :attr:`states` attribute or else the latter will be ignored. You may map :attr:`END` to one of the parents states to continue the parent conversation after the child conversation has ended or even map a state to :attr:`END` to end the *parent* conversation from within the child conversation. For an example on nested :class:`ConversationHandler` s, see :any:`examples.nestedconversationbot`. Examples: * :any:`Conversation Bot ` * :any:`Conversation Bot 2 ` * :any:`Nested Conversation Bot ` * :any:`Persistent Conversation Bot ` Args: entry_points (List[:class:`telegram.ext.BaseHandler`]): A list of :obj:`BaseHandler` objects that can trigger the start of the conversation. The first handler whose :meth:`check_update` method returns :obj:`True` will be used. If all return :obj:`False`, the update is not handled. states (Dict[:obj:`object`, List[:class:`telegram.ext.BaseHandler`]]): A :obj:`dict` that defines the different states of conversation a user can be in and one or more associated :obj:`BaseHandler` objects that should be used in that state. The first handler whose :meth:`check_update` method returns :obj:`True` will be used. fallbacks (List[:class:`telegram.ext.BaseHandler`]): A list of handlers that might be used if the user is in a conversation, but every handler for their current state returned :obj:`False` on :meth:`check_update`. The first handler which :meth:`check_update` method returns :obj:`True` will be used. If all return :obj:`False`, the update is not handled. allow_reentry (:obj:`bool`, optional): If set to :obj:`True`, a user that is currently in a conversation can restart the conversation by triggering one of the entry points. Default is :obj:`False`. per_chat (:obj:`bool`, optional): If the conversation key should contain the Chat's ID. Default is :obj:`True`. per_user (:obj:`bool`, optional): If the conversation key should contain the User's ID. Default is :obj:`True`. per_message (:obj:`bool`, optional): If the conversation key should contain the Message's ID. Default is :obj:`False`. conversation_timeout (:obj:`float` | :obj:`datetime.timedelta`, optional): When this handler is inactive more than this timeout (in seconds), it will be automatically ended. If this value is ``0`` or :obj:`None` (default), there will be no timeout. The last received update and the corresponding :class:`context <.CallbackContext>` will be handled by *ALL* the handler's whose :meth:`check_update` method returns :obj:`True` that are in the state :attr:`ConversationHandler.TIMEOUT`. Caution: * This feature relies on the :attr:`telegram.ext.Application.job_queue` being set and hence requires that the dependencies that :class:`telegram.ext.JobQueue` relies on are installed. * Using :paramref:`conversation_timeout` with nested conversations is currently not supported. You can still try to use it, but it will likely behave differently from what you expect. name (:obj:`str`, optional): The name for this conversation handler. Required for persistence. persistent (:obj:`bool`, optional): If the conversation's dict for this handler should be saved. :paramref:`name` is required and persistence has to be set in :attr:`Application <.Application.persistence>`. .. versionchanged:: 20.0 Was previously named as ``persistence``. map_to_parent (Dict[:obj:`object`, :obj:`object`], optional): A :obj:`dict` that can be used to instruct a child conversation handler to transition into a mapped state on its parent conversation handler in place of a specified nested state. block (:obj:`bool`, optional): Pass :obj:`False` or :obj:`True` to set a default value for the :attr:`BaseHandler.block` setting of all handlers (in :attr:`entry_points`, :attr:`states` and :attr:`fallbacks`). The resolution order for checking if a handler should be run non-blocking is: 1. :attr:`telegram.ext.BaseHandler.block` (if set) 2. the value passed to this parameter (if any) 3. :attr:`telegram.ext.Defaults.block` (if defaults are used) .. seealso:: :wiki:`Concurrency` .. versionchanged:: 20.0 No longer overrides the handlers settings. Resolution order was changed. Raises: :exc:`ValueError`: If :paramref:`persistent` is used but :paramref:`name` was not set, or when :attr:`per_message`, :attr:`per_chat`, :attr:`per_user` are all :obj:`False`. Attributes: block (:obj:`bool`): Determines whether the callback will run in a blocking way. Always :obj:`True` since conversation handlers handle any non-blocking callbacks internally. )_allow_reentry_block_child_conversations_conversation_timeout_conversations _entry_points _fallbacks_map_to_parent_name _per_chat _per_message _per_user _persistent_states_timeout_jobs_lock timeout_jobsrDTIMEOUTWAITINGFTNzConversationHandler[CCT]) r? entry_pointsstates fallbacks allow_reentryper_chatper_user per_messageconversation_timeoutname persistent map_to_parentblockc CsJddlm} m}m}m}d|_| |_||_||_||_ ||_ ||_ ||_ ||_ ||_| |_| |_i|_t|_i|_t|_| r|jstd| |_t|j|j|jfstd|jr|jstdddg}| || ||!D]}| |q|j"d d |Dd }|D]*}t#|t$t%frHtd |j&j'd ddnt#|t(r|t)|j*t+s|td|j*j'dddnt#||rtdddn|jrt#||t,t-|| frtd|j&j'd|ddnN|jrt#|t.std|ddn&|js t#|t.r td|dd|j/rt#||j&rtdddqdS)Nr)PollAnswerHandler PollHandlerPreCheckoutQueryHandlerShippingQueryHandlerTz:Conversations can't be persistent when handler is unnamed.z='per_user', 'per_chat' and 'per_message' can't all be 'False'znIf 'per_message=True' is used, 'per_chat=True' should also be used, since message IDs are not globally unique. stacklevelcss|]}t|tr|VqdSr<) isinstancer&).0handlerr4r4r5 qs z/ConversationHandler.__init__..z Read this FAQ entry to learn more about the per_* settings: https://github.com/python-telegram-bot/python-telegram-bot/wiki/Frequently-Asked-Questions#what-do-the-per_-settings-in-conversationhandler-do.zJThe `ConversationHandler` only handles updates of type `telegram.Update`. z handles updates of type `str`.zkThe `ConversationHandler` only handles updates of type `telegram.Update`. The TypeHandler is set to handle .zPollHandler will never trigger in a conversation since it has no information about the chat or the user who voted in it. Do you mean the `PollAnswerHandler`?zUpdates handled by zb only have information about the user, so this handler won't ever be triggered if `per_chat=True`.zIf 'per_message=True', all entry points, state handlers, and fallbacks must be 'CallbackQueryHandler', since no other handlers have a message context.zUIf 'per_message=False', 'CallbackQueryHandler' will not be tracked for every message.zUsing `conversation_timeout` with nested conversations is currently not supported. You can still try to use it, but it will likely behave differently from what you expect.)0 telegram.extrmrnrorprlrMrQrYrRrLrWrUrVrOrTrSr[rHLockrZrPsetrNri ValueErrorrXanyrfrergrextendvaluesr,rtrr __class__r.r issubclasstyperrrrrh)r?rarbrcrdrerfrgrhrirjrkrlrmrnrorpZ all_handlersZstate_handlersZ per_faq_linkrvr4r4r5__init__*s            zConversationHandler.__init__r:cCsTd}tt|jd|}t|}t|j|krD|ddd}t||j|dS)aGive a string representation of the ConversationHandler in the form ``ConversationHandler[name=..., states={...}]``. If there are more than 3 states, only the first 3 states are listed. As this class doesn't implement :meth:`object.__str__`, the default implementation will be used, which is equivalent to :meth:`__repr__`. Returns: :obj:`str` Nr\z, ...})rirb)dictlistrbitemsstrlenrri)r?Ztruncation_thresholdrbZ states_stringr4r4r5__repr__s zConversationHandler.__repr__cCs|jS)zList[:class:`telegram.ext.BaseHandler`]: A list of :obj:`BaseHandler` objects that can trigger the start of the conversation. )rQr>r4r4r5rasz ConversationHandler.entry_points)_r;cCs tddS)NzDYou can not assign a new value to entry_points after initialization.AttributeErrorr?rr4r4r5rascCs|jS)aDict[:obj:`object`, List[:class:`telegram.ext.BaseHandler`]]: A :obj:`dict` that defines the different states of conversation a user can be in and one or more associated :obj:`BaseHandler` objects that should be used in that state. )rYr>r4r4r5rbszConversationHandler.statescCs tddS)Nz>You can not assign a new value to states after initialization.rrr4r4r5rbscCs|jS)zList[:class:`telegram.ext.BaseHandler`]: A list of handlers that might be used if the user is in a conversation, but every handler for their current state returned :obj:`False` on :meth:`check_update`. )rRr>r4r4r5rcszConversationHandler.fallbackscCs tddS)NzAYou can not assign a new value to fallbacks after initialization.rrr4r4r5rcscCs|jS)zQ:obj:`bool`: Determines if a user can restart a conversation with an entry point.)rLr>r4r4r5rdsz!ConversationHandler.allow_reentrycCs tddS)NzEYou can not assign a new value to allow_reentry after initialization.rrr4r4r5rdscCs|jS)zB:obj:`bool`: If the conversation key should contain the User's ID.)rWr>r4r4r5rfszConversationHandler.per_usercCs tddS)Nz@You can not assign a new value to per_user after initialization.rrr4r4r5rf scCs|jS)zB:obj:`bool`: If the conversation key should contain the Chat's ID.)rUr>r4r4r5re szConversationHandler.per_chatcCs tddS)Nz@You can not assign a new value to per_chat after initialization.rrr4r4r5rescCs|jS)zE:obj:`bool`: If the conversation key should contain the message's ID.)rVr>r4r4r5rgszConversationHandler.per_messagecCs tddS)NzCYou can not assign a new value to per_message after initialization.rrr4r4r5rgscCs|jS)z:obj:`float` | :obj:`datetime.timedelta`: Optional. When this handler is inactive more than this timeout (in seconds), it will be automatically ended. )rOr>r4r4r5rhsz(ConversationHandler.conversation_timeoutcCs tddS)NzLYou can not assign a new value to conversation_timeout after initialization.rrr4r4r5rh)scCs|jS)zE:obj:`str`: Optional. The name for this :class:`ConversationHandler`.)rTr>r4r4r5ri/szConversationHandler.namecCs tddS)Nz`. )rXr>r4r4r5rj8szConversationHandler.persistentcCs tddS)NzBYou can not assign a new value to persistent after initialization.rrr4r4r5rj@scCs|jS)a Dict[:obj:`object`, :obj:`object`]: Optional. A :obj:`dict` that can be used to instruct a nested :class:`ConversationHandler` to transition into a mapped state on its parent :class:`ConversationHandler` in place of a specified nested state. )rSr>r4r4r5rkDsz!ConversationHandler.map_to_parentcCs tddS)NzEYou can not assign a new value to map_to_parent after initialization.rrr4r4r5rkLsr#)r)r;cs|jr|jr|jstd|j}ttttft|_|j ||j |jIdH}|j || D]"\}}||j krj|j|j |dqj|j|ji}|jD]}| |j|dIdHq|S)aInitializes the persistence for this handler and its child conversations. While this method is marked as protected, we expect it to be called by the Application/parent conversations. It's just protected to hide it from users. Args: application (:class:`telegram.ext.Application`): The application. Returns: A dict {conversation.name -> TrackingDict}, which contains all dict of this conversation and possible child conversations. zRThis handler is not persistent, has no name or the application has no persistence!N) new_statekey)r))rjriZ persistencer@rPrrr"rJr,Zget_conversationsZupdate_no_trackrrD _update_staterN_initialize_persistence)r?r)Zcurrent_conversationsZ stored_datarstateoutrvr4r4r5rRs.       z+ConversationHandler._initialize_persistence)r,r;cCs|j}|j}g}|jr2|dkr&td||j|jrT|dkrHtd||j|jr|jdkrltd|jj r||jj n||jj j t |S)z7Builds the conversation key associated with the update.Nz2Can't build key for update without effective chat!z2Can't build key for update without effective user!z1Can't build key for update without CallbackQuery!) effective_chateffective_userrer@appendidrfrgcallback_queryZinline_message_idmessageZ message_idtuple)r?r,Zchatuserrr4r4r5_get_keys$   zConversationHandler._get_keyr-)rr)r,contextr+r;c sZz|IdH}Wn6tk rD}ztjd|dWYdSd}~XYnX|j|||||dS)NzTNon-blocking handler callback raised exception. Not scheduling conversation timeout.exc_info)rr)r,rr+) ExceptionrBdebug _schedule_job)r?rr)r,rr+Zeffective_new_staterEr4r4r5_schedule_job_delayedsz)ConversationHandler._schedule_job_delayedc Csr||jkrdSz.|j}|j|j|jt||||d|j|<Wn0tk rl}ztj d|dW5d}~XYnXdS)zRSchedules a job which executes :meth:`_trigger_timeout` upon conversation timeout.N)datazFailed to schedule timeout.r) rD job_queueZrun_once_trigger_timeoutrhr(r[rrBrA)r?rr)r,rr+Zj_queuerEr4r4r5rs  z!ConversationHandler._schedule_jobc Cs:t|tsdS|js|jrdS|jr.|js.dS|jr>|js>dS|jrN|j sNdS|j rf|jrf|j j sfdS| |}|j |}d}t|tr2td|r|}|jdkr|jr|j |dd}n||||j |}nJ|j |jg}|D]0}||}|dk r|dk r|j|||fSqdStdt|t|d}|dks^|jr|jD].} | |}|dk rd|dk rd| }qqd|dkrdS|dk r.|dkr.|j |gD].} | |}|dk r|dk r| }q.q|jD].} | |}|dk r|dk r| }q.qdS||||fS)a( Determines whether an update should be handled by this conversation handler, and if so in which state the conversation currently is. Args: update (:class:`telegram.Update` | :obj:`object`): Incoming update. Returns: :obj:`bool` Nz&Waiting for asyncio Task to finish ...Fz'Selecting conversation %s with state %s)rtrZ channel_postZedited_channel_postrerrfrrgrrrrPgetr6rBrr=rGr8r9rApoprrbr` check_updaterrdrarc) r?r,rrcheckrFhandlersZhandler_rvZ entry_point candidatefallbackr4r4r5rsj                    z ConversationHandler.check_updatez)Application[Any, CCT, Any, Any, Any, Any])r,r) check_resultrr;c s2|\}}}}d} |j4IdH$|j|d} | dk r>| W5QIdHRX|jtk r`|j} nB|jtk rr|j} n0t|jt r|jj dk r|jj j} n t |j} zF| r| ||||IdH} n&|j| |||||d|jdd} Wn.tk r} z| j} d} W5d} ~ XYnX|j4IdH|jr|jdkrJtddd nd|jjjsdtd dd nJt| tjr|j|| |||||d|jd d n|| ||||W5QIdHRXt|jtr | |jkr ||j||| rt|j| |j| S||j kr$|| ||| r.tdS) aLSend the update to the callback for the current state and BaseHandler Args: check_result: The result from :meth:`check_update`. For this handler it's a tuple of the conversation state, key, handler, and the handler's check result. update (:class:`telegram.Update`): Incoming telegram update. application (:class:`telegram.ext.Application`): Application that originated the update. context (:class:`telegram.ext.CallbackContext`): The context as provided by the application. FNzConversationHandler:z:handle_update:non_blocking_cb) coroutiner,riTzHIgnoring `conversation_timeout` because the Application has no JobQueue.rrzQIgnoring `conversation_timeout` because the Applications JobQueue is not running.z:handle_update:timeout_job)r,ri)!rZr[rZschedule_removalrlrrMrtZbotrdefaultsr get_value handle_updateZ create_taskZ update_idrrrhrrZ schedulerZrunningrHrIrrrkrrrDrr`)r?r,r)rrZ current_stater+rvZhandler_check_resultZraise_dp_handler_stopZ timeout_jobrlrrAr4r4r5r-s          "  z!ConversationHandler.handle_update)rrrvr;cCs||jkr||jkr|j|=nt|tjrFt|j||d|j|<nb|dk r||jkrt|dk rnt |j j ndd|d|j dk rd|j ndddd ||j|<dS) Nr7rz returned state z, which is unknown to the ConversationHandler rxrqrr) rDrPrtrHrIr6rrbrreprcallbackr.ri)r?rrrvr4r4r5rs      <z!ConversationHandler._update_state)rr;c s td|j}tt|j}td|j|j}|j4IdH:|j |j}||k rfW5QIdHRdS|j |j=W5QIdHRX|j |j g}|D]`}| |j}|dk r|dk rz||j|j||IdHWqtk rtdddYqXq||j|jdS)zThis is run whenever a conversation has timed out. Also makes sure that all handlers which are in the :attr:`TIMEOUT` state and whose :meth:`BaseHandler.check_update` returns :obj:`True` is handled. r$z7Conversation timeout was triggered for conversation %s!NFzWApplicationHandlerStop in TIMEOUT state of ConversationHandler has no effect. Ignoring.rqrr)rjobr(rrBrr+r*rZr[rrbr^rr,rr)rrrrD) r?rrZctxtr*Z found_jobrrvrr4r4r5rs:   z$ConversationHandler._trigger_timeout)N)7r.r/r0r1r2rDrintr3r^r`rrrrr rJrrKr r floatdatetime timedeltarrrrpropertyrasetterr rbrcrdrfrergrhrirjrkrr"rrrHrIrr_CheckUpdateTyperrrrr4r4r4r5r&zs   &  4  ] e )Br1rHrZ dataclassesrtypingrrrrrrr r r r r rZtelegramrZtelegram._utils.defaultvaluerrZtelegram._utils.loggingrZtelegram._utils.reprrZtelegram._utils.typesrZtelegram._utils.warningsrZtelegram.ext._applicationrZtelegram.ext._extbotrZ"telegram.ext._handlers.basehandlerrZ+telegram.ext._handlers.callbackqueryhandlerrZ0telegram.ext._handlers.choseninlineresulthandlerrZ)telegram.ext._handlers.inlinequeryhandlerrZ+telegram.ext._handlers.stringcommandhandlerrZ)telegram.ext._handlers.stringregexhandlerrZ"telegram.ext._handlers.typehandlerrZ telegram.ext._utils.trackingdictrZtelegram.ext._utils.typesr r!r"ryr#r$r%rJrr.rBr(r6r&r4r4r4r5s< 8                 ,