telegram.utils.helpers Module

This module contains helper functions.

telegram.utils.helpers.DEFAULT_20 = 20

Default 20

Type:

DefaultValue

telegram.utils.helpers.DEFAULT_FALSE = False

Default False

Type:

DefaultValue

telegram.utils.helpers.DEFAULT_NONE = None

Default None

Type:

DefaultValue

class telegram.utils.helpers.DefaultValue(value=None)

Bases: Generic[DVType]

Wrapper for immutable default arguments that allows to check, if the default value was set explicitly. Usage:

DefaultOne = DefaultValue(1)
def f(arg=DefaultOne):
    if arg is DefaultOne:
        print('`arg` is the default')
        arg = arg.value
    else:
        print('`arg` was set explicitly')
    print(f'`arg` = {str(arg)}')

This yields:

>>> f()
`arg` is the default
`arg` = 1
>>> f(1)
`arg` was set explicitly
`arg` = 1
>>> f(2)
`arg` was set explicitly
`arg` = 2

Also allows to evaluate truthiness:

default = DefaultValue(value)
if default:
    ...

is equivalent to:

default = DefaultValue(value)
if value:
    ...

repr(DefaultValue(value)) returns repr(value) and str(DefaultValue(value)) returns f'DefaultValue({value})'.

Parameters:

value (obj) – The value of the default argument

value

The value of the default argument

Type:

obj

static get_value(obj)

Shortcut for:

return obj.value if isinstance(obj, DefaultValue) else obj
Parameters:

obj (object) – The object to process

Returns:

The value

Return type:

Same type as input, or the value of the input

telegram.utils.helpers.create_deep_linked_url(bot_username, payload=None, group=False)

Creates a deep-linked URL for this bot_username with the specified payload. See https://core.telegram.org/bots#deep-linking to learn more.

The payload may consist of the following characters: A-Z, a-z, 0-9, _, -

Note

Works well in conjunction with CommandHandler("start", callback, filters = Filters.regex('payload'))

Examples

create_deep_linked_url(bot.get_me().username, "some-params")

Parameters:
  • bot_username (str) – The username to link to

  • payload (str, optional) – Parameters to encode in the created URL

  • group (bool, optional) – If True the user is prompted to select a group to add the bot to. If False, opens a one-on-one conversation with the bot. Defaults to False.

Returns:

An URL to start the bot with specific parameters

Return type:

str

telegram.utils.helpers.decode_conversations_from_json(json_string)

Helper method to decode a conversations dict (that uses tuples as keys) from a JSON-string created with encode_conversations_to_json().

Parameters:

json_string (str) – The conversations dict as JSON string.

Returns:

The conversations dict after decoding

Return type:

dict

telegram.utils.helpers.decode_user_chat_data_from_json(data)

Helper method to decode chat or user data (that uses ints as keys) from a JSON-string.

Parameters:

data (str) – The user/chat_data dict as JSON string.

Returns:

The user/chat_data defaultdict after decoding

Return type:

dict

telegram.utils.helpers.effective_message_type(entity)

Extracts the type of message as a string identifier from a telegram.Message or a telegram.Update.

Parameters:

entity (telegram.Update | telegram.Message) – The update or message to extract from.

Returns:

One of Message.MESSAGE_TYPES

Return type:

str

telegram.utils.helpers.encode_conversations_to_json(conversations)

Helper method to encode a conversations dict (that uses tuples as keys) to a JSON-serializable way. Use decode_conversations_from_json() to decode.

Parameters:

conversations (dict) – The conversations dict to transform to JSON.

Returns:

The JSON-serialized conversations dict

Return type:

str

telegram.utils.helpers.escape_markdown(text, version=1, entity_type=None)

Helper function to escape telegram markup symbols.

Parameters:
  • text (str) – The text.

  • version (int | str) – Use to specify the version of telegrams Markdown. Either 1 or 2. Defaults to 1.

  • entity_type (str, optional) – For the entity types PRE, CODE and the link part of TEXT_LINKS, only certain characters need to be escaped in MarkdownV2. See the official API documentation for details. Only valid in combination with version=2, will be ignored else.

telegram.utils.helpers.from_timestamp(unixtime, tzinfo=<UTC>)

Converts an (integer) unix timestamp to a timezone aware datetime object. None s are left alone (i.e. from_timestamp(None) is None).

