Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# BaseRequest

class telegram.request.BaseRequest

  Bases: `contextlib.AbstractAsyncContextManager`, `ABC`

  Abstract interface class that allows python-telegram-bot to make requests to the Bot API. Can be implemented via different asyncio HTTP libraries. An implementation of this class must implement all abstract methods and properties.

  Instances of this class can be used as asyncio context managers, where

      async with request_object:
          # code

  is roughly equivalent to

      try:
          await request_object.initialize()
          # code
      finally:
          await request_object.shutdown()

  Use In

  - `telegram.ext.ApplicationBuilder.get_updates_request()`

  - `telegram.ext.ApplicationBuilder.request()`

  See also

  `__aenter__()` and `__aexit__()`.

  Tip

  JSON encoding and decoding is done with the standard library’s `json` by default. To use a custom library for this, you can override `parse_json_payload()` and implement custom logic to encode the keys of `telegram.request.RequestData.parameters`.

  See also

  Architecture Overview, Builder Pattern

  Added in version 20.0.

  DEFAULT_NONE = None

    A special object that indicates that an argument of a function was not explicitly passed. Used for the timeout parameters of `post()` and `do_request()`.

    Example

    When calling `request.post(url)`, `request` should use the default timeouts set on initialization. When calling `request.post(url, connect_timeout=5, read_timeout=None)`, `request` should use `5` for the connect timeout and `None` for the read timeout.

    Use `if parameter is (not) BaseRequest.DEFAULT_NONE:` to check if the parameter was set.

    Type:

      `object`

  USER_AGENT = 'python-telegram-bot v21.10 (https://python-telegram-bot.org)'

    A description that can be used as user agent for requests made to the Bot API.

    Type:

      `str`

  async __aenter__()

    Asynchronous context manager which `initializes` the Request.

    Returns:

      The initialized Request instance.

    Raises:

      Exception – If an exception is raised during initialization, `shutdown()` is called in this case.

  async __aexit__(exc_type, exc_val, exc_tb)

    Asynchronous context manager which `shuts down` the Request.

  abstract async do_request(url, method, request_data=None, read_timeout=None, write_timeout=None, connect_timeout=None, pool_timeout=None)

    Makes a request to the Bot API. Must be implemented by a subclass.

    Warning

    This method will be called by `post()` and `retrieve()`. It should not be called manually.

    Parameters:

      - url (`str`) – The URL to request.

      - method (`str`) – HTTP method (i.e. `'POST'`, `'GET'`, etc.).

      - request_data (`telegram.request.RequestData`, optional) – An object containing information about parameters and files to upload for the request.

      - read_timeout (`float` | `None`, optional) – If passed, specifies the maximum amount of time (in seconds) to wait for a response from Telegram’s server instead of the time specified during creating of this object. Defaults to `DEFAULT_NONE`.

      - write_timeout (`float` | `None`, optional) – If passed, specifies the maximum amount of time (in seconds) to wait for a write operation to complete (in terms of a network socket; i.e. POSTing a request or uploading a file) instead of the time specified during creating of this object. Defaults to `DEFAULT_NONE`.

      - connect_timeout (`float` | `None`, optional) – If passed, specifies the maximum amount of time (in seconds) to wait for a connection attempt to a server to succeed instead of the time specified during creating of this object. Defaults to `DEFAULT_NONE`.

      - pool_timeout (`float` | `None`, optional) – If passed, specifies the maximum amount of time (in seconds) to wait for a connection to become available instead of the time specified during creating of this object. Defaults to `DEFAULT_NONE`.

    Returns:

      The HTTP return code & the payload part of the server response.

    Return type:

      tuple[`int`, `bytes`]

  abstract async initialize()

    Initialize resources used by this class. Must be implemented by a subclass.

  static parse_json_payload(payload)

    Parse the JSON returned from Telegram.

    Tip

    By default, this method uses the standard library’s `json.loads()` and `errors="replace"` in `bytes.decode()`. You can override it to customize either of these behaviors.

    Parameters:

      payload (`bytes`) – The UTF-8 encoded JSON payload as returned by Telegram.

    Returns:

      A JSON parsed as Python dict with results.

    Return type:

      dict

    Raises:

      TelegramError – If loading the JSON data failed

  final async post(url, request_data=None, read_timeout=None, write_timeout=None, connect_timeout=None, pool_timeout=None)

    Makes a request to the Bot API handles the return code and parses the answer.

    Warning

    This method will be called by the methods of `telegram.Bot` and should not be called manually.

    Parameters:

      - url (`str`) – The URL to request.

      - request_data (`telegram.request.RequestData`, optional) – An object containing information about parameters and files to upload for the request.

      - read_timeout (`float` | `None`, optional) – If passed, specifies the maximum amount of time (in seconds) to wait for a response from Telegram’s server instead of the time specified during creating of this object. Defaults to `DEFAULT_NONE`.

      - write_timeout (`float` | `None`, optional) – If passed, specifies the maximum amount of time (in seconds) to wait for a write operation to complete (in terms of a network socket; i.e. POSTing a request or uploading a file) instead of the time specified during creating of this object. Defaults to `DEFAULT_NONE`.

      - connect_timeout (`float` | `None`, optional) – If passed, specifies the maximum amount of time (in seconds) to wait for a connection attempt to a server to succeed instead of the time specified during creating of this object. Defaults to `DEFAULT_NONE`.

      - pool_timeout (`float` | `None`, optional) – If passed, specifies the maximum amount of time (in seconds) to wait for a connection to become available instead of the time specified during creating of this object. Defaults to `DEFAULT_NONE`.

    Returns:

      The JSON response of the Bot API.

  property read_timeout

    This property must return the default read timeout in seconds used by this class. More precisely, the returned value should be the one used when `post.read_timeout` of :meth:post` is not passed/equal to `DEFAULT_NONE`.

    Added in version 20.7.

    Warning

    For now this property does not need to be implemented by subclasses and will raise `NotImplementedError` if accessed without being overridden. However, in future versions, this property will be abstract and must be implemented by subclasses.

    Returns:

      The read timeout in seconds.

    Return type:

      `float` | `None`

  final async retrieve(url, read_timeout=None, write_timeout=None, connect_timeout=None, pool_timeout=None)

    Retrieve the contents of a file by its URL.

    Warning

    This method will be called by the methods of `telegram.Bot` and should not be called manually.

    Parameters:

      - url (`str`) – The web location we want to retrieve.

      - read_timeout (`float` | `None`, optional) – If passed, specifies the maximum amount of time (in seconds) to wait for a response from Telegram’s server instead of the time specified during creating of this object. Defaults to `DEFAULT_NONE`.

      - write_timeout (`float` | `None`, optional) – If passed, specifies the maximum amount of time (in seconds) to wait for a write operation to complete (in terms of a network socket; i.e. POSTing a request or uploading a file) instead of the time specified during creating of this object. Defaults to `DEFAULT_NONE`.

      - connect_timeout (`float` | `None`, optional) – If passed, specifies the maximum amount of time (in seconds) to wait for a connection attempt to a server to succeed instead of the time specified during creating of this object. Defaults to `DEFAULT_NONE`.

      - pool_timeout (`float` | `None`, optional) – If passed, specifies the maximum amount of time (in seconds) to wait for a connection to become available instead of the time specified during creating of this object. Defaults to `DEFAULT_NONE`.

    Returns:

      The files contents.

    Return type:

      `bytes`

  abstract async shutdown()

    Stop & clear resources used by this class. Must be implemented by a subclass.