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: DVType = None)¶ Bases:
typing.Generic
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: Union[OT, DefaultValue[OT]]) → OT¶ Shortcut for:
return obj.value if isinstance(obj, DefaultValue) else obj
Parameters: obj ( object
) – The object to processReturns: The value Return type: Same type as input, or the value of the input
-
-
telegram.utils.helpers.
create_deep_linked_url
(bot_username: str, payload: str = None, group: bool = False) → str¶ 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) – 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
- bot_username (
-
telegram.utils.helpers.
decode_conversations_from_json
(json_string: str) → Dict[str, Dict[Tuple, object]]¶ 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: str) → DefaultDict[int, Dict[object, object]]¶ 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: Union[Message, Update]) → Optional[str]¶ 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: Dict[str, Dict[Tuple, object]]) → str¶ 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: str, version: int = 1, entity_type: str = None) → str¶ 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.
- text (
-
telegram.utils.helpers.
from_timestamp
(unixtime: Optional[int], tzinfo: datetime.tzinfo = <UTC>) → Optional[datetime.datetime]¶ 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
.- unixtime (
-
telegram.utils.helpers.
get_signal_name
(signum: int) → str¶ Returns the signal name of the given signal number.
-
telegram.utils.helpers.
is_local_file
(obj: Union[str, pathlib.Path, None]) → bool¶ 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: Union[int, str], name: str) → str¶ 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
- user_id (
-
telegram.utils.helpers.
mention_markdown
(user_id: Union[int, str], name: str, version: int = 1) → str¶ 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
- user_id (
-
telegram.utils.helpers.
parse_file_input
(file_input: Union[str, bytes, IO, InputFile, pathlib.Path, TelegramObject], tg_type: Type[TelegramObject] = None, attach: bool = None, filename: str = None) → Union[str, InputFile, Any]¶ 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
- For string input, if the input is an absolute path of a local file,
adds the
-
telegram.utils.helpers.
to_float_timestamp
(time_object: Union[int, float, datetime.timedelta, datetime.datetime, datetime.time], reference_timestamp: float = None, tzinfo: datetime.tzinfo = None) → float¶ 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
– Ift
’s type is not one of those described above.ValueError
– Ift
is adatetime.datetime
andreference_timestamp
is notNone
.
- time_object (
-
telegram.utils.helpers.
to_timestamp
(dt_obj: Union[int, float, datetime.timedelta, datetime.datetime, datetime.time, None], reference_timestamp: float = None, tzinfo: datetime.tzinfo = None) → Optional[int]¶ 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.