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

@@ -3,8 +3,8 @@ telegram package
 
 .. toctree::
 
-   telegram.utils.helpers
    telegram.ext
+   telegram.utils
    telegram.audio
    telegram.bot
    telegram.callbackquery

docs/source/telegram.utils.promise.rst

@@ -0,0 +1,6 @@
+telegram.utils.promise.Promise
+==============================
+
+.. autoclass:: telegram.utils.promise.Promise
+    :members:
+    :show-inheritance:

docs/source/telegram.utils.request.rst

@@ -0,0 +1,6 @@
+telegram.utils.request.Request
+==============================
+
+.. autoclass:: telegram.utils.request.Request
+    :members:
+    :show-inheritance:

docs/source/telegram.utils.rst

@@ -0,0 +1,8 @@
+telegram.utils package
+======================
+
+.. toctree::
+
+    telegram.utils.helpers
+    telegram.utils.promise
+    telegram.utils.request

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).

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

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