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