From 5956aae23576f0ec6c567ab0b627515f639fa57c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jannes=20H=C3=B6ke?= Date: Mon, 5 Mar 2018 12:17:56 +0100 Subject: [PATCH] Add missing docs utils (#912) * add documentation for telegram.utils.promise and .request * improve documentation for telegram.utils.promise and .request * add missing 's' to new_chat_member(s) in all docstrings * fix docs for `set_chat_photo` [CI skip] --- docs/source/telegram.rst | 2 +- docs/source/telegram.utils.promise.rst | 6 +++++ docs/source/telegram.utils.request.rst | 6 +++++ docs/source/telegram.utils.rst | 8 +++++++ telegram/bot.py | 2 +- telegram/utils/promise.py | 32 +++++++++++++++++++++++++- telegram/utils/request.py | 2 ++ 7 files changed, 55 insertions(+), 3 deletions(-) create mode 100644 docs/source/telegram.utils.promise.rst create mode 100644 docs/source/telegram.utils.request.rst create mode 100644 docs/source/telegram.utils.rst diff --git a/docs/source/telegram.rst b/docs/source/telegram.rst index 59441f2e5..2c2b4ecdf 100644 --- a/docs/source/telegram.rst +++ b/docs/source/telegram.rst @@ -3,8 +3,8 @@ telegram package .. toctree:: - telegram.utils.helpers telegram.ext + telegram.utils telegram.audio telegram.bot telegram.callbackquery diff --git a/docs/source/telegram.utils.promise.rst b/docs/source/telegram.utils.promise.rst new file mode 100644 index 000000000..09dec37df --- /dev/null +++ b/docs/source/telegram.utils.promise.rst @@ -0,0 +1,6 @@ +telegram.utils.promise.Promise +============================== + +.. autoclass:: telegram.utils.promise.Promise + :members: + :show-inheritance: diff --git a/docs/source/telegram.utils.request.rst b/docs/source/telegram.utils.request.rst new file mode 100644 index 000000000..8efebf2c3 --- /dev/null +++ b/docs/source/telegram.utils.request.rst @@ -0,0 +1,6 @@ +telegram.utils.request.Request +============================== + +.. autoclass:: telegram.utils.request.Request + :members: + :show-inheritance: diff --git a/docs/source/telegram.utils.rst b/docs/source/telegram.utils.rst new file mode 100644 index 000000000..a80347237 --- /dev/null +++ b/docs/source/telegram.utils.rst @@ -0,0 +1,8 @@ +telegram.utils package +====================== + +.. toctree:: + + telegram.utils.helpers + telegram.utils.promise + telegram.utils.request diff --git a/telegram/bot.py b/telegram/bot.py index 4aac1d138..a940e686d 100644 --- a/telegram/bot.py +++ b/telegram/bot.py @@ -2639,7 +2639,7 @@ class Bot(TelegramObject): Args: chat_id (:obj:`int` | :obj:`str`): Unique identifier for the target chat or username of the target`channel (in the format @channelusername). - photo (`telegram.InputFile`): New chat photo. + photo (`filelike object`): New chat photo. timeout (:obj:`int` | :obj:`float`, optional): If this value is specified, use it as the read timeout from the server (instead of the one specified during creation of the connection pool). diff --git a/telegram/utils/promise.py b/telegram/utils/promise.py index 06bad2101..4e3ebf934 100644 --- a/telegram/utils/promise.py +++ b/telegram/utils/promise.py @@ -27,7 +27,20 @@ logger.addHandler(logging.NullHandler()) class Promise(object): - """A simple Promise implementation for the run_async decorator.""" + """A simple Promise implementation for use with the run_async decorator, DelayQueue etc. + + Args: + pooled_function (:obj:`callable`): The callable that will be called concurrently. + args (:obj:`list` | :obj:`tuple`): Positional arguments for :attr:`pooled_function`. + kwargs (:obj:`dict`): Keyword arguments for :attr:`pooled_function`. + + Attributes: + pooled_function (:obj:`callable`): The callable that will be called concurrently. + args (:obj:`list` | :obj:`tuple`): Positional arguments for :attr:`pooled_function`. + kwargs (:obj:`dict`): Keyword arguments for :attr:`pooled_function`. + done (:obj:`threading.Event`): Is set when the result is available. + + """ def __init__(self, pooled_function, args, kwargs): self.pooled_function = pooled_function @@ -38,6 +51,8 @@ class Promise(object): self._exception = None def run(self): + """Calls the :attr:`pooled_function` callable.""" + try: self._result = self.pooled_function(*self.args, **self.kwargs) @@ -52,6 +67,19 @@ class Promise(object): self.run() def result(self, timeout=None): + """Return the result of the ``Promise``. + + Args: + timeout (:obj:`float`, optional): Maximum time in seconds to wait for the result to be + calculated. ``None`` means indefinite. Default is ``None``. + + Returns: + Returns the return value of :attr:`pooled_function` or ``None`` if the ``timeout`` + expires. + + Raises: + Any exception raised by :attr:`pooled_function`. + """ self.done.wait(timeout=timeout) if self._exception is not None: raise self._exception # pylint: disable=raising-bad-type @@ -59,4 +87,6 @@ class Promise(object): @property def exception(self): + """The exception raised by :attr:`pooled_function` or ``None`` if no exception has been + raised (yet).""" return self._exception diff --git a/telegram/utils/request.py b/telegram/utils/request.py index 7c374c312..3d65b7357 100644 --- a/telegram/utils/request.py +++ b/telegram/utils/request.py @@ -242,6 +242,7 @@ class Request(object): def post(self, url, data, timeout=None): """Request an URL. + Args: url (:obj:`str`): The web location we want to retrieve. data (dict[str, str|int]): A dict of key/value pairs. Note: On py2.7 value is unicode. @@ -291,6 +292,7 @@ class Request(object): def download(self, url, filename, timeout=None): """Download a file by its URL. + Args: url (str): The web location we want to retrieve. timeout (:obj:`int` | :obj:`float`): If this value is specified, use it as the read