telegram.utils.helpers Module

This module contains helper functions.

telegram.utils.helpers.DEFAULT_20: telegram.utils.helpers.DefaultValue = 20

Default 20

Type

DefaultValue

telegram.utils.helpers.DEFAULT_FALSE: telegram.utils.helpers.DefaultValue = False

Default False

Type

DefaultValue

telegram.utils.helpers.DEFAULT_NONE: telegram.utils.helpers.DefaultValue = None

Default None

Type

DefaultValue

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

Bases: Generic[telegram.utils.helpers.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.