Parameters:
  • unixtime (int) – Integer POSIX timestamp.

  • tzinfo (datetime.tzinfo, optional) – The timezone to which the timestamp is to be converted to. Defaults to UTC.

Returns:

Timezone aware equivalent datetime.datetime value if unixtime is not None; else None.

telegram.utils.helpers.get_signal_name(signum)

Returns the signal name of the given signal number.

telegram.utils.helpers.is_local_file(obj)

Checks if a given string is a file on local system.

Parameters:

obj (str) – The string to check.

telegram.utils.helpers.mention_html(user_id, name)
Parameters:
  • user_id (int) – The user’s id which you want to mention.

  • name (str) – The name the mention is showing.

Returns:

The inline mention for the user as HTML.

Return type:

str

telegram.utils.helpers.mention_markdown(user_id, name, version=1)
Parameters:
  • user_id (int) – The user’s id which you want to mention.

  • name (str) – The name the mention is showing.

  • version (int | str) – Use to specify the version of Telegram’s Markdown. Either 1 or 2. Defaults to 1.

Returns:

The inline mention for the user as Markdown.

Return type:

str

telegram.utils.helpers.parse_file_input(file_input, tg_type=None, attach=None, filename=None)

Parses input for sending files:

  • For string input, if the input is an absolute path of a local file, adds the file:// prefix. If the input is a relative path of a local file, computes the absolute path and adds the file:// prefix. Returns the input unchanged, otherwise.

  • pathlib.Path objects are treated the same way as strings.

  • For IO and bytes input, returns an telegram.InputFile.

  • If tg_type is specified and the input is of that type, returns the file_id attribute.

Parameters:
  • file_input (str | bytes | filelike object | Telegram media object) – The input to parse.

  • tg_type (type, optional) – The Telegram media type the input can be. E.g. telegram.Animation.

  • attach (bool, optional) – Whether this file should be send as one file or is part of a collection of files. Only relevant in case an telegram.InputFile is returned.

  • filename (str, optional) – The filename. Only relevant in case an telegram.InputFile is returned.

Returns:

The parsed input or the untouched file_input, in case it’s no valid file input.

Return type:

str | telegram.InputFile | object

telegram.utils.helpers.to_float_timestamp(time_object, reference_timestamp=None, tzinfo=None)

Converts a given time object to a float POSIX timestamp. Used to convert different time specifications to a common format. The time object can be relative (i.e. indicate a time increment, or a time of day) or absolute. object objects from the datetime module that are timezone-naive will be assumed to be in UTC, if bot is not passed or bot.defaults is None.

Parameters:
  • time_object (int | float | datetime.timedelta | datetime.datetime | datetime.time) –

    Time value to convert. The semantics of this parameter will depend on its type:

    • int or float will be interpreted as “seconds from reference_t

    • datetime.timedelta will be interpreted as “time increment from reference_t

    • datetime.datetime will be interpreted as an absolute date/time value

    • datetime.time will be interpreted as a specific time of day

  • reference_timestamp (float, optional) –

    POSIX timestamp that indicates the absolute time from which relative calculations are to be performed (e.g. when t is given as an int, indicating “seconds from reference_t”). Defaults to now (the time at which this function is called).

    If t is given as an absolute representation of date & time (i.e. a datetime.datetime object), reference_timestamp is not relevant and so its value should be None. If this is not the case, a ValueError will be raised.

  • tzinfo (pytz.BaseTzInfo, optional) –

    If t is a naive object from the datetime module, it will be interpreted as this timezone. Defaults to pytz.utc.

    Note

    Only to be used by telegram.ext.

Returns:

The return value depends on the type of argument t. If t is given as a time increment (i.e. as a int, float or datetime.timedelta), then the return value will be reference_t + t.

Else if it is given as an absolute date/time value (i.e. a datetime.datetime object), the equivalent value as a POSIX timestamp will be returned.

Finally, if it is a time of the day without date (i.e. a datetime.time object), the return value is the nearest future occurrence of that time of day.

Return type:

float | None

Raises:
  • TypeError – If t’s type is not one of those described above.

  • ValueError – If t is a datetime.datetime and reference_timestamp is not None.

telegram.utils.helpers.to_timestamp(dt_obj, reference_timestamp=None, tzinfo=None)

Wrapper over to_float_timestamp() which returns an integer (the float value truncated down to the nearest integer).

See the documentation for to_float_timestamp() for more details.