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