telegram.utils.helpers Module¶
This module contains helper functions.
-
telegram.utils.helpers.
DEFAULT_20
: telegram.utils.helpers.DefaultValue = 20¶ Default
20
- Type
-
telegram.utils.helpers.
DEFAULT_FALSE
: telegram.utils.helpers.DefaultValue = False¶ Default
False
- Type
-
telegram.utils.helpers.
DEFAULT_NONE
: telegram.utils.helpers.DefaultValue = None¶ Default
None
- Type
-
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))
returnsrepr(value)
andstr(DefaultValue(value))
returnsf'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 specifiedpayload
. 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 topayload (
str
, optional) – Parameters to encode in the created URLgroup (
bool
, optional) – IfTrue
the user is prompted to select a group to add the bot to. IfFalse
, opens a one-on-one conversation with the bot. Defaults toFalse
.
- 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 atelegram.Update
.- Parameters
entity (
telegram.Update
|telegram.Message
) – Theupdate
ormessage
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. Either1
or2
. Defaults to1
.entity_type (
str
, optional) – For the entity typesPRE
,CODE
and the link part ofTEXT_LINKS
, only certain characters need to be escaped inMarkdownV2
. See the official API documentation for details. Only valid in combination withversion=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)
isNone
).- 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 ifunixtime
is notNone
; elseNone
.
-
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. Either1
or2
. Defaults to1
.
- 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 thefile://
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 thefile_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 antelegram.InputFile
is returned.filename (
str
, optional) – The filename. Only relevant in case antelegram.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, ifbot
is not passed orbot.defaults
isNone
.- 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
orfloat
will be interpreted as “seconds fromreference_t
”datetime.timedelta
will be interpreted as “time increment fromreference_t
”datetime.datetime
will be interpreted as an absolute date/time valuedatetime.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 anint
, indicating “seconds fromreference_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. adatetime.datetime
object),reference_timestamp
is not relevant and so its value should beNone
. If this is not the case, aValueError
will be raised.tzinfo (
pytz.BaseTzInfo
, optional) –If
t
is a naive object from thedatetime
module, it will be interpreted as this timezone. Defaults topytz.utc
.Note
Only to be used by
telegram.ext
.
- Returns
The return value depends on the type of argument
t
. Ift
is given as a time increment (i.e. as aint
,float
ordatetime.timedelta
), then the return value will bereference_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 adatetime.datetime
andreference_timestamp
is notNone
.
-
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.