telegram.request.BaseRequest

class telegram.request.BaseRequest[source]

Bases: 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()

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.

New in version 20.0.

DEFAULT_NONE = None[source]

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 v20.0a1 (https://python-telegram-bot.org)'[source]

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

Type

str

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

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()[source]

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

static parse_json_payload(payload)[source]

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

async post(url, request_data=None, read_timeout=None, write_timeout=None, connect_timeout=None, pool_timeout=None)[source]

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.

Return type

Dict[str, …]

async retrieve(url, read_timeout=None, write_timeout=None, connect_timeout=None, pool_timeout=None)[source]

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()[source]

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