From ca04daf7822209f5f5bc86e12880b1e50c1ef994 Mon Sep 17 00:00:00 2001 From: Bibo-Joshi Date: Sun, 29 Nov 2020 16:25:47 +0100 Subject: [PATCH] Doc Fixes & Extensions (#2201) * Add note on dispatcherhandlerstop to conversationhandler * Fine tune @run_async deprecation warning * Refine docs of JobQueue.jobs/get_jobs_by_name --- telegram/ext/conversationhandler.py | 2 ++ telegram/ext/dispatcher.py | 4 ++-- telegram/ext/jobqueue.py | 7 +++++-- 3 files changed, 9 insertions(+), 4 deletions(-) diff --git a/telegram/ext/conversationhandler.py b/telegram/ext/conversationhandler.py index e0c309f17..8f1ddce0d 100644 --- a/telegram/ext/conversationhandler.py +++ b/telegram/ext/conversationhandler.py @@ -84,6 +84,8 @@ class ConversationHandler(Handler): 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.DispatcherHandlerStop` can be used in conversations as described + in the corresponding documentation. Note: In each of the described collections of handlers, a handler may in turn be a diff --git a/telegram/ext/dispatcher.py b/telegram/ext/dispatcher.py index 95af35233..2dc74e8de 100644 --- a/telegram/ext/dispatcher.py +++ b/telegram/ext/dispatcher.py @@ -67,8 +67,8 @@ def run_async( @wraps(func) def async_func(*args: Any, **kwargs: Any) -> Any: warnings.warn( - 'The @run_async decorator is deprecated. Use the `run_async` parameter of' - '`Dispatcher.add_handler` or `Dispatcher.run_async` instead.', + 'The @run_async decorator is deprecated. Use the `run_async` parameter of ' + 'your Handler or `Dispatcher.run_async` instead.', TelegramDeprecationWarning, stacklevel=2, ) diff --git a/telegram/ext/jobqueue.py b/telegram/ext/jobqueue.py index 61e889e7c..10e1f7548 100644 --- a/telegram/ext/jobqueue.py +++ b/telegram/ext/jobqueue.py @@ -498,11 +498,14 @@ class JobQueue: self.scheduler.shutdown() def jobs(self) -> Tuple['Job', ...]: - """Returns a tuple of all jobs that are currently in the ``JobQueue``.""" + """ + Returns a tuple of all *pending/scheduled* jobs that are currently in the ``JobQueue``. + """ return tuple(Job.from_aps_job(job, self) for job in self.scheduler.get_jobs()) def get_jobs_by_name(self, name: str) -> Tuple['Job', ...]: - """Returns a tuple of jobs with the given name that are currently in the ``JobQueue``""" + """Returns a tuple of all *pending/scheduled* jobs with the given name that are currently + in the ``JobQueue``""" return tuple(job for job in self.jobs() if job.name == name)