# Utilities

These are the utilities that the library has to offer.

Utilities for working with the Telegram API itself (such as handy methods to convert between an entity like a User, Chat, etc. into its Input version)

class telethon.utils.AsyncClassWrapper(wrapped)

  Bases: `object`

  __getattr__(item)
  __weakref__

    list of weak references to the object (if defined)

telethon.utils.chunks(iterable, size=100)

  Turns the given iterable into chunks of the specified size, which is 100 by default since that’s what Telegram uses the most.

telethon.utils.decode_waveform(waveform)

  Inverse operation of `encode_waveform`.

telethon.utils.encode_waveform(waveform)

  Encodes the input `bytes` into a 5-bit byte-string to be used as a voice note’s waveform. See `decode_waveform` for the reverse operation.

  Example

        chat = ...
        file = 'my.ogg'

        # Send 'my.ogg' with a ascending-triangle waveform
        await client.send_file(chat, file, attributes=[types.DocumentAttributeAudio(
            duration=7,
            voice=True,
            waveform=utils.encode_waveform(bytes(range(2 ** 5))  # 2**5 because 5-bit
        )]

        # Send 'my.ogg' with a square waveform
        await client.send_file(chat, file, attributes=[types.DocumentAttributeAudio(
            duration=7,
            voice=True,
            waveform=utils.encode_waveform(bytes((31, 31, 15, 15, 15, 15, 31, 31)) * 4)
        )]

telethon.utils.get_appropriated_part_size(file_size)

  Gets the appropriated part size when uploading or downloading files, given an initial file size.

telethon.utils.get_attributes(file, *, attributes=None, mime_type=None, force_document=False, voice_note=False, video_note=False, supports_streaming=False, thumb=None)

  Get a list of attributes for the given file and the mime type as a tuple ([attribute], mime_type).

telethon.utils.get_display_name(entity)

  Gets the display name for the given User, Chat or Channel. Returns an empty string otherwise.

telethon.utils.get_extension(media)

  Gets the corresponding extension for any Telegram media.

telethon.utils.get_inner_text(text, entities)

  Gets the inner text that’s surrounded by the given entities. For instance: text = ‘hey!’, entity = MessageEntityBold(2, 2) -> ‘y!’.

  Parameters

    - text – the original text.

    - entities – the entity or entities that must be matched.

  Returns

    a single result or a list of the text surrounded by the entities.

telethon.utils.get_input_channel(entity)

  Similar to `get_input_peer()`, but for InputChannel’s alone.

  Important

  This method does not validate for invalid general-purpose access hashes, unlike `get_input_peer`. Consider using instead: `get_input_channel(get_input_peer(channel))`.

telethon.utils.get_input_chat_photo(photo)

  Similar to `get_input_peer()`, but for chat photos

telethon.utils.get_input_dialog(dialog)

  Similar to `get_input_peer()`, but for dialogs

telethon.utils.get_input_document(document)

  Similar to `get_input_peer()`, but for documents

telethon.utils.get_input_geo(geo)

  Similar to `get_input_peer()`, but for geo points

telethon.utils.get_input_group_call(call)

  Similar to `get_input_peer()`, but for input calls.

telethon.utils.get_input_location(location)

  Similar to `get_input_peer()`, but for input messages.

  Note that this returns a tuple `(dc_id, location)`, the `dc_id` being present if known.

telethon.utils.get_input_media(media, *, is_photo=False, attributes=None, force_document=False, voice_note=False, video_note=False, supports_streaming=False, ttl=None)

  Similar to `get_input_peer()`, but for media.

  If the media is InputFile and `is_photo` is known to be `True`, it will be treated as an InputMediaUploadedPhoto. Else, the rest of parameters will indicate how to treat it.

telethon.utils.get_input_message(message)

  Similar to `get_input_peer()`, but for input messages.

telethon.utils.get_input_peer(entity, allow_self=True, check_hash=True)

  Gets the input peer for the given “entity” (user, chat or channel).

  A `TypeError` is raised if the given entity isn’t a supported type or if `check_hash is True` but the entity’s `access_hash is None` or the entity contains `min` information. In this case, the hash cannot be used for general purposes, and thus is not returned to avoid any issues which can derive from invalid access hashes.

  Note that `check_hash` is ignored if an input peer is already passed since in that case we assume the user knows what they’re doing. This is key to getting entities by explicitly passing `hash = 0`.

telethon.utils.get_input_photo(photo)

  Similar to `get_input_peer()`, but for photos

telethon.utils.get_input_user(entity)

  Similar to `get_input_peer()`, but for InputUser’s alone.

  Important

  This method does not validate for invalid general-purpose access hashes, unlike `get_input_peer`. Consider using instead: `get_input_channel(get_input_peer(channel))`.

telethon.utils.get_message_id(message)

  Similar to `get_input_peer()`, but for message IDs.

telethon.utils.get_peer(peer)

telethon.utils.get_peer_id(peer, add_mark=True)

  Convert the given peer into its marked ID by default.

  This “mark” comes from the “bot api” format, and with it the peer type can be identified back. User ID is left unmodified, chat ID is negated, and channel ID is “prefixed” with -100:

  - `user_id`

  - `-chat_id`

  - `-100channel_id`

  The original ID and the peer type class can be returned with a call to `resolve_id(marked_id)()`.

telethon.utils.is_audio(file)

  Returns `True` if the file has an audio mime type.

telethon.utils.is_gif(file)

  Returns `True` if the file extension looks like a gif file to Telegram.

telethon.utils.is_image(file)

  Returns `True` if the file extension looks like an image file to Telegram.

telethon.utils.is_list_like(obj)

  Returns `True` if the given object looks like a list.

  Checking `if hasattr(obj, '__iter__')` and ignoring `str/bytes` is not enough. Things like `open()` are also iterable (and probably many other things), so just support the commonly known list-like objects.

telethon.utils.is_video(file)

  Returns `True` if the file has a video mime type.

telethon.utils.pack_bot_file_id(file)

  Inverse operation for `resolve_bot_file_id`.

  The only parameters this method will accept are Document and Photo, and it will return a variable-length `file_id` string.

  If an invalid parameter is given, it will `return None`.

telethon.utils.parse_phone(phone)

  Parses the given phone, or returns `None` if it’s invalid.

telethon.utils.parse_username(username)

  Parses the given username or channel access hash, given a string, username or URL. Returns a tuple consisting of both the stripped, lowercase username and whether it is a joinchat/ hash (in which case is not lowercase’d).

  Returns `(None, False)` if the `username` or link is not valid.

telethon.utils.resolve_bot_file_id(file_id)

  Given a Bot API-style `file_id`, returns the media it represents. If the `file_id` is not valid, `None` is returned instead.

  Note that the `file_id` does not have information such as image dimensions or file size, so these will be zero if present.

  For thumbnails, the photo ID and hash will always be zero.

telethon.utils.resolve_id(marked_id)

  Given a marked ID, returns the original ID and its Peer type.

telethon.utils.resolve_inline_message_id(inline_msg_id)

  Resolves an inline message ID. Returns a tuple of `(message id, peer, dc id, access hash)`

  The `peer` may either be a PeerUser referencing the user who sent the message via the bot in a private conversation or small group chat, or a PeerChannel if the message was sent in a channel.

  The `access_hash` does not have any use yet.

telethon.utils.resolve_invite_link(link)

  Resolves the given invite link. Returns a tuple of `(link creator user id, global chat id, random int)`.

  Note that for broadcast channels or with the newest link format, the link creator user ID will be zero to protect their identity. Normal chats and megagroup channels will have such ID.

  Note that the chat ID may not be accurate for chats with a link that were upgraded to megagroup, since the link can remain the same, but the chat ID will be correct once a new link is generated.

telethon.utils.sanitize_parse_mode(mode)

  Converts the given parse mode into an object with `parse` and `unparse` callable properties.

telethon.utils.split_text(text, entities, *, limit=4096, max_entities=100, split_at=('\\n', '\\s', '.'))

  Split a message text and entities into multiple messages, each with their own set of entities. This allows sending a very large message as multiple messages while respecting the formatting.

  Arguments
    text (`str`):

      The message text.

    entities (List[MessageEntity])

      The formatting entities.

    limit (`int`):

      The maximum message length of each individual message.

    max_entities (`int`):

      The maximum amount of entities that will be present in each individual message.

    split_at (Tuplel[`str`]):

      The list of regular expressions that will determine where to split the text. By default, a newline is searched. If no newline is present, a space is searched. If no space is found, the split will be made at any character.

      The last expression should always match a character, or else the text will stop being splitted and the resulting text may be larger than the limit.

  Yields

    Pairs of `(str, entities)` with the split message.

  Example

        from telethon import utils
        from telethon.extensions import markdown

        very_long_markdown_text = "..."
        text, entities = markdown.parse(very_long_markdown_text)

        for text, entities in utils.split_text(text, entities):
            await client.send_message(chat, text, formatting_entities=entities)

telethon.utils.stripped_photo_to_jpg(stripped)

  Adds the JPG header and footer to a stripped image.

  Ported from https://github.com/telegramdesktop/tdesktop/blob/bec39d89e19670eb436dc794a8f20b657cb87c71/Telegram/SourceFiles/ui/image/image.cpp#L225