telegram.utils.helpers Module¶
This module contains helper functions.
-
telegram.utils.helpers.
DEFAULT_NONE
= <telegram.utils.helpers.DefaultValue object>¶ Default None
Type: DefaultValue
-
class
telegram.utils.helpers.
DefaultValue
(value=None)¶ Bases:
object
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('`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: ...
-
value
¶ The value of the default argument
Type: obj
Parameters: value ( obj
) – The value of the default argument-
-
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 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
- bot_username (
-
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 ( Update
|Message
) –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 transofrm to JSON.Returns: The JSON-serialized conversations dict Return type: str
-
telegram.utils.helpers.
escape_markdown
(text)¶ Helper function to escape telegram markup symbols.
-
telegram.utils.helpers.
from_timestamp
(unixtime)¶ Converts an (integer) unix timestamp to a naive datetime object in UTC.
None
s are left alone (i.e.from_timestamp(None)
isNone
).Parameters: unixtime (int) – integer POSIX timestamp Returns: equivalent datetime.datetime
value in naive UTC iftimestamp
is notNone
; elseNone
-
telegram.utils.helpers.
get_signal_name
(signum)¶ Returns the signal name of the given signal number.
-
telegram.utils.helpers.
mention_html
(user_id, name)¶ Parameters: - user_id (
int
) – - name (
str
) –
Returns: The inline mention for the user as html.
Return type: str
- user_id (
-
telegram.utils.helpers.
mention_markdown
(user_id, name)¶ Parameters: - user_id (
int
) – - name (
str
) –
Returns: The inline mention for the user as markdown.
Return type: str
- user_id (
-
telegram.utils.helpers.
to_float_timestamp
(t, reference_timestamp=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. Any objects from the
datetime
module that are timezone-naive will be assumed to be in UTC.None
s are left alone (i.e.to_float_timestamp(None)
isNone
).Parameters: - t (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.
Returns: - (float | None) The return value depends on the type of argument
t
. Ift
is given as a time increment (i.e. as a obj:int,
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.
Raises: TypeError
– if t’s type is not one of those described above- t (int | float | datetime.timedelta | datetime.datetime | datetime.time) –
-
telegram.utils.helpers.
to_timestamp
(dt_obj, reference_timestamp=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.