Update to layer 211

There no plans for this to ever be non-experimental in v1.

.coveragerc

@@ -0,0 +1,8 @@
+[run]
+branch = true
+parallel = true
+source =
+    telethon
+
+[report]
+precision = 2

.github/ISSUE_TEMPLATE.md

@@ -1,9 +0,0 @@
-<!--
-0. The library is Python 3.x, not Python 2.x.
-1. If you're posting an issue, make sure it's a bug in the library, not in your code.
-2. If you're posting a question, make sure you have read and tried enough things first.
-3. Show as much information as possible, including your failed attempts, and the full console output (to include the whole traceback with line numbers).
-4. Good looking issues are a lot more appealing. If you need help check out https://guides.github.com/features/mastering-markdown/.
-
-You may also want to watch "How (not) to ask a technical question" over https://youtu.be/53zkBvL4ZB4
--->

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,96 @@
+name: Bug Report
+description: Create a report about a bug inside the library.
+body:
+
+  - type: textarea
+    id: reproducing-example
+    attributes:
+      label: Code that causes the issue
+      description: Provide a code example that reproduces the problem. Try to keep it short without other dependencies.
+      placeholder: |
+        ```python
+        from telethon.sync import TelegramClient
+        ...
+
+        ```
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected behavior
+      description: Explain what you should expect to happen. Include reproduction steps.
+      placeholder: |
+        "I was doing... I was expecting the following to happen..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual-behavior
+    attributes:
+      label: Actual behavior
+      description: Explain what actually happens.
+      placeholder: |
+        "This happened instead..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: traceback
+    attributes:
+      label: Traceback
+      description: |
+        The traceback, if the problem is a crash.
+      placeholder: |
+        ```
+        Traceback (most recent call last):
+          File "code.py", line 1, in <code>
+
+        ```
+
+  - type: input
+    id: telethon-version
+    attributes:
+      label: Telethon version
+      description: The output of `python -c "import telethon; print(telethon.__version__)"`.
+      placeholder: "1.x"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      description: The output of `python --version`.
+      placeholder: "3.x"
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating system (including distribution name and version)
+      placeholder: Windows 11, macOS 13.4, Ubuntu 23.04...
+    validations:
+      required: true
+
+  - type: textarea
+    id: other-details
+    attributes:
+      label: Other details
+      placeholder: |
+        Additional details and attachments. Is it a server? Network condition?
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      description: Read this carefully, we will close and ignore your issue if you skimmed through this.
+      options:
+        - label: The error is in the library's code, and not in my own.
+          required: true
+        - label: I have searched for this issue before posting it and there isn't an open duplicate.
+          required: true
+        - label: I ran `pip install -U https://github.com/LonamiWebs/Telethon/archive/v1.zip` and triggered the bug in the latest version.
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Ask questions in StackOverflow
+    url: https://stackoverflow.com/questions/ask?tags=telethon
+    about: Questions are not bugs. Please ask them in StackOverflow instead. Questions in the bug tracker will be closed
+  - name: Find about updates and our Telegram groups
+    url: https://t.me/s/TelethonUpdates
+    about: Be notified of updates, chat with other people about the library or ask questions in these groups

.github/ISSUE_TEMPLATE/documentation-issue.yml

@@ -0,0 +1,22 @@
+name: Documentation Issue
+description: Report a problem with the documentation.
+labels: [documentation]
+body:
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: Describe the problem in detail.
+      placeholder: This part is unclear...
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      description: Read this carefully, we will close and ignore your issue if you skimmed through this.
+      options:
+        - label: This is a documentation problem, not a question or a bug report.
+          required: true
+        - label: I have searched for this issue before posting it and there isn't a duplicate.
+          required: true

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -0,0 +1,22 @@
+name: Feature Request
+description: Suggest ideas, changes or other enhancements for the library.
+labels: [enhancement]
+body:
+
+  - type: textarea
+    id: feature-description
+    attributes:
+      label: Describe your suggested feature
+      description: Please describe your idea. Would you like another friendly method? Renaming them to something more appropriate? Changing the way something works?
+      placeholder: "It should work like this..."
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Checklist
+      description: Read this carefully, we will close and ignore your issue if you skimmed through this.
+      options:
+        - label: I have searched for this issue before posting it and there isn't a duplicate.
+          required: true

.github/pull_request_template.md

@@ -0,0 +1,5 @@
+<!--
+Thanks for the PR! Please keep in mind that v1 is *feature frozen*.
+New features very likely won't be merged, although fixes can be sent.
+All new development should happen in v2. Thanks!
+-->

.github/workflows.disabled/python.yml

@@ -0,0 +1,28 @@
+name: Python Library
+
+on: [push, pull_request]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.5", "3.6", "3.7", "3.8"]
+    steps:
+    - uses: actions/checkout@v1
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v1
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Set up env
+      run: |
+        python -m pip install --upgrade pip
+        pip install tox
+    - name: Lint with flake8
+      run: |
+        tox -e flake
+    - name: Test with pytest
+      run: |
+        # use "py", which is the default python version
+        tox -e py

.gitignore

@@ -1,103 +1,23 @@
-.idea
-telethon/tl/functions/
-telethon/tl/types/
-telethon/tl/all_tlobjects.py
+# Generated code
+/telethon/tl/functions/
+/telethon/tl/types/
+/telethon/tl/alltlobjects.py
+/telethon/errors/rpcerrorlist.py
 
 # User session
 *.session
-usermedia/
-api/settings
+/usermedia/
 
-# Quick tests should live in this file
-example.py
-
-# Byte-compiled / optimized / DLL files
+# Builds and testing
 __pycache__/
-*.py[cod]
-*$py.class
+/dist/
+/build/
+/*.egg-info/
+/readthedocs/_build/
+/.tox/
 
-# C extensions
-*.so
+# API reference docs
+/docs/
 
-# Distribution / packaging
-.Python
-env/
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-*.egg-info/
-.installed.cfg
-*.egg
-
-# PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-*.spec
-
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-*,cover
-.hypothesis/
-
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
-local_settings.py
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
-docs/_build/
-
-# PyBuilder
-target/
-
-# IPython Notebook
-.ipynb_checkpoints
-
-# pyenv
-.python-version
-
-# celery beat schedule file
-celerybeat-schedule
-
-# dotenv
-.env
-
-# virtualenv
-.venv/
-venv/
-ENV/
-
-# Spyder project settings
-.spyderproject
-
-# Rope project settings
-.ropeproject
+# File used to manually test new changes, contains sensitive data
+/example.py

.readthedocs.yaml

@@ -0,0 +1,18 @@
+# https://docs.readthedocs.io/en/stable/config-file/v2.html
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: readthedocs/conf.py
+
+formats:
+  - pdf
+  - epub
+
+python:
+  install:
+    - requirements: readthedocs/requirements.txt

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2016 LonamiWebs
+Copyright (c) 2016-Present LonamiWebs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

MANIFEST.in

@@ -1,4 +0,0 @@
-include LICENSE
-include README.rst
-
-recursive-include telethon *

README.rst

@@ -4,57 +4,84 @@ Telethon
 
   ⭐️ Thanks **everyone** who has starred the project, it means a lot!
 
-**Telethon** is Telegram client implementation in **Python 3** which uses
-the latest available API of Telegram. Remember to use **pip3** to install!
+|logo| **Telethon** is an asyncio_ **Python 3**
+MTProto_ library to interact with Telegram_'s API
+as a user or through a bot account (bot API alternative).
+
+.. important::
+
+    If you have code using Telethon before its 1.0 version, you must
+    read `Compatibility and Convenience`_ to learn how to migrate.
+    As with any third-party library for Telegram, be careful not to
+    break `Telegram's ToS`_ or `Telegram can ban the account`_.
+
+What is this?
+-------------
+
+Telegram is a popular messaging application. This library is meant
+to make it easy for you to write Python programs that can interact
+with Telegram. Think of it as a wrapper that has already done the
+heavy job for you, so you can focus on developing an application.
+
 
 Installing
 ----------
 
-.. code:: sh
+.. code-block:: sh
 
-  pip install telethon
+  pip3 install telethon
 
 
 Creating a client
 -----------------
 
-.. code:: python
+.. code-block:: python
 
-  from telethon import TelegramClient
+    from telethon import TelegramClient, events, sync
 
-  # These example values won't work. You must get your own api_id and
-  # api_hash from https://my.telegram.org, under API Development.
-  api_id = 12345
-  api_hash = '0123456789abcdef0123456789abcdef'
-  phone = '+34600000000'
+    # These example values won't work. You must get your own api_id and
+    # api_hash from https://my.telegram.org, under API Development.
+    api_id = 12345
+    api_hash = '0123456789abcdef0123456789abcdef'
 
-  client = TelegramClient('session_name', api_id, api_hash)
-  client.connect()
-
-  # If you already have a previous 'session_name.session' file, skip this.
-  client.sign_in(phone=phone)
-  me = client.sign_in(code=77777)  # Put whatever code you received here.
+    client = TelegramClient('session_name', api_id, api_hash)
+    client.start()
 
 
 Doing stuff
 -----------
 
-.. code:: python
+.. code-block:: python
 
-  print(me.stringify())
+    print(client.get_me().stringify())
 
-  client.send_message('username', 'Hello! Talking to you from Telethon')
-  client.send_file('username', '/home/myself/Pictures/holidays.jpg')
+    client.send_message('username', 'Hello! Talking to you from Telethon')
+    client.send_file('username', '/home/myself/Pictures/holidays.jpg')
 
-  client.download_profile_photo(me)
-  total, messages, senders = client.get_message_history('username')
-  client.download_media(messages[0])
+    client.download_profile_photo('me')
+    messages = client.get_messages('username')
+    messages[0].download_media()
+
+    @client.on(events.NewMessage(pattern='(?i)hi|hello'))
+    async def handler(event):
+        await event.respond('Hey!')
 
 
 Next steps
 ----------
 
-Do you like how Telethon looks? Check the
-`wiki over GitHub <https://github.com/LonamiWebs/Telethon/wiki>`_ for a
-more in-depth explanation, with examples, troubleshooting issues, and more
+Do you like how Telethon looks? Check out `Read The Docs`_ for a more
+in-depth explanation, with examples, troubleshooting issues, and more
 useful information.
+
+.. _asyncio: https://docs.python.org/3/library/asyncio.html
+.. _MTProto: https://core.telegram.org/mtproto
+.. _Telegram: https://telegram.org
+.. _Compatibility and Convenience: https://docs.telethon.dev/en/stable/misc/compatibility-and-convenience.html
+.. _Telegram's ToS: https://core.telegram.org/api/terms
+.. _Telegram can ban the account: https://docs.telethon.dev/en/stable/quick-references/faq.html#my-account-was-deleted-limited-when-using-the-library
+.. _Read The Docs: https://docs.telethon.dev
+
+.. |logo| image:: logo.svg
+    :width: 24pt
+    :height: 24pt

api/settings_example

@@ -1,4 +0,0 @@
-api_id=12345
-api_hash=0123456789abcdef0123456789abcdef
-user_phone=+34600000000
-session_name=anonymous

dev-requirements.txt

@@ -0,0 +1,3 @@
+pytest
+pytest-cov
+pytest-asyncio

docs/.gitignore

@@ -1 +0,0 @@
-generated/

docs/generate.py

@@ -1,586 +0,0 @@
-#!/usr/bin/env python3
-import os
-import re
-import sys
-import shutil
-try:
-    from .docs_writer import DocsWriter
-except (ImportError, SystemError):
-    from docs_writer import DocsWriter
-
-# Small trick so importing telethon_generator works
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))
-
-from telethon_generator.parser import TLParser, TLObject
-
-
-# TLObject -> Python class name
-def get_class_name(tlobject):
-    """Gets the class name following the Python style guidelines"""
-    # Courtesy of http://stackoverflow.com/a/31531797/4759433
-    name = tlobject.name if isinstance(tlobject, TLObject) else tlobject
-    result = re.sub(r'_([a-z])', lambda m: m.group(1).upper(), name)
-
-    # Replace '_' with '' once again to make sure it doesn't appear on the name
-    result = result[:1].upper() + result[1:].replace('_', '')
-
-    # If it's a function, let it end with "Request" to identify them more easily
-    if isinstance(tlobject, TLObject) and tlobject.is_function:
-        result += 'Request'
-
-    return result
-
-
-# TLObject -> filename
-def get_file_name(tlobject, add_extension=False):
-    """Gets the file name in file_name_format.html for the given TLObject.
-       Only its name may also be given if the full TLObject is not available"""
-    if isinstance(tlobject, TLObject):
-        name = tlobject.name
-    else:
-        name = tlobject
-
-    # Courtesy of http://stackoverflow.com/a/1176023/4759433
-    s1 = re.sub('(.)([A-Z][a-z]+)', r'\1_\2', name)
-    result = re.sub('([a-z0-9])([A-Z])', r'\1_\2', s1).lower()
-    if add_extension:
-        return result + '.html'
-    else:
-        return result
-
-
-# TLObject -> from ... import ...
-def get_import_code(tlobject):
-    kind = 'functions' if tlobject.is_function else 'types'
-    ns = '.' + tlobject.namespace if tlobject.namespace else ''
-
-    return 'from telethon.tl.{}{} import {}'\
-        .format(kind, ns, get_class_name(tlobject))
-
-
-def get_create_path_for(tlobject):
-    """Gets the file path (and creates the parent directories)
-       for the given 'tlobject', relative to nothing; only its local path"""
-
-    # Determine the output directory
-    out_dir = 'methods' if tlobject.is_function else 'constructors'
-
-    if tlobject.namespace:
-        out_dir = os.path.join(out_dir, tlobject.namespace)
-
-    # Ensure that it exists
-    os.makedirs(out_dir, exist_ok=True)
-
-    # Return the resulting filename
-    return os.path.join(out_dir, get_file_name(tlobject, add_extension=True))
-
-
-def is_core_type(type_):
-    """Returns "true" if the type is considered a core type"""
-    return type_.lower() in {
-        'int', 'long', 'int128', 'int256', 'double',
-        'vector', 'string', 'bool', 'true', 'bytes', 'date'
-    }
-
-
-def get_path_for_type(type_, relative_to='.'):
-    """Similar to getting the path for a TLObject, it might not be possible
-       to have the TLObject itself but rather its name (the type);
-       this method works in the same way, returning a relative path"""
-    if is_core_type(type_):
-        path = 'index.html#%s' % type_.lower()
-
-    elif '.' in type_:
-        # If it's not a core type, then it has to be a custom Telegram type
-        namespace, name = type_.split('.')
-        path = 'types/%s/%s' % (namespace, get_file_name(name, True))
-    else:
-        path = 'types/%s' % get_file_name(type_, True)
-
-    return get_relative_path(path, relative_to)
-
-
-# Destination path from the current position -> relative to the given path
-def get_relative_path(destination, relative_to):
-    if os.path.isfile(relative_to):
-        relative_to = os.path.dirname(relative_to)
-
-    return os.path.relpath(destination, start=relative_to)
-
-
-def get_relative_paths(original, relative_to):
-    """Converts the dictionary of 'original' paths to relative paths
-       starting from the given 'relative_to' file"""
-    return {k: get_relative_path(v, relative_to) for k, v in original.items()}
-
-
-# Generate a index.html file for the given folder
-def find_title(html_file):
-    """Finds the <title> for the given HTML file, or (Unknown)"""
-    with open(html_file) as handle:
-        for line in handle:
-            if '<title>' in line:
-                # + 7 to skip len('<title>')
-                return line[line.index('<title>') + 7:line.index('</title>')]
-
-    return '(Unknown)'
-
-
-def build_menu(docs, filename, relative_main_index):
-    """Builds the menu using the given DocumentWriter up to 'filename',
-       which must be a file (it cannot be a directory)"""
-    # TODO Maybe this could be part of DocsWriter itself, "build path menu"
-    docs.add_menu('API', relative_main_index)
-
-    items = filename.split('/')
-    for i in range(len(items) - 1):
-        item = items[i]
-        link = '../' * (len(items) - (i + 2))
-        link += 'index.html'
-        docs.add_menu(item.title(), link=link)
-
-    if items[-1] != 'index.html':
-        docs.add_menu(os.path.splitext(items[-1])[0])
-    docs.end_menu()
-
-
-def generate_index(folder, original_paths):
-    """Generates the index file for the specified folder"""
-
-    # Determine the namespaces listed here (as sub folders)
-    # and the files (.html files) that we should link to
-    namespaces = []
-    files = []
-    for item in os.listdir(folder):
-        if os.path.isdir(os.path.join(folder, item)):
-            namespaces.append(item)
-        elif item != 'index.html':
-            files.append(item)
-
-    # We work with relative paths
-    paths = get_relative_paths(original_paths, relative_to=folder)
-
-    # Now that everything is setup, write the index.html file
-    filename = os.path.join(folder, 'index.html')
-    with DocsWriter(filename, type_to_path_function=get_path_for_type) as docs:
-        # Title should be the current folder name
-        docs.write_head(folder.title(), relative_css_path=paths['css'])
-
-        docs.set_menu_separator(paths['arrow'])
-        build_menu(docs, filename, relative_main_index=paths['index_all'])
-
-        docs.write_title(folder.title())
-
-        if namespaces:
-            docs.write_title('Namespaces', level=3)
-            docs.begin_table(4)
-            namespaces.sort()
-            for namespace in namespaces:
-                # For every namespace, also write the index of it
-                generate_index(os.path.join(folder, namespace), original_paths)
-                docs.add_row(namespace.title(),
-                             link=os.path.join(namespace, 'index.html'))
-
-            docs.end_table()
-
-        docs.write_title('Available items')
-        docs.begin_table(2)
-
-        files = [(f, find_title(os.path.join(folder, f))) for f in files]
-        files.sort(key=lambda t: t[1])
-
-        for file, title in files:
-            docs.add_row(title, link=file)
-
-        docs.end_table()
-        docs.end_body()
-
-
-def get_description(arg):
-    """Generates a proper description for the given argument"""
-    desc = []
-    otherwise = False
-    if arg.can_be_inferred:
-        desc.append('If left unspecified, it will be inferred automatically.')
-        otherwise = True
-    elif arg.is_flag:
-        desc.append('This argument can be omitted.')
-        otherwise = True
-
-    if arg.is_vector:
-        if arg.is_generic:
-            desc.append('A list of other Requests must be supplied.')
-        else:
-            desc.append('A list must be supplied.')
-    elif arg.is_generic:
-        desc.append('A different Request must be supplied for this argument.')
-    else:
-        otherwise = False  # Always reset to false if no other text is added
-
-    if otherwise:
-        desc.insert(1, 'Otherwise,')
-        desc[-1] = desc[-1][:1].lower() + desc[-1][1:]
-
-    return ' '.join(desc)
-
-
-def generate_documentation(scheme_file):
-    """Generates the documentation HTML files from from scheme.tl to
-       /methods and /constructors, etc.
-    """
-    original_paths = {
-        'css': 'css/docs.css',
-        'arrow': 'img/arrow.svg',
-        '404': '404.html',
-        'index_all': 'index.html',
-        'index_types': 'types/index.html',
-        'index_methods': 'methods/index.html',
-        'index_constructors': 'constructors/index.html'
-    }
-    tlobjects = tuple(TLParser.parse_file(scheme_file))
-
-    print('Generating constructors and functions documentation...')
-
-    # Save 'Type: [Constructors]' for use in both:
-    # * Seeing the return type or constructors belonging to the same type.
-    # * Generating the types documentation, showing available constructors.
-    # TODO Tried using 'defaultdict(list)' with strange results, make it work.
-    tltypes = {}
-    tlfunctions = {}
-    for tlobject in tlobjects:
-        # Select to which dictionary we want to store this type
-        dictionary = tlfunctions if tlobject.is_function else tltypes
-
-        if tlobject.result in dictionary:
-            dictionary[tlobject.result].append(tlobject)
-        else:
-            dictionary[tlobject.result] = [tlobject]
-
-    for tltype, constructors in tltypes.items():
-        tltypes[tltype] = list(sorted(constructors, key=lambda c: c.name))
-
-    for tlobject in tlobjects:
-        filename = get_create_path_for(tlobject)
-
-        # Determine the relative paths for this file
-        paths = get_relative_paths(original_paths, relative_to=filename)
-
-        with DocsWriter(filename, type_to_path_function=get_path_for_type) \
-                as docs:
-            docs.write_head(
-                title=get_class_name(tlobject),
-                relative_css_path=paths['css'])
-
-            # Create the menu (path to the current TLObject)
-            docs.set_menu_separator(paths['arrow'])
-            build_menu(docs, filename, relative_main_index=paths['index_all'])
-
-            # Create the page title
-            docs.write_title(get_class_name(tlobject))
-
-            # Write the code definition for this TLObject
-            docs.write_code(tlobject)
-            docs.write_copy_button('Copy import to the clipboard',
-                                   get_import_code(tlobject))
-
-            # Write the return type (or constructors belonging to the same type)
-            docs.write_title('Returns' if tlobject.is_function
-                             else 'Belongs to', level=3)
-
-            generic_arg = next((arg.name for arg in tlobject.args
-                                if arg.generic_definition), None)
-
-            if tlobject.result == generic_arg:
-                # We assume it's a function returning a generic type
-                generic_arg = next((arg.name for arg in tlobject.args
-                                    if arg.is_generic))
-                docs.write_text('This function returns the result of whatever '
-                                'the result from invoking the request passed '
-                                'through <i>{}</i> is.'.format(generic_arg))
-            else:
-                if re.search('^vector<', tlobject.result, re.IGNORECASE):
-                    docs.write_text('A list of the following type is returned.')
-                    _, inner = tlobject.result.split('<')
-                    inner = inner.strip('>')
-                else:
-                    inner = tlobject.result
-
-                docs.begin_table(column_count=1)
-                docs.add_row(inner, link=get_path_for_type(
-                    inner, relative_to=filename
-                ))
-                docs.end_table()
-
-                constructors = tltypes.get(inner, [])
-                if not constructors:
-                    docs.write_text('This type has no instances available.')
-                elif len(constructors) == 1:
-                    docs.write_text('This type can only be an instance of:')
-                else:
-                    docs.write_text('This type can be an instance of either:')
-
-                docs.begin_table(column_count=2)
-                for constructor in constructors:
-                    link = get_create_path_for(constructor)
-                    link = get_relative_path(link, relative_to=filename)
-                    docs.add_row(get_class_name(constructor), link=link)
-                docs.end_table()
-
-            # Return (or similar types) written. Now parameters/members
-            docs.write_title(
-                'Parameters' if tlobject.is_function else 'Members', level=3
-            )
-
-            # Sort the arguments in the same way they're sorted
-            # on the generated code (flags go last)
-            args = [
-                a for a in tlobject.sorted_args()
-                if not a.flag_indicator and not a.generic_definition
-            ]
-
-            if args:
-                # Writing parameters
-                docs.begin_table(column_count=3)
-
-                for arg in args:
-                    # Name row
-                    docs.add_row(arg.name,
-                                 bold=True)
-
-                    # Type row
-                    if arg.is_generic:
-                        docs.add_row('!' + arg.type, align='center')
-                    else:
-                        docs.add_row(
-                            arg.type, align='center', link=
-                            get_path_for_type(arg.type, relative_to=filename)
-                         )
-
-                    # Add a description for this argument
-                    docs.add_row(get_description(arg))
-
-                docs.end_table()
-            else:
-                if tlobject.is_function:
-                    docs.write_text('This request takes no input parameters.')
-                else:
-                    docs.write_text('This type has no members.')
-
-            docs.end_body()
-
-    # Find all the available types (which are not the same as the constructors)
-    # Each type has a list of constructors associated to it, hence is a map
-    print('Generating types documentation...')
-    for tltype, constructors in tltypes.items():
-        filename = get_path_for_type(tltype)
-        out_dir = os.path.dirname(filename)
-        if out_dir:
-            os.makedirs(out_dir, exist_ok=True)
-
-        # Since we don't have access to the full TLObject, split the type
-        if '.' in tltype:
-            namespace, name = tltype.split('.')
-        else:
-            namespace, name = None, tltype
-
-        # Determine the relative paths for this file
-        paths = get_relative_paths(original_paths, relative_to=out_dir)
-
-        with DocsWriter(filename, type_to_path_function=get_path_for_type) \
-                as docs:
-            docs.write_head(
-                title=get_class_name(name),
-                relative_css_path=paths['css'])
-
-            docs.set_menu_separator(paths['arrow'])
-            build_menu(docs, filename, relative_main_index=paths['index_all'])
-
-            # Main file title
-            docs.write_title(get_class_name(name))
-
-            # List available constructors for this type
-            docs.write_title('Available constructors', level=3)
-            if not constructors:
-                docs.write_text('This type has no constructors available.')
-            elif len(constructors) == 1:
-                docs.write_text('This type has one constructor available.')
-            else:
-                docs.write_text('This type has %d constructors available.' %
-                                len(constructors))
-
-            docs.begin_table(2)
-            for constructor in constructors:
-                # Constructor full name
-                link = get_create_path_for(constructor)
-                link = get_relative_path(link, relative_to=filename)
-                docs.add_row(get_class_name(constructor), link=link)
-            docs.end_table()
-
-            # List all the methods which return this type
-            docs.write_title('Methods returning this type', level=3)
-            functions = tlfunctions.get(tltype, [])
-            if not functions:
-                docs.write_text('No method returns this type.')
-            elif len(functions) == 1:
-                docs.write_text('Only the following method returns this type.')
-            else:
-                docs.write_text(
-                    'The following %d methods return this type as a result.' %
-                    len(functions)
-                )
-
-            docs.begin_table(2)
-            for func in functions:
-                link = get_create_path_for(func)
-                link = get_relative_path(link, relative_to=filename)
-                docs.add_row(get_class_name(func), link=link)
-            docs.end_table()
-
-            # List all the methods which take this type as input
-            docs.write_title('Methods accepting this type as input', level=3)
-            other_methods = sorted(
-                (t for t in tlobjects
-                 if any(tltype == a.type for a in t.args) and t.is_function),
-                key=lambda t: t.name
-            )
-            if not other_methods:
-                docs.write_text(
-                    'No methods accept this type as an input parameter.')
-            elif len(other_methods) == 1:
-                docs.write_text(
-                    'Only this method has a parameter with this type.')
-            else:
-                docs.write_text(
-                    'The following %d methods accept this type as an input '
-                    'parameter.' % len(other_methods))
-
-            docs.begin_table(2)
-            for ot in other_methods:
-                link = get_create_path_for(ot)
-                link = get_relative_path(link, relative_to=filename)
-                docs.add_row(get_class_name(ot), link=link)
-            docs.end_table()
-
-            # List every other type which has this type as a member
-            docs.write_title('Other types containing this type', level=3)
-            other_types = sorted(
-                (t for t in tlobjects
-                 if any(tltype == a.type for a in t.args)
-                 and not t.is_function
-                 ), key=lambda t: t.name
-            )
-
-            if not other_types:
-                docs.write_text(
-                    'No other types have a member of this type.')
-            elif len(other_types) == 1:
-                docs.write_text(
-                    'You can find this type as a member of this other type.')
-            else:
-                docs.write_text(
-                    'You can find this type as a member of any of '
-                    'the following %d types.' % len(other_types))
-
-            docs.begin_table(2)
-            for ot in other_types:
-                link = get_create_path_for(ot)
-                link = get_relative_path(link, relative_to=filename)
-                docs.add_row(get_class_name(ot), link=link)
-            docs.end_table()
-            docs.end_body()
-
-    # After everything's been written, generate an index.html per folder.
-    # This will be done automatically and not taking into account any extra
-    # information that we have available, simply a file listing all the others
-    # accessible by clicking on their title
-    print('Generating indices...')
-    for folder in ['types', 'methods', 'constructors']:
-        generate_index(folder, original_paths)
-
-    # Write the final core index, the main index for the rest of files
-    layer = TLParser.find_layer(scheme_file)
-    types = set()
-    methods = []
-    constructors = []
-    for tlobject in tlobjects:
-        if tlobject.is_function:
-            methods.append(tlobject)
-        else:
-            constructors.append(tlobject)
-
-        if not is_core_type(tlobject.result):
-            if re.search('^vector<', tlobject.result, re.IGNORECASE):
-                types.add(tlobject.result.split('<')[1].strip('>'))
-            else:
-                types.add(tlobject.result)
-
-    types = sorted(types)
-    methods = sorted(methods, key=lambda m: m.name)
-    constructors = sorted(constructors, key=lambda c: c.name)
-
-    def fmt(xs):
-        ys = {x: get_class_name(x) for x in xs}  # cache TLObject: display
-        zs = {}  # create a dict to hold those which have duplicated keys
-        for y in ys.values():
-            zs[y] = y in zs
-        return ', '.join(
-            '"{}.{}"'.format(x.namespace, ys[x])
-            if zs[ys[x]] and getattr(x, 'namespace', None)
-            else '"{}"'.format(ys[x]) for x in xs
-        )
-
-    request_names = fmt(methods)
-    type_names = fmt(types)
-    constructor_names = fmt(constructors)
-
-    def fmt(xs, formatter):
-        return ', '.join('"{}"'.format(formatter(x)) for x in xs)
-
-    request_urls = fmt(methods, get_create_path_for)
-    type_urls = fmt(types, get_path_for_type)
-    constructor_urls = fmt(constructors, get_create_path_for)
-
-    replace_dict = {
-        'type_count': len(types),
-        'method_count': len(methods),
-        'constructor_count': len(tlobjects) - len(methods),
-        'layer': layer,
-
-        'request_names': request_names,
-        'type_names': type_names,
-        'constructor_names': constructor_names,
-        'request_urls': request_urls,
-        'type_urls': type_urls,
-        'constructor_urls': constructor_urls
-    }
-
-    shutil.copy('../res/404.html', original_paths['404'])
-
-    with open('../res/core.html') as infile,\
-            open(original_paths['index_all'], 'w') as outfile:
-        text = infile.read()
-        for key, value in replace_dict.items():
-            text = text.replace('{' + key + '}', str(value))
-
-        outfile.write(text)
-
-    # Everything done
-    print('Documentation generated.')
-
-
-def copy_resources():
-    for d in ['css', 'img']:
-        os.makedirs(d, exist_ok=True)
-
-    shutil.copy('../res/img/arrow.svg', 'img')
-    shutil.copy('../res/css/docs.css', 'css')
-
-
-if __name__ == '__main__':
-    os.makedirs('generated', exist_ok=True)
-    os.chdir('generated')
-    try:
-        generate_documentation('../../telethon_generator/scheme.tl')
-        copy_resources()
-    finally:
-        os.chdir(os.pardir)

docs/res/core.html

@@ -1,314 +0,0 @@
-<!DOCTYPE html>
-<html>
-<head>
-    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
-    <title>Telethon API</title>
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <link href="css/docs.css" rel="stylesheet">
-    <link href="https://fonts.googleapis.com/css?family=Nunito|Source+Code+Pro" rel="stylesheet">
-    <style>
-        body {
-            overflow: scroll;
-        }
-    </style>
-</head>
-<body>
-<div id="main_div">
-    <!-- You can append '?q=query' to the URL to default to a search -->
-    <input id="searchBox" type="text" onkeyup="updateSearch()"
-           placeholder="Search for requests and types…" />
-
-<div id="searchDiv">
-
-    <details open><summary class="title">Methods (<span id="methodsCount">0</span>)</summary>
-        <ul id="methodsList" class="together">
-        </ul>
-    </details>
-
-    <details open><summary class="title">Types (<span id="typesCount">0</span>)</summary>
-        <ul id="typesList" class="together">
-        </ul>
-    </details>
-
-    <details><summary class="title">Constructors (<span id="constructorsCount">0</span>)</summary>
-        <ul id="constructorsList" class="together">
-        </ul>
-    </details>
-</div>
-
-<div id="contentDiv">
-    <h1>Telethon API</h1>
-    <p>This documentation was generated straight from the <code>scheme.tl</code>
-    provided by Telegram. However, there is no official documentation per se
-    on what the methods, constructors and types mean. Nevertheless, this
-    page aims to provide easy access to all the available methods, their
-    definition and parameters.</p>
-
-    <p>Although this documentation was generated for <i>Telethon</i>, it may
-    be useful for any other Telegram library out there.</p>
-
-    <h3>Index</h3>
-    <ul>
-        <li>
-            <a href="#methods">Methods</a>
-            (<a href="methods/index.html">full list</a>)
-        </li>
-        <li>
-            <a href="#types">Types</a>
-            (<a href="types/index.html">full list</a>)
-        </li>
-        <li>
-            <a href="#constructors">Constructors</a>
-            (<a href="constructors/index.html">full list</a>)
-        </li>
-        <li><a href="#core">Core types</a></li>
-        <li><a href="#example">Full example</a></li>
-    </ul>
-
-    <h3 id="methods">Methods</h3>
-    <p>Currently there are <b>{method_count} methods</b> available for the layer
-    {layer}. The complete list can be seen <a href="methods/index.html">here</a>.
-    <br /><br />
-    Methods, also known as <i>requests</i>, are used to interact with
-    the Telegram API itself and are invoked with a call to <code>.invoke()</code>.
-    <b>Only these</b> can be passed to <code>.invoke()</code>! You cannot
-    <code>.invoke()</code> types or constructors, only requests. After this,
-    Telegram will return a <code>result</code>, which may be, for instance,
-    a bunch of messages, some dialogs, users, etc.</p>
-
-    <h3 id="types">Types</h3>
-    <p>Currently there are <b>{type_count} types</b>. You can see the full
-    list <a href="types/index.html">here</a>.</p>
-
-    <p>The Telegram types are the <i>abstract</i> results that you receive
-    after invoking a request. They are "abstract" because they can have
-    multiple constructors. For instance, the abstract type <code>User</code>
-    can be either <code>UserEmpty</code> or <code>User</code>. You should,
-    most of the time, make sure you received the desired type by using
-    the <code>isinstance(result, Constructor)</code> Python function.
-
-    When a request needs a Telegram type as argument, you should create
-    an instance of it by using one of its, possibly multiple, constructors.</p>
-
-    <h3 id="constructors">Constructors</h3>
-    <p>Currently there are <b>{constructor_count} constructors</b>. You can see
-    the full list <a href="constructors/index.html">here</a>.</p>
-
-    <p>Constructors are the way you can create instances of the abstract types
-    described above, and also the instances which are actually returned from
-    the functions although they all share a common abstract type.</p>
-
-    <h3 id="core">Core types</h3>
-    <p>Core types are types from which the rest of Telegram types build upon:</p>
-    <ul>
-    <li id="int"><b>int</b>:
-        The value should be an integer type, like <span class="sh1">42</span>.
-        It should have 32 bits or less. You can check the bit length by
-        calling <code>a.bit_length()</code>, where <code>a</code> is an
-        integer variable.
-    </li>
-    <li id="long"><b>long</b>:
-        Different name for an integer type. The numbers given should have
-        64 bits or less.
-    </li>
-    <li id="int128"><b>int128</b>:
-        Another integer type, should have 128 bits or less.
-    </li>
-    <li id="int256"><b>int256</b>:
-        The largest integer type, allowing 256 bits or less.
-    </li>
-    <li id="double"><b>double</b>:
-        The value should be a floating point value, such as
-        <span class="sh1">123.456</span>.
-    </li>
-    <li id="vector"><b>Vector&lt;T&gt;</b>:
-        If a type <code>T</code> is wrapped around <code>Vector&lt;T&gt;</code>,
-        then it means that the argument should be a <i>list</i> of it.
-        For instance, a valid value for <code>Vector&lt;int&gt;</code>
-        would be <code>[1, 2, 3]</code>.
-    </li>
-    <li id="string"><b>string</b>:
-        A valid UTF-8 string should be supplied. This is right how
-        Python strings work, no further encoding is required.
-    </li>
-    <li id="bool"><b>Bool</b>:
-        Either <code>True</code> or <code>False</code>.
-    </li>
-    <li id="true"><b>true</b>:
-        These arguments aren't actually sent but rather encoded as flags.
-        Any truthy value (<code>True</code>, <code>7</code>) will enable
-        this flag, although it's recommended to use <code>True</code> or
-        <code>None</code> to symbolize that it's not present.
-    </li>
-    <li id="bytes"><b>bytes</b>:
-        A sequence of bytes, like <code>b'hello'</code>, should be supplied.
-    </li>
-    <li id="date"><b>date</b>:
-        Although this type is internally used as an <code>int</code>,
-        you can pass a <code>datetime</code> object instead to work
-        with date parameters.
-    </li>
-    </ul>
-
-    <h3 id="example">Full example</h3>
-    <p>The following example demonstrates:</p>
-    <ol>
-        <li>How to create a <code>TelegramClient</code>.</li>
-        <li>Connecting to the Telegram servers and authorizing an user.</li>
-        <li>Retrieving a list of chats (<i>dialogs</i>).</li>
-        <li>Invoking a request without the built-in methods.</li>
-    </ol>
-    <pre><span class="sh3">#!/usr/bin/python3</span>
-<span class="sh4">from</span> telethon <span class="sh4">import</span> TelegramClient
-<span class="sh4">from</span> telethon.tl.functions.messages <span class="sh4">import</span> GetHistoryRequest
-
-<span class="sh3"># <b>(1)</b> Use your own values here</span>
-api_id   = <span class="sh1">12345</span>
-api_hash = <span class="sh2">'0123456789abcdef0123456789abcdef'</span>
-phone    = <span class="sh2">'+34600000000'</span>
-
-<span class="sh3"># <b>(2)</b> Create the client and connect</span>
-client = TelegramClient(<span class="sh2">'username'</span>, api_id, api_hash)
-client.connect()
-
-<span class="sh3"># Ensure you're authorized</span>
-if not client.is_user_authorized():
-    client.send_code_request(phone)
-    client.sign_in(phone, input(<span class="sh2">'Enter the code: '</span>))
-
-<span class="sh3"># <b>(3)</b> Using built-in methods</span>
-dialogs, entities = client.get_dialogs(<span class="sh1">10</span>)
-entity = entities[<span class="sh1">0</span>]
-
-<span class="sh3"># <b>(4)</b> !! Invoking a request manually !!</span>
-result = <b>client</b>(GetHistoryRequest(
-    entity,
-    limit=<span class="sh1">20</span>,
-    offset_date=<span class="sh1">None</span>,
-    offset_id=<span class="sh1">0</span>,
-    max_id=<span class="sh1">0</span>,
-    min_id=<span class="sh1">0</span>,
-    add_offset=<span class="sh1">0</span>
-))
-
-<span class="sh3"># Now you have access to the first 20 messages</span>
-messages = result.messages</pre>
-
-    <p>As it can be seen, manually calling requests with
-    <code>client(request)</code> (or using the old way, by calling
-    <code>client.invoke(request)</code>) is way more verbose than using the
-    built-in methods (such as <code>client.get_dialogs()</code>).</p>
-
-    <p>However, and
-    given that there are so many methods available, it's impossible to provide
-    a nice interface to things that may change over time. To get full access,
-    however, you're still able to invoke these methods manually.</p>
-</div>
-
-</div>
-<script>
-contentDiv = document.getElementById("contentDiv");
-searchDiv = document.getElementById("searchDiv");
-searchBox = document.getElementById("searchBox");
-
-// Search lists
-methodsList = document.getElementById("methodsList");
-methodsCount = document.getElementById("methodsCount");
-
-typesList = document.getElementById("typesList");
-typesCount = document.getElementById("typesCount");
-
-constructorsList = document.getElementById("constructorsList");
-constructorsCount = document.getElementById("constructorsCount");
-
-try {
-    requests = [{request_names}];
-    types = [{type_names}];
-    constructors = [{constructor_names}];
-
-    requestsu = [{request_urls}];
-    typesu = [{type_urls}];
-    constructorsu = [{constructor_urls}];
-} catch (e) {
-    requests = [];
-    types = [];
-    constructors = [];
-    requestsu = [];
-    typesu = [];
-    constructorsu = [];
-}
-
-// Given two input arrays "original" and "original urls" and a query,
-// return a pair of arrays with matching "query" elements from "original".
-//
-// TODO Perhaps return an array of pairs instead a pair of arrays (for cache).
-function getSearchArray(original, originalu, query) {
-    var destination = [];
-    var destinationu = [];
-
-    for (var i = 0; i < original.length; ++i) {
-        if (original[i].toLowerCase().indexOf(query) != -1) {
-            destination.push(original[i]);
-            destinationu.push(originalu[i]);
-        }
-    }
-
-    return [destination, destinationu];
-}
-
-// Modify "countSpan" and "resultList" accordingly based on the elements
-// given as [[elements], [element urls]] (both with the same length)
-function buildList(countSpan, resultList, foundElements) {
-    var result = "";
-    for (var i = 0; i < foundElements[0].length; ++i) {
-        result += '<li>';
-        result += '<a href="' + foundElements[1][i] + '">';
-        result += foundElements[0][i];
-        result += '</a></li>';
-    }
-
-    countSpan.innerHTML = "" + foundElements[0].length;
-    resultList.innerHTML = result;
-}
-
-function updateSearch() {
-    if (searchBox.value) {
-        contentDiv.style.display = "none";
-        searchDiv.style.display = "";
-
-        var query = searchBox.value.toLowerCase();
-
-        var foundRequests = getSearchArray(requests, requestsu, query);
-        var foundTypes = getSearchArray(types, typesu, query);
-        var foundConstructors = getSearchArray(
-            constructors, constructorsu, query
-        );
-
-        buildList(methodsCount, methodsList, foundRequests);
-        buildList(typesCount, typesList, foundTypes);
-        buildList(constructorsCount, constructorsList, foundConstructors);
-    } else {
-        contentDiv.style.display = "";
-        searchDiv.style.display = "none";
-    }
-}
-
-function getQuery(name) {
-    var query = window.location.search.substring(1);
-    var vars = query.split("&");
-    for (var i = 0; i != vars.length; ++i) {
-        var pair = vars[i].split("=");
-        if (pair[0] == name)
-            return pair[1];
-    }
-}
-
-var query = getQuery('q');
-if (query) {
-    searchBox.value = query;
-}
-
-updateSearch();
-</script>
-</body>
-</html>

logo.svg

@@ -0,0 +1,6 @@
+<!-- Logo hand-made by Lonami (C) LonamiWebs 2018, tidied up by JuanPotato -->
+<svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg" width="100" height="100">
+  <circle cx="50" cy="50" r="45" fill="#3777b0" />
+  <path d="M20 30 h60 v10 l-2 2 h-17.5 l-10.5 43 l-2 2 l-12.5 -45 h-17.5 v-10" fill="#f0a727"/>
+  <path d="M20 30 h60 v10 h-17.5 l-12.5 45 l-12.5 -45 h-17.5 v-10" fill="#ffd750"/>
+</svg>

optional-requirements.txt

@@ -0,0 +1,6 @@
+cryptg
+pysocks
+python-socks[asyncio]
+hachoir
+pillow
+isal

pyproject.toml

@@ -0,0 +1,36 @@
+# https://snarky.ca/what-the-heck-is-pyproject-toml/
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+# Need to use legacy format for the time being
+# https://tox.readthedocs.io/en/3.20.0/example/basic.html#pyproject-toml-tox-legacy-ini
+[tool.tox]
+legacy_tox_ini = """
+[tox]
+envlist = py35,py36,py37,py38
+
+# run with tox -e py
+[testenv]
+deps =
+    -rrequirements.txt
+    -roptional-requirements.txt
+    -rdev-requirements.txt
+commands =
+    # NOTE: you can run any command line tool here - not just tests
+    pytest {posargs}
+
+# run with tox -e flake
+[testenv:flake]
+deps =
+    -rrequirements.txt
+    -roptional-requirements.txt
+    -rdev-requirements.txt
+    flake8
+commands =
+    # stop the build if there are Python syntax errors or undefined names
+    flake8 telethon/ telethon_generator/ tests/ --count --select=E9,F63,F7,F82 --show-source --statistics
+    # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+    flake8 telethon/ telethon_generator/ tests/ --count --exit-zero --exclude telethon/tl/,telethon/errors/rpcerrorlist.py --max-complexity=10 --max-line-length=127 --statistics
+
+"""

readthedocs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = Telethon
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

readthedocs/basic/installation.rst

@@ -0,0 +1,96 @@
+.. _installation:
+
+============
+Installation
+============
+
+Telethon is a Python library, which means you need to download and install
+Python from https://www.python.org/downloads/ if you haven't already. Once
+you have Python installed, `upgrade pip`__ and run:
+
+.. code-block:: sh
+
+    python3 -m pip install --upgrade pip
+    python3 -m pip install --upgrade telethon
+
+…to install or upgrade the library to the latest version.
+
+.. __: https://pythonspeed.com/articles/upgrade-pip/
+
+Installing Development Versions
+===============================
+
+If you want the *latest* unreleased changes,
+you can run the following command instead:
+
+.. code-block:: sh
+
+    python3 -m pip install --upgrade https://github.com/LonamiWebs/Telethon/archive/v1.zip
+
+.. note::
+
+    The development version may have bugs and is not recommended for production
+    use. However, when you are `reporting a library bug`__, you should try if the
+    bug still occurs in this version.
+
+.. __: https://github.com/LonamiWebs/Telethon/issues/
+
+
+Verification
+============
+
+To verify that the library is installed correctly, run the following command:
+
+.. code-block:: sh
+
+    python3 -c "import telethon; print(telethon.__version__)"
+
+The version number of the library should show in the output.
+
+
+Optional Dependencies
+=====================
+
+If cryptg_ is installed, **the library will work a lot faster**, since
+encryption and decryption will be made in C instead of Python. If your
+code deals with a lot of updates or you are downloading/uploading a lot
+of files, you will notice a considerable speed-up (from a hundred kilobytes
+per second to several megabytes per second, if your connection allows it).
+If it's not installed, pyaes_ will be used (which is pure Python, so it's
+much slower).
+
+If pillow_ is installed, large images will be automatically resized when
+sending photos to prevent Telegram from failing with "invalid image".
+Official clients also do this.
+
+If aiohttp_ is installed, the library will be able to download
+:tl:`WebDocument` media files (otherwise you will get an error).
+
+If hachoir_ is installed, it will be used to extract metadata from files
+when sending documents. Telegram uses this information to show the song's
+performer, artist, title, duration, and for videos too (including size).
+Otherwise, they will default to empty values, and you can set the attributes
+manually.
+
+.. note::
+
+    Some of the modules may require additional dependencies before being
+    installed through ``pip``. If you have an ``apt``-based system, consider
+    installing the most commonly missing dependencies (with the right ``pip``):
+
+    .. code-block:: sh
+
+        apt update
+        apt install clang lib{jpeg-turbo,webp}-dev python{,-dev} zlib-dev
+        pip install -U --user setuptools
+        pip install -U --user telethon cryptg pillow
+
+    Thanks to `@bb010g`_ for writing down this nice list.
+
+
+.. _cryptg: https://github.com/cher-nov/cryptg
+.. _pyaes: https://github.com/ricmoo/pyaes
+.. _pillow: https://python-pillow.org
+.. _aiohttp: https://docs.aiohttp.org
+.. _hachoir: https://hachoir.readthedocs.io
+.. _@bb010g: https://static.bb010g.com

readthedocs/basic/next-steps.rst

@@ -0,0 +1,46 @@
+==========
+Next Steps
+==========
+
+These basic first steps should have gotten you started with the library.
+
+By now, you should know how to call friendly methods and how to work with
+the returned objects, how things work inside event handlers, etc.
+
+Next, we will see a quick reference summary of *all* the methods and
+properties that you will need when using the library. If you follow
+the links there, you will expand the documentation for the method
+and property, with more examples on how to use them.
+
+Therefore, **you can find an example on every method** of the client
+to learn how to use it, as well as a description of all the arguments.
+
+After that, we will go in-depth with some other important concepts
+that are worth learning and understanding.
+
+From now on, you can keep pressing the "Next" button if you want,
+or use the menu on the left, since some pages are quite lengthy.
+
+A note on developing applications
+=================================
+
+If you're using the library to make an actual application (and not just
+automate things), you should make sure to `comply with the ToS`__:
+
+    […] when logging in as an existing user, apps are supposed to call
+    [:tl:`GetTermsOfServiceUpdate`] to check for any updates to the Terms of
+    Service; this call should be repeated after ``expires`` seconds have
+    elapsed. If an update to the Terms Of Service is available, clients are
+    supposed to show a consent popup; if accepted, clients should call
+    [:tl:`AcceptTermsOfService`], providing the ``termsOfService id`` JSON
+    object; in case of denial, clients are to delete the account using
+    [:tl:`DeleteAccount`], providing Decline ToS update as deletion reason.
+
+.. __: https://core.telegram.org/api/config#terms-of-service
+
+However, if you use the library to automate or enhance your Telegram
+experience, it's very likely that you are using other applications doing this
+check for you (so you wouldn't run the risk of violating the ToS).
+
+The library itself will not automatically perform this check or accept the ToS
+because it should require user action (the only exception is during sign-up).

readthedocs/basic/quick-start.rst

@@ -0,0 +1,111 @@
+===========
+Quick-Start
+===========
+
+Let's see a longer example to learn some of the methods that the library
+has to offer. These are known as "friendly methods", and you should always
+use these if possible.
+
+.. code-block:: python
+
+    from telethon import TelegramClient
+
+    # Remember to use your own values from my.telegram.org!
+    api_id = 12345
+    api_hash = '0123456789abcdef0123456789abcdef'
+    client = TelegramClient('anon', api_id, api_hash)
+
+    async def main():
+        # Getting information about yourself
+        me = await client.get_me()
+
+        # "me" is a user object. You can pretty-print
+        # any Telegram object with the "stringify" method:
+        print(me.stringify())
+
+        # When you print something, you see a representation of it.
+        # You can access all attributes of Telegram objects with
+        # the dot operator. For example, to get the username:
+        username = me.username
+        print(username)
+        print(me.phone)
+
+        # You can print all the dialogs/conversations that you are part of:
+        async for dialog in client.iter_dialogs():
+            print(dialog.name, 'has ID', dialog.id)
+
+        # You can send messages to yourself...
+        await client.send_message('me', 'Hello, myself!')
+        # ...to some chat ID
+        await client.send_message(-100123456, 'Hello, group!')
+        # ...to your contacts
+        await client.send_message('+34600123123', 'Hello, friend!')
+        # ...or even to any username
+        await client.send_message('username', 'Testing Telethon!')
+
+        # You can, of course, use markdown in your messages:
+        message = await client.send_message(
+            'me',
+            'This message has **bold**, `code`, __italics__ and '
+            'a [nice website](https://example.com)!',
+            link_preview=False
+        )
+
+        # Sending a message returns the sent message object, which you can use
+        print(message.raw_text)
+
+        # You can reply to messages directly if you have a message object
+        await message.reply('Cool!')
+
+        # Or send files, songs, documents, albums...
+        await client.send_file('me', '/home/me/Pictures/holidays.jpg')
+
+        # You can print the message history of any chat:
+        async for message in client.iter_messages('me'):
+            print(message.id, message.text)
+
+            # You can download media from messages, too!
+            # The method will return the path where the file was saved.
+            if message.photo:
+                path = await message.download_media()
+                print('File saved to', path)  # printed after download is done
+
+    with client:
+        client.loop.run_until_complete(main())
+
+
+Here, we show how to sign in, get information about yourself, send
+messages, files, getting chats, printing messages, and downloading
+files.
+
+You should make sure that you understand what the code shown here
+does, take note on how methods are called and used and so on before
+proceeding. We will see all the available methods later on.
+
+.. important::
+
+    Note that Telethon is an asynchronous library, and as such, you should
+    get used to it and learn a bit of basic `asyncio`. This will help a lot.
+    As a quick start, this means you generally want to write all your code
+    inside some ``async def`` like so:
+
+    .. code-block:: python
+
+        client = ...
+
+        async def do_something(me):
+            ...
+
+        async def main():
+            # Most of your code should go here.
+            # You can of course make and use your own async def (do_something).
+            # They only need to be async if they need to await things.
+            me = await client.get_me()
+            await do_something(me)
+
+        with client:
+            client.loop.run_until_complete(main())
+
+    After you understand this, you may use the ``telethon.sync`` hack if you
+    want do so (see :ref:`compatibility-and-convenience`), but note you may
+    run into other issues (iPython, Anaconda, etc. have some issues with it).

readthedocs/basic/signing-in.rst

@@ -0,0 +1,229 @@
+.. _signing-in:
+
+==========
+Signing In
+==========
+
+Before working with Telegram's API, you need to get your own API ID and hash:
+
+1. `Login to your Telegram account <https://my.telegram.org/>`_ with the
+   phone number of the developer account to use.
+
+2. Click under API Development tools.
+
+3. A *Create new application* window will appear. Fill in your application
+   details. There is no need to enter any *URL*, and only the first two
+   fields (*App title* and *Short name*) can currently be changed later.
+
+4. Click on *Create application* at the end. Remember that your
+   **API hash is secret** and Telegram won't let you revoke it.
+   Don't post it anywhere!
+
+.. note::
+
+    This API ID and hash is the one used by *your application*, not your
+    phone number. You can use this API ID and hash with *any* phone number
+    or even for bot accounts.
+
+
+Editing the Code
+================
+
+This is a little introduction for those new to Python programming in general.
+
+We will write our code inside ``hello.py``, so you can use any text
+editor that you like. To run the code, use ``python3 hello.py`` from
+the terminal.
+
+.. important::
+
+    Don't call your script ``telethon.py``! Python will try to import
+    the client from there and it will fail with an error such as
+    "ImportError: cannot import name 'TelegramClient' ...".
+
+
+Signing In
+==========
+
+We can finally write some code to log into our account!
+
+.. code-block:: python
+
+    from telethon import TelegramClient
+
+    # Use your own values from my.telegram.org
+    api_id = 12345
+    api_hash = '0123456789abcdef0123456789abcdef'
+
+    # The first parameter is the .session file name (absolute paths allowed)
+    with TelegramClient('anon', api_id, api_hash) as client:
+        client.loop.run_until_complete(client.send_message('me', 'Hello, myself!'))
+
+
+In the first line, we import the class name so we can create an instance
+of the client. Then, we define variables to store our API ID and hash
+conveniently.
+
+At last, we create a new `TelegramClient <telethon.client.telegramclient.TelegramClient>`
+instance and call it ``client``. We can now use the client variable
+for anything that we want, such as sending a message to ourselves.
+
+.. note::
+
+    Since Telethon is an asynchronous library, you need to ``await``
+    coroutine functions to have them run (or otherwise, run the loop
+    until they are complete). In this tiny example, we don't bother
+    making an ``async def main()``.
+
+    See :ref:`mastering-asyncio` to find out more.
+
+
+Using a ``with`` block is the preferred way to use the library. It will
+automatically `start() <telethon.client.auth.AuthMethods.start>` the client,
+logging or signing up if necessary.
+
+If the ``.session`` file already existed, it will not login
+again, so be aware of this if you move or rename the file!
+
+
+Signing In as a Bot Account
+===========================
+
+You can also use Telethon for your bots (normal bot accounts, not users).
+You will still need an API ID and hash, but the process is very similar:
+
+
+.. code-block:: python
+
+    from telethon.sync import TelegramClient
+
+    api_id = 12345
+    api_hash = '0123456789abcdef0123456789abcdef'
+    bot_token = '12345:0123456789abcdef0123456789abcdef'
+
+    # We have to manually call "start" if we want an explicit bot token
+    bot = TelegramClient('bot', api_id, api_hash).start(bot_token=bot_token)
+
+    # But then we can use the client instance as usual
+    with bot:
+        ...
+
+
+To get a bot account, you need to talk
+with `@BotFather <https://t.me/BotFather>`_.
+
+
+Signing In behind a Proxy
+=========================
+
+If you need to use a proxy to access Telegram,
+you will need to either:
+
+* For Python >= 3.6 : `install python-socks[asyncio]`__
+* For Python <= 3.5 : `install PySocks`__
+
+and then change
+
+.. code-block:: python
+
+    TelegramClient('anon', api_id, api_hash)
+
+with
+
+.. code-block:: python
+
+    TelegramClient('anon', api_id, api_hash, proxy=("socks5", '127.0.0.1', 4444))
+
+(of course, replacing the protocol, IP and port with the protocol, IP and port of the proxy).
+
+The ``proxy=`` argument should be a dict (or tuple, for backwards compatibility),
+consisting of parameters described `in PySocks usage`__.
+
+The allowed values for the argument ``proxy_type`` are:
+
+* For Python <= 3.5:
+    * ``socks.SOCKS5`` or ``'socks5'``
+    * ``socks.SOCKS4`` or ``'socks4'``
+    * ``socks.HTTP`` or ``'http'``
+
+* For Python >= 3.6:
+    * All of the above
+    * ``python_socks.ProxyType.SOCKS5``
+    * ``python_socks.ProxyType.SOCKS4``
+    * ``python_socks.ProxyType.HTTP``
+
+
+Example:
+
+.. code-block:: python
+
+    proxy = {
+        'proxy_type': 'socks5', # (mandatory) protocol to use (see above)
+        'addr': '1.1.1.1',      # (mandatory) proxy IP address
+        'port': 5555,           # (mandatory) proxy port number
+        'username': 'foo',      # (optional) username if the proxy requires auth
+        'password': 'bar',      # (optional) password if the proxy requires auth
+        'rdns': True            # (optional) whether to use remote or local resolve, default remote
+    }
+
+For backwards compatibility with ``PySocks`` the following format
+is possible (but discouraged):
+
+.. code-block:: python
+
+    proxy = (socks.SOCKS5, '1.1.1.1', 5555, True, 'foo', 'bar')
+
+.. __: https://github.com/romis2012/python-socks#installation
+.. __: https://github.com/Anorov/PySocks#installation
+.. __: https://github.com/Anorov/PySocks#usage-1
+
+
+Using MTProto Proxies
+=====================
+
+MTProto Proxies are Telegram's alternative to normal proxies,
+and work a bit differently. The following protocols are available:
+
+* ``ConnectionTcpMTProxyAbridged``
+* ``ConnectionTcpMTProxyIntermediate``
+* ``ConnectionTcpMTProxyRandomizedIntermediate`` (preferred)
+
+For now, you need to manually specify these special connection modes
+if you want to use a MTProto Proxy. Your code would look like this:
+
+.. code-block:: python
+
+    from telethon import TelegramClient, connection
+    #   we need to change the connection ^^^^^^^^^^
+
+    client = TelegramClient(
+        'anon',
+        api_id,
+        api_hash,
+
+        # Use one of the available connection modes.
+        # Normally, this one works with most proxies.
+        connection=connection.ConnectionTcpMTProxyRandomizedIntermediate,
+
+        # Then, pass the proxy details as a tuple:
+        #     (host name, port, proxy secret)
+        #
+        # If the proxy has no secret, the secret must be:
+        #     '00000000000000000000000000000000'
+        proxy=('mtproxy.example.com', 2002, 'secret')
+    )
+
+In future updates, we may make it easier to use MTProto Proxies
+(such as avoiding the need to manually pass ``connection=``).
+
+In short, the same code above but without comments to make it clearer:
+
+.. code-block:: python
+
+    from telethon import TelegramClient, connection
+
+    client = TelegramClient(
+        'anon', api_id, api_hash,
+        connection=connection.ConnectionTcpMTProxyRandomizedIntermediate,
+        proxy=('mtproxy.example.com', 2002, 'secret')
+    )

readthedocs/basic/updates.rst

@@ -0,0 +1,159 @@
+=======
+Updates
+=======
+
+Updates are an important topic in a messaging platform like Telegram.
+After all, you want to be notified when a new message arrives, when
+a member joins, when someone starts typing, etc.
+For that, you can use **events**.
+
+.. important::
+
+    It is strongly advised to enable logging when working with events,
+    since exceptions in event handlers are hidden by default. Please
+    add the following snippet to the very top of your file:
+
+    .. code-block:: python
+
+        import logging
+        logging.basicConfig(format='[%(levelname) %(asctime)s] %(name)s: %(message)s',
+                            level=logging.WARNING)
+
+
+Getting Started
+===============
+
+Let's start things with an example to automate replies:
+
+.. code-block:: python
+
+    from telethon import TelegramClient, events
+
+    client = TelegramClient('anon', api_id, api_hash)
+
+    @client.on(events.NewMessage)
+    async def my_event_handler(event):
+        if 'hello' in event.raw_text:
+            await event.reply('hi!')
+
+    client.start()
+    client.run_until_disconnected()
+
+
+This code isn't much, but there might be some things unclear.
+Let's break it down:
+
+.. code-block:: python
+
+    from telethon import TelegramClient, events
+
+    client = TelegramClient('anon', api_id, api_hash)
+
+
+This is normal creation (of course, pass session name, API ID and hash).
+Nothing we don't know already.
+
+.. code-block:: python
+
+    @client.on(events.NewMessage)
+
+
+This Python decorator will attach itself to the ``my_event_handler``
+definition, and basically means that *on* a `NewMessage
+<telethon.events.newmessage.NewMessage>` *event*,
+the callback function you're about to define will be called:
+
+.. code-block:: python
+
+    async def my_event_handler(event):
+        if 'hello' in event.raw_text:
+            await event.reply('hi!')
+
+
+If a `NewMessage
+<telethon.events.newmessage.NewMessage>` event occurs,
+and ``'hello'`` is in the text of the message, we `reply()
+<telethon.tl.custom.message.Message.reply>` to the event
+with a ``'hi!'`` message.
+
+.. note::
+
+    Event handlers **must** be ``async def``. After all,
+    Telethon is an asynchronous library based on `asyncio`,
+    which is a safer and often faster approach to threads.
+
+    You **must** ``await`` all method calls that use
+    network requests, which is most of them.
+
+
+More Examples
+=============
+
+Replying to messages with hello is fun, but, can we do more?
+
+.. code-block:: python
+
+    @client.on(events.NewMessage(outgoing=True, pattern=r'\.save'))
+    async def handler(event):
+        if event.is_reply:
+            replied = await event.get_reply_message()
+            sender = replied.sender
+            await client.download_profile_photo(sender)
+            await event.respond('Saved your photo {}'.format(sender.username))
+
+We could also get replies. This event filters outgoing messages
+(only those that we send will trigger the method), then we filter
+by the regex ``r'\.save'``, which will match messages starting
+with ``".save"``.
+
+Inside the method, we check whether the event is replying to another message
+or not. If it is, we get the reply message and the sender of that message,
+and download their profile photo.
+
+Let's delete messages which contain "heck". We don't allow swearing here.
+
+.. code-block:: python
+
+    @client.on(events.NewMessage(pattern=r'(?i).*heck'))
+    async def handler(event):
+        await event.delete()
+
+
+With the ``r'(?i).*heck'`` regex, we match case-insensitive
+"heck" anywhere in the message. Regex is very powerful and you
+can learn more at https://regexone.com/.
+
+So far, we have only seen the `NewMessage
+<telethon.events.newmessage.NewMessage>`, but there are many more
+which will be covered later. This is only a small introduction to updates.
+
+Entities
+========
+
+When you need the user or chat where an event occurred, you **must** use
+the following methods:
+
+.. code-block:: python
+
+    async def handler(event):
+        # Good
+        chat = await event.get_chat()
+        sender = await event.get_sender()
+        chat_id = event.chat_id
+        sender_id = event.sender_id
+
+        # BAD. Don't do this
+        chat = event.chat
+        sender = event.sender
+        chat_id = event.chat.id
+        sender_id = event.sender.id
+
+Events are like messages, but don't have all the information a message has!
+When you manually get a message, it will have all the information it needs.
+When you receive an update about a message, it **won't** have all the
+information, so you have to **use the methods**, not the properties.
+
+Make sure you understand the code seen here before continuing!
+As a rule of thumb, remember that new message events behave just
+like message objects, so you can do with them everything you can
+do with a message object.

readthedocs/concepts/asyncio.rst

@@ -0,0 +1,368 @@
+.. _mastering-asyncio:
+
+=================
+Mastering asyncio
+=================
+
+.. contents::
+
+
+What's asyncio?
+===============
+
+`asyncio` is a Python 3's built-in library. This means it's already installed if
+you have Python 3. Since Python 3.5, it is convenient to work with asynchronous
+code. Before (Python 3.4) we didn't have ``async`` or ``await``, but now we do.
+
+`asyncio` stands for *Asynchronous Input Output*. This is a very powerful
+concept to use whenever you work IO. Interacting with the web or external
+APIs such as Telegram's makes a lot of sense this way.
+
+
+Why asyncio?
+============
+
+Asynchronous IO makes a lot of sense in a library like Telethon.
+You send a request to the server (such as "get some message"), and
+thanks to `asyncio`, your code won't block while a response arrives.
+
+The alternative would be to spawn a thread for each update so that
+other code can run while the response arrives. That is *a lot* more
+expensive.
+
+The code will also run faster, because instead of switching back and
+forth between the OS and your script, your script can handle it all.
+Avoiding switching saves quite a bit of time, in Python or any other
+language that supports asynchronous IO. It will also be cheaper,
+because tasks are smaller than threads, which are smaller than processes.
+
+
+What are asyncio basics?
+========================
+
+The code samples below assume that you have Python 3.7 or greater installed.
+
+.. code-block:: python
+
+    # First we need the asyncio library
+    import asyncio
+
+    # We also need something to run
+    async def main():
+        for char in 'Hello, world!\n':
+            print(char, end='', flush=True)
+            await asyncio.sleep(0.2)
+
+    # Then, we can create a new asyncio loop and use it to run our coroutine.
+    # The creation and tear-down of the loop is hidden away from us.
+    asyncio.run(main())
+
+
+What does telethon.sync do?
+===========================
+
+The moment you import any of these:
+
+.. code-block:: python
+
+    from telethon import sync, ...
+    # or
+    from telethon.sync import ...
+    # or
+    import telethon.sync
+
+The ``sync`` module rewrites most ``async def``
+methods in Telethon to something similar to this:
+
+.. code-block:: python
+
+    def new_method():
+        result = original_method()
+        if loop.is_running():
+            # the loop is already running, return the await-able to the user
+            return result
+        else:
+            # the loop is not running yet, so we can run it for the user
+            return loop.run_until_complete(result)
+
+
+That means you can do this:
+
+.. code-block:: python
+
+    print(client.get_me().username)
+
+Instead of this:
+
+.. code-block:: python
+
+    me = client.loop.run_until_complete(client.get_me())
+    print(me.username)
+
+    # or, using asyncio's default loop (it's the same)
+    import asyncio
+    loop = asyncio.get_running_loop()  # == client.loop
+    me = loop.run_until_complete(client.get_me())
+    print(me.username)
+
+
+As you can see, it's a lot of boilerplate and noise having to type
+``run_until_complete`` all the time, so you can let the magic module
+to rewrite it for you. But notice the comment above: it won't run
+the loop if it's already running, because it can't. That means this:
+
+.. code-block:: python
+
+    async def main():
+        # 3. the loop is running here
+        print(
+            client.get_me()  # 4. this will return a coroutine!
+            .username  # 5. this fails, coroutines don't have usernames
+        )
+
+    loop.run_until_complete(  # 2. run the loop and the ``main()`` coroutine
+        main()  # 1. calling ``async def`` "returns" a coroutine
+    )
+
+
+Will fail. So if you're inside an ``async def``, then the loop is
+running, and if the loop is running, you must ``await`` things yourself:
+
+.. code-block:: python
+
+    async def main():
+        print((await client.get_me()).username)
+
+    loop.run_until_complete(main())
+
+
+What are async, await and coroutines?
+=====================================
+
+The ``async`` keyword lets you define asynchronous functions,
+also known as coroutines, and also iterate over asynchronous
+loops or use ``async with``:
+
+.. code-block:: python
+
+    import asyncio
+
+    async def main():
+        # ^ this declares the main() coroutine function
+
+        async with client:
+            # ^ this is an asynchronous with block
+
+            async for message in client.iter_messages(chat):
+                # ^ this is a for loop over an asynchronous generator
+
+                print(message.sender.username)
+
+    asyncio.run(main())
+    # ^ this will create a new asyncio loop behind the scenes and tear it down
+    #   once the function returns. It will run the loop untiil main finishes.
+    #   You should only use this function if there is no other loop running.
+
+
+The ``await`` keyword blocks the *current* task, and the loop can run
+other tasks. Tasks can be thought of as "threads", since many can run
+concurrently:
+
+.. code-block:: python
+
+    import asyncio
+
+    async def hello(delay):
+        await asyncio.sleep(delay)  # await tells the loop this task is "busy"
+        print('hello')  # eventually the loop resumes the code here
+
+    async def world(delay):
+        # the loop decides this method should run first
+        await asyncio.sleep(delay)  # await tells the loop this task is "busy"
+        print('world')  # eventually the loop finishes all tasks
+
+    async def main():
+        asyncio.create_task(world(2))  # create the world task, passing 2 as delay
+        asyncio.create_task(hello(delay=1))  # another task, but with delay 1
+        await asyncio.sleep(3)  # wait for three seconds before exiting
+
+    try:
+        # create a new temporary asyncio loop and use it to run main
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        pass
+
+The same example, but without the comment noise:
+
+.. code-block:: python
+
+    import asyncio
+
+    async def hello(delay):
+        await asyncio.sleep(delay)
+        print('hello')
+
+    async def world(delay):
+        await asyncio.sleep(delay)
+        print('world')
+
+    async def main():
+        asyncio.create_task(world(2))
+        asyncio.create_task(hello(delay=1))
+        await asyncio.sleep(3)
+
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        pass
+
+
+Can I use threads?
+==================
+
+Yes, you can, but you must understand that the loops themselves are
+not thread safe. and you must be sure to know what is happening. The
+easiest and cleanest option is to use `asyncio.run` to create and manage
+the new event loop for you:
+
+.. code-block:: python
+
+    import asyncio
+    import threading
+
+    async def actual_work():
+        client = TelegramClient(..., loop=loop)
+        ...  # can use `await` here
+
+    def go():
+        asyncio.run(actual_work())
+
+    threading.Thread(target=go).start()
+
+
+Generally, **you don't need threads** unless you know what you're doing.
+Just create another task, as shown above. If you're using the Telethon
+with a library that uses threads, you must be careful to use `threading.Lock`
+whenever you use the client, or enable the compatible mode. For that, see
+:ref:`compatibility-and-convenience`.
+
+You may have seen this error:
+
+.. code-block:: text
+
+    RuntimeError: There is no current event loop in thread 'Thread-1'.
+
+It just means you didn't create a loop for that thread. Please refer to
+the ``asyncio`` documentation to correctly learn how to set the event loop
+for non-main threads.
+
+
+client.run_until_disconnected() blocks!
+=======================================
+
+All of what `client.run_until_disconnected()
+<telethon.client.updates.UpdateMethods.run_until_disconnected>` does is
+run the `asyncio`'s event loop until the client is disconnected. That means
+*the loop is running*. And if the loop is running, it will run all the tasks
+in it. So if you want to run *other* code, create tasks for it:
+
+.. code-block:: python
+
+    from datetime import datetime
+
+    async def clock():
+        while True:
+            print('The time:', datetime.now())
+            await asyncio.sleep(1)
+
+    loop.create_task(clock())
+    ...
+    client.run_until_disconnected()
+
+This creates a task for a clock that prints the time every second.
+You don't need to use `client.run_until_disconnected()
+<telethon.client.updates.UpdateMethods.run_until_disconnected>` either!
+You just need to make the loop is running, somehow. `loop.run_forever()
+<asyncio.loop.run_forever()>` and `loop.run_until_complete()
+<asyncio.loop.run_until_complete>` can also be used to run
+the loop, and Telethon will be happy with any approach.
+
+Of course, there are better tools to run code hourly or daily, see below.
+
+
+What else can asyncio do?
+=========================
+
+Asynchronous IO is a really powerful tool, as we've seen. There are plenty
+of other useful libraries that also use `asyncio` and that you can integrate
+with Telethon.
+
+* `aiohttp <https://github.com/aio-libs/aiohttp>`_ is like the infamous
+  `requests <https://github.com/requests/requests/>`_ but asynchronous.
+* `quart <https://gitlab.com/pgjones/quart>`_ is an asynchronous alternative
+  to `Flask <http://flask.pocoo.org/>`_.
+* `aiocron <https://github.com/gawel/aiocron>`_ lets you schedule things
+  to run things at a desired time, or run some tasks hourly, daily, etc.
+
+And of course, `asyncio <https://docs.python.org/3/library/asyncio.html>`_
+itself! It has a lot of methods that let you do nice things. For example,
+you can run requests in parallel:
+
+.. code-block:: python
+
+    async def main():
+        last, sent, download_path = await asyncio.gather(
+            client.get_messages('telegram', 10),
+            client.send_message('me', 'Using asyncio!'),
+            client.download_profile_photo('telegram')
+        )
+
+    loop.run_until_complete(main())
+
+
+This code will get the 10 last messages from `@telegram
+<https://t.me/telegram>`_, send one to the chat with yourself, and also
+download the profile photo of the channel. `asyncio` will run all these
+three tasks at the same time. You can run all the tasks you want this way.
+
+A different way would be:
+
+.. code-block:: python
+
+    loop.create_task(client.get_messages('telegram', 10))
+    loop.create_task(client.send_message('me', 'Using asyncio!'))
+    loop.create_task(client.download_profile_photo('telegram'))
+
+They will run in the background as long as the loop is running too.
+
+You can also `start an asyncio server
+<https://docs.python.org/3/library/asyncio-stream.html#asyncio.start_server>`_
+in the main script, and from another script, `connect to it
+<https://docs.python.org/3/library/asyncio-stream.html#asyncio.open_connection>`_
+to achieve `Inter-Process Communication
+<https://en.wikipedia.org/wiki/Inter-process_communication>`_.
+You can get as creative as you want. You can program anything you want.
+When you use a library, you're not limited to use only its methods. You can
+combine all the libraries you want. People seem to forget this simple fact!
+
+
+Why does client.start() work outside async?
+===========================================
+
+Because it's so common that it's really convenient to offer said
+functionality by default. This means you can set up all your event
+handlers and start the client without worrying about loops at all.
+
+Using the client in a ``with`` block, `start
+<telethon.client.auth.AuthMethods.start>`, `run_until_disconnected
+<telethon.client.updates.UpdateMethods.run_until_disconnected>`, and
+`disconnect <telethon.client.telegrambaseclient.TelegramBaseClient.disconnect>`
+all support this.
+
+Where can I read more?
+======================
+
+`Check out my blog post
+<https://lonami.dev/blog/asyncio/>`_ about `asyncio`, which
+has some more examples and pictures to help you understand what happens
+when the loop runs.

readthedocs/concepts/botapi-vs-mtproto.rst

@@ -0,0 +1,336 @@
+.. _botapi:
+
+=======================
+HTTP Bot API vs MTProto
+=======================
+
+
+Telethon is more than just another viable alternative when developing bots
+for Telegram. If you haven't decided which wrapper library for bots to use
+yet, using Telethon from the beginning may save you some headaches later.
+
+.. contents::
+
+
+What is Bot API?
+================
+
+The `Telegram Bot API`_, also known as HTTP Bot API and from now on referred
+to as simply "Bot API" is Telegram's official way for developers to control
+their own Telegram bots. Quoting their main page:
+
+    The Bot API is an HTTP-based interface created for developers keen on
+    building bots for Telegram.
+
+    To learn how to create and set up a bot, please consult our
+    `Introduction to Bots`_ and `Bot FAQ`_.
+
+Bot API is simply an HTTP endpoint which translates your requests to it into
+MTProto calls through tdlib_, their bot backend.
+
+Configuration of your bot, such as its available commands and auto-completion,
+is configured through `@BotFather <https://t.me/BotFather>`_.
+
+
+What is MTProto?
+================
+
+MTProto_ is Telegram's own protocol to communicate with their API when you
+connect to their servers.
+
+Telethon is an alternative MTProto-based backend written entirely in Python
+and much easier to setup and use.
+
+Both official applications and third-party clients (like your own
+applications) logged in as either user or bots **can use MTProto** to
+communicate directly with Telegram's API (which is not the HTTP bot API).
+
+When we talk about MTProto, we often mean "MTProto-based clients".
+
+
+Advantages of MTProto over Bot API
+==================================
+
+MTProto clients (like Telethon) connect directly to Telegram's servers,
+which means there is no HTTP connection, no "polling" or "web hooks". This
+means **less overhead**, since the protocol used between you and the server
+is much more compact than HTTP requests with responses in wasteful JSON.
+
+Since there is a direct connection to Telegram's servers, even if their
+Bot API endpoint is down, you can still have connection to Telegram directly.
+
+Using a MTProto client, you are also not limited to the public API that
+they expose, and instead, **you have full control** of what your bot can do.
+Telethon offers you all the power with often **much easier usage** than any
+of the available Python Bot API wrappers.
+
+If your application ever needs user features because bots cannot do certain
+things, you will be able to easily login as a user and even keep your bot
+without having to learn a new library.
+
+If less overhead and full control didn't convince you to use Telethon yet,
+check out the wiki page `MTProto vs HTTP Bot API`_ with a more exhaustive
+and up-to-date list of differences.
+
+
+Migrating from Bot API to Telethon
+==================================
+
+It doesn't matter if you wrote your bot with requests_ and you were
+making API requests manually, or if you used a wrapper library like
+python-telegram-bot_ or pyTelegramBotAPI_. It's never too late to
+migrate to Telethon!
+
+If you were using an asynchronous library like aiohttp_ or a wrapper like
+aiogram_ or dumbot_, it will be even easier, because Telethon is also an
+asynchronous library.
+
+Next, we will see some examples from the most popular libraries.
+
+
+Migrating from python-telegram-bot
+----------------------------------
+
+Let's take their `echobot.py`_ example and shorten it a bit:
+
+.. code-block:: python
+
+    from telegram.ext import Updater, CommandHandler, MessageHandler, Filters
+
+    def start(update, context):
+        """Send a message when the command /start is issued."""
+        update.message.reply_text('Hi!')
+
+    def echo(update, context):
+        """Echo the user message."""
+        update.message.reply_text(update.message.text)
+
+    def main():
+        """Start the bot."""
+        updater = Updater("TOKEN")
+        dp = updater.dispatcher
+        dp.add_handler(CommandHandler("start", start))
+        dp.add_handler(MessageHandler(Filters.text & ~Filters.command, echo))
+
+        updater.start_polling()
+
+        updater.idle()
+
+    if __name__ == '__main__':
+        main()
+
+
+After using Telethon:
+
+.. code-block:: python
+
+    from telethon import TelegramClient, events
+
+    bot = TelegramClient('bot', 11111, 'a1b2c3d4').start(bot_token='TOKEN')
+
+    @bot.on(events.NewMessage(pattern='/start'))
+    async def start(event):
+        """Send a message when the command /start is issued."""
+        await event.respond('Hi!')
+        raise events.StopPropagation
+
+    @bot.on(events.NewMessage)
+    async def echo(event):
+        """Echo the user message."""
+        await event.respond(event.text)
+
+    def main():
+        """Start the bot."""
+        bot.run_until_disconnected()
+
+    if __name__ == '__main__':
+        main()
+
+Key differences:
+
+* The recommended way to do it imports fewer things.
+* All handlers trigger by default, so we need ``events.StopPropagation``.
+* Adding handlers, responding and running is a lot less verbose.
+* Telethon needs ``async def`` and ``await``.
+* The ``bot`` isn't hidden away by ``Updater`` or ``Dispatcher``.
+
+
+Migrating from pyTelegramBotAPI
+-------------------------------
+
+Let's show another echobot from their README:
+
+.. code-block:: python
+
+    import telebot
+
+    bot = telebot.TeleBot("TOKEN")
+
+    @bot.message_handler(commands=['start'])
+    def send_welcome(message):
+        bot.reply_to(message, "Howdy, how are you doing?")
+
+    @bot.message_handler(func=lambda m: True)
+    def echo_all(message):
+        bot.reply_to(message, message.text)
+
+    bot.polling()
+
+Now we rewrite it to use Telethon:
+
+.. code-block:: python
+
+    from telethon import TelegramClient, events
+
+    bot = TelegramClient('bot', 11111, 'a1b2c3d4').start(bot_token='TOKEN')
+
+    @bot.on(events.NewMessage(pattern='/start'))
+    async def send_welcome(event):
+        await event.reply('Howdy, how are you doing?')
+
+    @bot.on(events.NewMessage)
+    async def echo_all(event):
+        await event.reply(event.text)
+
+    bot.run_until_disconnected()
+
+Key differences:
+
+* Instead of doing ``bot.reply_to(message)``, we can do ``event.reply``.
+  Note that the ``event`` behaves just like their ``message``.
+* Telethon also supports ``func=lambda m: True``, but it's not necessary.
+
+
+Migrating from aiogram
+----------------------
+
+From their GitHub:
+
+.. code-block:: python
+
+    from aiogram import Bot, Dispatcher, executor, types
+
+    API_TOKEN = 'BOT TOKEN HERE'
+
+    # Initialize bot and dispatcher
+    bot = Bot(token=API_TOKEN)
+    dp = Dispatcher(bot)
+
+    @dp.message_handler(commands=['start'])
+    async def send_welcome(message: types.Message):
+        """
+        This handler will be called when client send `/start` command.
+        """
+        await message.reply("Hi!\nI'm EchoBot!\nPowered by aiogram.")
+
+    @dp.message_handler(regexp='(^cat[s]?$|puss)')
+    async def cats(message: types.Message):
+        with open('data/cats.jpg', 'rb') as photo:
+            await bot.send_photo(message.chat.id, photo, caption='Cats is here 😺',
+                                 reply_to_message_id=message.message_id)
+
+    @dp.message_handler()
+    async def echo(message: types.Message):
+        await bot.send_message(message.chat.id, message.text)
+
+    if __name__ == '__main__':
+        executor.start_polling(dp, skip_updates=True)
+
+
+After rewrite:
+
+.. code-block:: python
+
+    from telethon import TelegramClient, events
+
+    # Initialize bot and... just the bot!
+    bot = TelegramClient('bot', 11111, 'a1b2c3d4').start(bot_token='TOKEN')
+
+    @bot.on(events.NewMessage(pattern='/start'))
+    async def send_welcome(event):
+        await event.reply('Howdy, how are you doing?')
+
+    @bot.on(events.NewMessage(pattern='(^cat[s]?$|puss)'))
+    async def cats(event):
+        await event.reply('Cats is here 😺', file='data/cats.jpg')
+
+    @bot.on(events.NewMessage)
+    async def echo_all(event):
+        await event.reply(event.text)
+
+    if __name__ == '__main__':
+        bot.run_until_disconnected()
+
+
+Key differences:
+
+* Telethon offers convenience methods to avoid retyping
+  ``bot.send_photo(message.chat.id, ...)`` all the time,
+  and instead let you type ``event.reply``.
+* Sending files is **a lot** easier. The methods for sending
+  photos, documents, audios, etc. are all the same!
+
+Migrating from dumbot
+---------------------
+
+Showcasing their subclassing example:
+
+.. code-block:: python
+
+    from dumbot import Bot
+
+    class Subbot(Bot):
+        async def init(self):
+            self.me = await self.getMe()
+
+        async def on_update(self, update):
+            await self.sendMessage(
+                chat_id=update.message.chat.id,
+                text='i am {}'.format(self.me.username)
+            )
+
+    Subbot(token).run()
+
+After rewriting:
+
+.. code-block:: python
+
+    from telethon import TelegramClient, events
+
+    class Subbot(TelegramClient):
+        def __init__(self, *a, **kw):
+            super().__init__(*a, **kw)
+            self.add_event_handler(self.on_update, events.NewMessage)
+
+        async def connect():
+            await super().connect()
+            self.me = await self.get_me()
+
+        async def on_update(event):
+            await event.reply('i am {}'.format(self.me.username))
+
+    bot = Subbot('bot', 11111, 'a1b2c3d4').start(bot_token='TOKEN')
+    bot.run_until_disconnected()
+
+
+Key differences:
+
+* Telethon method names are ``snake_case``.
+* dumbot does not offer friendly methods like ``update.reply``.
+* Telethon does not have an implicit ``on_update`` handler, so
+  we need to manually register one.
+
+
+.. _Telegram Bot API: https://core.telegram.org/bots/api
+.. _Introduction to Bots: https://core.telegram.org/bots
+.. _Bot FAQ: https://core.telegram.org/bots/faq
+.. _tdlib: https://core.telegram.org/tdlib
+.. _MTProto: https://core.telegram.org/mtproto
+.. _MTProto vs HTTP Bot API: https://github.com/LonamiWebs/Telethon/wiki/MTProto-vs-HTTP-Bot-API
+.. _requests: https://pypi.org/project/requests/
+.. _python-telegram-bot: https://python-telegram-bot.readthedocs.io
+.. _pyTelegramBotAPI: https://github.com/eternnoir/pyTelegramBotAPI
+.. _aiohttp: https://docs.aiohttp.org/en/stable
+.. _aiogram: https://aiogram.readthedocs.io
+.. _dumbot: https://github.com/Lonami/dumbot
+.. _echobot.py: https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/echobot.py

readthedocs/concepts/chats-vs-channels.rst

@@ -0,0 +1,169 @@
+.. _chats-channels:
+
+=================
+Chats vs Channels
+=================
+
+Telegram's raw API can get very confusing sometimes, in particular when it
+comes to talking about "chats", "channels", "groups", "megagroups", and all
+those concepts.
+
+This section will try to explain what each of these concepts are.
+
+
+Chats
+=====
+
+A ``Chat`` can be used to talk about either the common "subclass" that both
+chats and channels share, or the concrete :tl:`Chat` type.
+
+Technically, both :tl:`Chat` and :tl:`Channel` are a form of the `Chat type`_.
+
+**Most of the time**, the term :tl:`Chat` is used to talk about *small group
+chats*. When you create a group through an official application, this is the
+type that you get. Official applications refer to these as "Group".
+
+Both the bot API and Telethon will add a minus sign (negate) the real chat ID
+so that you can tell at a glance, with just a number, the entity type.
+
+For example, if you create a chat with :tl:`CreateChatRequest`, the real chat
+ID might be something like `123`. If you try printing it from a
+`message.chat_id` you will see `-123`. This ID helps Telethon know you're
+talking about a :tl:`Chat`.
+
+
+Channels
+========
+
+Official applications create a *broadcast* channel when you create a new
+channel (used to broadcast messages, only administrators can post messages).
+
+Official applications implicitly *migrate* an *existing* :tl:`Chat` to a
+*megagroup* :tl:`Channel` when you perform certain actions (exceed user limit,
+add a public username, set certain permissions, etc.).
+
+A ``Channel`` can be created directly with :tl:`CreateChannelRequest`, as
+either a ``megagroup`` or ``broadcast``.
+
+Official applications use the term "channel" **only** for broadcast channels.
+
+The API refers to the different types of :tl:`Channel` with certain attributes:
+
+* A **broadcast channel** is a :tl:`Channel` with the ``channel.broadcast``
+  attribute set to `True`.
+
+* A **megagroup channel** is a :tl:`Channel` with the ``channel.megagroup``
+  attribute set to `True`. Official applications refer to this as "supergroup".
+
+* A **gigagroup channel** is a :tl:`Channel` with the ``channel.gigagroup``
+  attribute set to `True`. Official applications refer to this as "broadcast
+  groups", and is used when a megagroup becomes very large and administrators
+  want to transform it into something where only they can post messages.
+
+
+Both the bot API and Telethon will "concatenate" ``-100`` to the real chat ID
+so that you can tell at a glance, with just a number, the entity type.
+
+For example, if you create a new broadcast channel, the real channel ID might
+be something like `456`. If you try printing it from a `message.chat_id` you
+will see `-1000000000456`. This ID helps Telethon know you're talking about a
+:tl:`Channel`.
+
+
+Converting IDs
+==============
+
+You can convert between the "marked" identifiers (prefixed with a minus sign)
+and the real ones with ``utils.resolve_id``. It will return a tuple with the
+real ID, and the peer type (the class):
+
+.. code-block:: python
+
+    from telethon import utils
+    real_id, peer_type = utils.resolve_id(-1000000000456)
+
+    print(real_id)  # 456
+    print(peer_type)  # <class 'telethon.tl.types.PeerChannel'>
+
+    peer = peer_type(real_id)
+    print(peer)  # PeerChannel(channel_id=456)
+
+
+The reverse operation can be done with ``utils.get_peer_id``:
+
+.. code-block:: python
+
+    print(utils.get_peer_id(types.PeerChannel(456)))  # -1000000000456
+
+
+Note that this function can also work with other types, like :tl:`Chat` or
+:tl:`Channel` instances.
+
+If you need to convert other types like usernames which might need to perform
+API calls to find out the identifier, you can use ``client.get_peer_id``:
+
+
+.. code-block:: python
+
+    print(await client.get_peer_id('me'))  # your id
+
+
+If there is no "mark" (no minus sign), Telethon will assume your identifier
+refers to a :tl:`User`. If this is **not** the case, you can manually fix it:
+
+
+.. code-block:: python
+
+    from telethon import types
+    await client.send_message(types.PeerChannel(456), 'hello')
+    #                         ^^^^^^^^^^^^^^^^^ explicit peer type
+
+
+A note on raw API
+=================
+
+Certain methods only work on a :tl:`Chat`, and some others only work on a
+:tl:`Channel` (and these may only work in broadcast, or megagroup). Your code
+likely knows what it's working with, so it shouldn't be too much of an issue.
+
+If you need to find the :tl:`Channel` from a :tl:`Chat` that migrated to it,
+access the `migrated_to` property:
+
+.. code-block:: python
+
+    # chat is a Chat
+    channel = await client.get_entity(chat.migrated_to)
+    # channel is now a Channel
+
+Channels do not have a "migrated_from", but a :tl:`ChannelFull` does. You can
+use :tl:`GetFullChannelRequest` to obtain this:
+
+.. code-block:: python
+
+    from telethon import functions
+    full = await client(functions.channels.GetFullChannelRequest(your_channel))
+    full_channel = full.full_chat
+    # full_channel is a ChannelFull
+    print(full_channel.migrated_from_chat_id)
+
+This way, you can also access the linked discussion megagroup of a broadcast channel:
+
+.. code-block:: python
+
+    print(full_channel.linked_chat_id)  # prints ID of linked discussion group or None
+
+You do not need to use ``client.get_entity`` to access the
+``migrated_from_chat_id`` :tl:`Chat` or the ``linked_chat_id`` :tl:`Channel`.
+They are in the ``full.chats`` attribute:
+
+.. code-block:: python
+
+    if full_channel.migrated_from_chat_id:
+        migrated_from_chat = next(c for c in full.chats if c.id == full_channel.migrated_from_chat_id)
+        print(migrated_from_chat.title)
+
+    if full_channel.linked_chat_id:
+        linked_group = next(c for c in full.chats if c.id == full_channel.linked_chat_id)
+        print(linked_group.username)
+
+.. _Chat type: https://tl.telethon.dev/types/chat.html

readthedocs/concepts/entities.rst

@@ -0,0 +1,313 @@
+.. _entities:
+
+========
+Entities
+========
+
+The library widely uses the concept of "entities". An entity will refer
+to any :tl:`User`, :tl:`Chat` or :tl:`Channel` object that the API may return
+in response to certain methods, such as :tl:`GetUsersRequest`.
+
+.. note::
+
+    When something "entity-like" is required, it means that you need to
+    provide something that can be turned into an entity. These things include,
+    but are not limited to, usernames, exact titles, IDs, :tl:`Peer` objects,
+    or even entire :tl:`User`, :tl:`Chat` and :tl:`Channel` objects and even
+    phone numbers **from people you have in your contact list**.
+
+    To "encounter" an ID, you would have to "find it" like you would in the
+    normal app. If the peer is in your dialogs, you would need to
+    `client.get_dialogs() <telethon.client.dialogs.DialogMethods.get_dialogs>`.
+    If the peer is someone in a group, you would similarly
+    `client.get_participants(group) <telethon.client.chats.ChatMethods.get_participants>`.
+
+    Once you have encountered an ID, the library will (by default) have saved
+    their ``access_hash`` for you, which is needed to invoke most methods.
+    This is why sometimes you might encounter this error when working with
+    the library. You should ``except ValueError`` and run code that you know
+    should work to find the entity.
+
+
+.. contents::
+
+
+What is an Entity?
+==================
+
+A lot of methods and requests require *entities* to work. For example,
+you send a message to an *entity*, get the username of an *entity*, and
+so on.
+
+There are a lot of things that work as entities: usernames, phone numbers,
+chat links, invite links, IDs, and the types themselves. That is, you can
+use any of those when you see an "entity" is needed.
+
+.. note::
+
+    Remember that the phone number must be in your contact list before you
+    can use it.
+
+You should use, **from better to worse**:
+
+1. Input entities. For example, `event.input_chat
+   <telethon.tl.custom.chatgetter.ChatGetter.input_chat>`,
+   `message.input_sender
+   <telethon.tl.custom.sendergetter.SenderGetter.input_sender>`,
+   or caching an entity you will use a lot with
+   ``entity = await client.get_input_entity(...)``.
+
+2. Entities. For example, if you had to get someone's
+   username, you can just use ``user`` or ``channel``.
+   It will work. Only use this option if you already have the entity!
+
+3. IDs. This will always look the entity up from the
+   cache (the ``*.session`` file caches seen entities).
+
+4. Usernames, phone numbers and links. The cache will be
+   used too (unless you force a `client.get_entity()
+   <telethon.client.users.UserMethods.get_entity>`),
+   but may make a request if the username, phone or link
+   has not been found yet.
+
+In recent versions of the library, the following two are equivalent:
+
+.. code-block:: python
+
+    async def handler(event):
+        await client.send_message(event.sender_id, 'Hi')
+        await client.send_message(event.input_sender, 'Hi')
+
+
+If you need to be 99% sure that the code will work (sometimes it's
+simply impossible for the library to find the input entity), or if
+you will reuse the chat a lot, consider using the following instead:
+
+.. code-block:: python
+
+    async def handler(event):
+        # This method may make a network request to find the input sender.
+        # Properties can't make network requests, so we need a method.
+        sender = await event.get_input_sender()
+        await client.send_message(sender, 'Hi')
+        await client.send_message(sender, 'Hi')
+
+
+Getting Entities
+================
+
+Through the use of the :ref:`sessions`, the library will automatically
+remember the ID and hash pair, along with some extra information, so
+you're able to just do this:
+
+.. code-block:: python
+
+    # (These examples assume you are inside an "async def")
+    #
+    # Dialogs are the "conversations you have open".
+    # This method returns a list of Dialog, which
+    # has the .entity attribute and other information.
+    #
+    # This part is IMPORTANT, because it fills the entity cache.
+    dialogs = await client.get_dialogs()
+
+    # All of these work and do the same.
+    username = await client.get_entity('username')
+    username = await client.get_entity('t.me/username')
+    username = await client.get_entity('https://telegram.dog/username')
+
+    # Other kind of entities.
+    channel = await client.get_entity('telegram.me/joinchat/AAAAAEkk2WdoDrB4-Q8-gg')
+    contact = await client.get_entity('+34xxxxxxxxx')
+    friend  = await client.get_entity(friend_id)
+
+    # Getting entities through their ID (User, Chat or Channel)
+    entity = await client.get_entity(some_id)
+
+    # You can be more explicit about the type for said ID by wrapping
+    # it inside a Peer instance. This is recommended but not necessary.
+    from telethon.tl.types import PeerUser, PeerChat, PeerChannel
+
+    my_user    = await client.get_entity(PeerUser(some_id))
+    my_chat    = await client.get_entity(PeerChat(some_id))
+    my_channel = await client.get_entity(PeerChannel(some_id))
+
+
+.. note::
+
+    You **don't** need to get the entity before using it! Just let the
+    library do its job. Use a phone from your contacts, username, ID or
+    input entity (preferred but not necessary), whatever you already have.
+
+All methods in the :ref:`telethon-client` call `.get_input_entity()
+<telethon.client.users.UserMethods.get_input_entity>` prior
+to sending the request to save you from the hassle of doing so manually.
+That way, convenience calls such as `client.send_message('username', 'hi!')
+<telethon.client.messages.MessageMethods.send_message>`
+become possible.
+
+Every entity the library encounters (in any response to any call) will by
+default be cached in the ``.session`` file (an SQLite database), to avoid
+performing unnecessary API calls. If the entity cannot be found, additonal
+calls like :tl:`ResolveUsernameRequest` or :tl:`GetContactsRequest` may be
+made to obtain the required information.
+
+
+Entities vs. Input Entities
+===========================
+
+.. note::
+
+    This section is informative, but worth reading. The library
+    will transparently handle all of these details for you.
+
+On top of the normal types, the API also make use of what they call their
+``Input*`` versions of objects. The input version of an entity (e.g.
+:tl:`InputPeerUser`, :tl:`InputChat`, etc.) only contains the minimum
+information that's required from Telegram to be able to identify
+who you're referring to: a :tl:`Peer`'s **ID** and **hash**. They
+are named like this because they are input parameters in the requests.
+
+Entities' ID are the same for all user and bot accounts, however, the access
+hash is **different for each account**, so trying to reuse the access hash
+from one account in another will **not** work.
+
+Sometimes, Telegram only needs to indicate the type of the entity along
+with their ID. For this purpose, :tl:`Peer` versions of the entities also
+exist, which just have the ID. You cannot get the hash out of them since
+you should not be needing it. The library probably has cached it before.
+
+Peers are enough to identify an entity, but they are not enough to make
+a request with them. You need to know their hash before you can
+"use them", and to know the hash you need to "encounter" them, let it
+be in your dialogs, participants, message forwards, etc.
+
+.. note::
+
+    You *can* use peers with the library. Behind the scenes, they are
+    replaced with the input variant. Peers "aren't enough" on their own
+    but the library will do some more work to use the right type.
+
+As we just mentioned, API calls don't need to know the whole information
+about the entities, only their ID and hash. For this reason, another method,
+`client.get_input_entity() <telethon.client.users.UserMethods.get_input_entity>`
+is available. This will always use the cache while possible, making zero API
+calls most of the time. When a request is made, if you provided the full
+entity, e.g. an :tl:`User`, the library will convert it to the required
+:tl:`InputPeer` automatically for you.
+
+**You should always favour**
+`client.get_input_entity() <telethon.client.users.UserMethods.get_input_entity>`
+**over**
+`client.get_entity() <telethon.client.users.UserMethods.get_entity>`
+for this reason! Calling the latter will always make an API call to get
+the most recent information about said entity, but invoking requests don't
+need this information, just the :tl:`InputPeer`. Only use
+`client.get_entity() <telethon.client.users.UserMethods.get_entity>`
+if you need to get actual information, like the username, name, title, etc.
+of the entity.
+
+To further simplify the workflow, since the version ``0.16.2`` of the
+library, the raw requests you make to the API are also able to call
+`client.get_input_entity() <telethon.client.users.UserMethods.get_input_entity>`
+wherever needed, so you can even do things like:
+
+.. code-block:: python
+
+    await client(SendMessageRequest('username', 'hello'))
+
+The library will call the ``.resolve()`` method of the request, which will
+resolve ``'username'`` with the appropriated :tl:`InputPeer`. Don't worry if
+you don't get this yet, but remember some of the details here are important.
+
+
+Full Entities
+=============
+
+In addition to :tl:`PeerUser`, :tl:`InputPeerUser`, :tl:`User` (and its
+variants for chats and channels), there is also the concept of :tl:`UserFull`.
+
+This full variant has additional information such as whether the user is
+blocked, its notification settings, the bio or about of the user, etc.
+
+There is also :tl:`messages.ChatFull` which is the equivalent of full entities
+for chats and channels, with also the about section of the channel. Note that
+the ``users`` field only contains bots for the channel (so that clients can
+suggest commands to use).
+
+You can get both of these by invoking :tl:`GetFullUser`, :tl:`GetFullChat`
+and :tl:`GetFullChannel` respectively.
+
+
+Accessing Entities
+==================
+
+Although it's explicitly noted in the documentation that messages
+*subclass* `ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>`
+and `SenderGetter <telethon.tl.custom.sendergetter.SenderGetter>`,
+some people still don't get inheritance.
+
+When the documentation says "Bases: `telethon.tl.custom.chatgetter.ChatGetter`"
+it means that the class you're looking at, *also* can act as the class it
+bases. In this case, `ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>`
+knows how to get the *chat* where a thing belongs to.
+
+So, a `Message <telethon.tl.custom.message.Message>` is a
+`ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>`.
+That means you can do this:
+
+.. code-block:: python
+
+    message.is_private
+    message.chat_id
+    await message.get_chat()
+    # ...etc
+
+`SenderGetter <telethon.tl.custom.sendergetter.SenderGetter>` is similar:
+
+.. code-block:: python
+
+    message.user_id
+    await message.get_input_sender()
+    message.user
+    # ...etc
+
+Quite a few things implement them, so it makes sense to reuse the code.
+For example, all events (except raw updates) implement `ChatGetter
+<telethon.tl.custom.chatgetter.ChatGetter>` since all events occur
+in some chat.
+
+
+Summary
+=======
+
+TL;DR; If you're here because of *"Could not find the input entity for"*,
+you must ask yourself "how did I find this entity through official
+applications"? Now do the same with the library. Use what applies:
+
+.. code-block:: python
+
+    # (These examples assume you are inside an "async def")
+    async with client:
+        # Does it have a username? Use it!
+        entity = await client.get_entity(username)
+
+        # Do you have a conversation open with them? Get dialogs.
+        await client.get_dialogs()
+
+        # Are they participant of some group? Get them.
+        await client.get_participants('username')
+
+        # Is the entity the original sender of a forwarded message? Get it.
+        await client.get_messages('username', 100)
+
+        # NOW you can use the ID, anywhere!
+        await client.send_message(123456, 'Hi!')
+
+        entity = await client.get_entity(123456)
+        print(entity)
+
+Once the library has "seen" the entity, you can use their **integer** ID.
+You can't use entities from IDs the library hasn't seen. You must make the
+library see them *at least once* and disconnect properly. You know where
+the entities are and you must tell the library. It won't guess for you.

readthedocs/concepts/errors.rst

@@ -0,0 +1,155 @@
+.. _rpc-errors:
+
+==========
+RPC Errors
+==========
+
+RPC stands for Remote Procedure Call, and when the library raises
+a ``RPCError``, it's because you have invoked some of the API
+methods incorrectly (wrong parameters, wrong permissions, or even
+something went wrong on Telegram's server).
+
+You should import the errors from ``telethon.errors`` like so:
+
+.. code-block:: python
+
+    from telethon import errors
+
+    try:
+        async with client.takeout() as takeout:
+            ...
+
+    except errors.TakeoutInitDelayError as e:
+        #  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ here we except TAKEOUT_INIT_DELAY
+        print('Must wait', e.seconds, 'before takeout')
+
+
+There isn't any official list of all possible RPC errors, so the
+`list of known errors`_ is provided on a best-effort basis. When new methods
+are available, the list may be lacking since we simply don't know what errors
+can raise from them.
+
+Once we do find out about a new error and what causes it, the list is
+updated, so if you see an error without a specific class, do report it
+(and what method caused it)!.
+
+This list is used to generate documentation for the `raw API page`_.
+For example, if we want to know what errors can occur from
+`messages.sendMessage`_ we can simply navigate to its raw API page
+and find it has 24 known RPC errors at the time of writing.
+
+
+Base Errors
+===========
+
+All the "base" errors are listed in :ref:`telethon-errors`.
+Any other more specific error will be a subclass of these.
+
+If the library isn't aware of a specific error just yet, it will instead
+raise one of these superclasses. This means you may find stuff like this:
+
+.. code-block:: text
+
+    telethon.errors.rpcbaseerrors.BadRequestError: RPCError 400: MESSAGE_POLL_CLOSED (caused by SendVoteRequest)
+
+If you do, make sure to open an issue or send a pull request to update the
+`list of known errors`_.
+
+
+Common Errors
+=============
+
+These are some of the errors you may normally need to deal with:
+
+-  ``FloodWaitError`` (420), the same request was repeated many times.
+   Must wait ``.seconds`` (you can access this attribute). For example:
+
+   .. code-block:: python
+
+       ...
+       from telethon import errors
+
+       try:
+           messages = await client.get_messages(chat)
+           print(messages[0].text)
+       except errors.FloodWaitError as e:
+           print('Have to sleep', e.seconds, 'seconds')
+           time.sleep(e.seconds)
+
+-  ``SessionPasswordNeededError``, if you have setup two-steps
+   verification on Telegram and are trying to sign in.
+-  ``FilePartMissingError``, if you have tried to upload an empty file.
+-  ``ChatAdminRequiredError``, you don't have permissions to perform
+   said operation on a chat or channel. Try avoiding filters, i.e. when
+   searching messages.
+
+The generic classes for different error codes are:
+
+- ``InvalidDCError`` (303), the request must be repeated on another DC.
+- ``BadRequestError`` (400), the request contained errors.
+- ``UnauthorizedError`` (401), the user is not authorized yet.
+- ``ForbiddenError`` (403), privacy violation error.
+- ``NotFoundError`` (404), make sure you're invoking ``Request``\ 's!
+
+If the error is not recognised, it will only be an ``RPCError``.
+
+You can refer to all errors from Python through the ``telethon.errors``
+module. If you don't know what attributes they have, try printing their
+dir (like ``print(dir(e))``).
+
+
+Attributes
+==========
+
+Some of the errors carry additional data in them. When they look like
+``EMAIL_UNCONFIRMED_X``, the ``_X`` value will be accessible from the
+error instance. The current list of errors that do this is the following:
+
+- ``EmailUnconfirmedError`` has ``.code_length``.
+- ``FileMigrateError`` has ``.new_dc``.
+- ``FilePartMissingError`` has ``.which``.
+- ``FloodTestPhoneWaitError`` has ``.seconds``.
+- ``FloodWaitError`` has ``.seconds``.
+- ``InterdcCallErrorError`` has ``.dc``.
+- ``InterdcCallRichErrorError`` has ``.dc``.
+- ``NetworkMigrateError`` has ``.new_dc``.
+- ``PhoneMigrateError`` has ``.new_dc``.
+- ``SlowModeWaitError`` has ``.seconds``.
+- ``TakeoutInitDelayError`` has ``.seconds``.
+- ``UserMigrateError`` has ``.new_dc``.
+
+
+Avoiding Limits
+===============
+
+Don't spam. You won't get ``FloodWaitError`` or your account banned or
+deleted if you use the library *for legit use cases*. Make cool tools.
+Don't spam! Nobody knows the exact limits for all requests since they
+depend on a lot of factors, so don't bother asking.
+
+Still, if you do have a legit use case and still get those errors, the
+library will automatically sleep when they are smaller than 60 seconds
+by default. You can set different "auto-sleep" thresholds:
+
+.. code-block:: python
+
+    client.flood_sleep_threshold = 0  # Don't auto-sleep
+    client.flood_sleep_threshold = 24 * 60 * 60  # Sleep always
+
+You can also except it and act as you prefer:
+
+.. code-block:: python
+
+    from telethon.errors import FloodWaitError
+    try:
+        ...
+    except FloodWaitError as e:
+        print('Flood waited for', e.seconds)
+        quit(1)
+
+VoIP numbers are very limited, and some countries are more limited too.
+
+
+.. _list of known errors: https://github.com/LonamiWebs/Telethon/blob/v1/telethon_generator/data/errors.csv
+.. _raw API page: https://tl.telethon.dev/
+.. _messages.sendMessage: https://tl.telethon.dev/methods/messages/send_message.html

readthedocs/concepts/full-api.rst

@@ -0,0 +1,420 @@
+.. _full-api:
+
+============
+The Full API
+============
+
+.. important::
+
+    While you have access to this, you should always use the friendly
+    methods listed on :ref:`client-ref` unless you have a better reason
+    not to, like a method not existing or you wanting more control.
+
+.. contents::
+
+
+Introduction
+============
+
+The :ref:`telethon-client` doesn't offer a method for every single request
+the Telegram API supports. However, it's very simple to *call* or *invoke*
+any request defined in Telegram's API.
+
+This section will teach you how to use what Telethon calls the `TL reference`_.
+The linked page contains a list and a way to search through *all* types
+generated from the definition of Telegram's API (in ``.tl`` file format,
+hence the name). These types include requests and constructors.
+
+.. note::
+
+    The reason to keep both https://tl.telethon.dev and this
+    documentation alive is that the former allows instant search results
+    as you type, and a "Copy import" button. If you like namespaces, you
+    can also do ``from telethon.tl import types, functions``. Both work.
+
+Telegram makes these ``.tl`` files public, which other implementations, such
+as Telethon, can also use to generate code. These files are versioned under
+what's called "layers". ``.tl`` files consist of thousands of definitions,
+and newer layers often add, change, or remove them. Each definition refers
+to either a Remote Procedure Call (RPC) function, or a type (which the
+`TL reference`_ calls "constructors", as they construct particular type
+instances).
+
+As such, the `TL reference`_ is a good place to go to learn about all possible
+requests, types, and what they look like. If you're curious about what's been
+changed between layers, you can refer to the `TL diff`_ site.
+
+
+Navigating the TL reference
+===========================
+
+Functions
+---------
+
+"Functions" is the term used for the Remote Procedure Calls (RPC) that can be
+sent to Telegram to ask it to perform something (e.g. "send message"). These
+requests have an associated return type. These can be invoked ("called"):
+
+.. code-block:: python
+
+    client = TelegramClient(...)
+    function_instance = SomeRequest(...)
+
+    # Invoke the request
+    returned_type = await client(function_instance)
+
+Whenever you find the type for a function in the `TL reference`_, the page
+will contain the following information:
+
+* What type of account can use the method. This information is regenerated
+  from time to time (by attempting to invoke the function under both account
+  types and finding out where it fails). Some requests can only be used by
+  bot accounts, others by user accounts, and others by both.
+* The TL definition. This helps you get a feel for the what the function
+  looks like. This is not Python code. It just contains the definition in
+  a concise manner.
+* "Copy import" button. Does what it says: it will copy the necessary Python
+  code to import the function to your system's clipboard for easy access.
+* Returns. The returned type. When you invoke the function, this is what the
+  result will be. It also includes which of the constructors can be returned
+  inline, to save you a click.
+* Parameters. The parameters accepted by the function, including their type,
+  whether they expect a list, and whether they're optional.
+* Known RPC errors. A best-effort list of known errors the request may cause.
+  This list is not complete and may be out of date, but should provide an
+  overview of what could go wrong.
+* Example. Autogenerated example, showcasing how you may want to call it.
+  Bear in mind that this is *autogenerated*. It may be spitting out non-sense.
+  The goal of this example is not to show you everything you can do with the
+  request, only to give you a feel for what it looks like to use it.
+
+It is very important to click through the links and navigate to get the full
+picture. A specific page will show you what the specific function returns and
+needs as input parameters. But it may reference other types, so you need to
+navigate to those to learn what those contain or need.
+
+Types
+-----
+
+"Types" as understood by TL are not actually generated in Telethon.
+They would be the "abstract base class" of the constructors, but since Python
+is duck-typed, there is hardly any need to generate mostly unnecessary code.
+The page for a type contains:
+
+* Constructors. Every type will have one or more constructors. These
+  constructors *are* generated and can be immported and used.
+* Requests returning this type. A helpful way to find out "what requests can
+  return this?". This is how you may learn what request you need to use to
+  obtain a particular instance of a type.
+* Requests accepting this type as input. A helpful way to find out "what
+  requests can use this type as one of their input parameters?". This is how
+  you may learn where a type is used.
+* Other types containing this type. A helpful way to find out "where else
+  does this type appear?". This is how you can walk back through nested
+  objects.
+
+Constructors
+------------
+
+Constructors are used to create instances of a particular type, and are also
+returned when invoking requests. You will have to create instances yourself
+when invoking requests that need a particular type as input.
+The page for a constructor contains:
+
+* Belongs to. The parent type. This is a link back to the types page for the
+  specific constructor. It also contains the sibling constructors inline, to
+  save you a click.
+* Members. Both the input parameters *and* fields the constructor contains.
+
+
+Using the TL reference
+======================
+
+After you've found a request you want to send, a good start would be to simply
+copy and paste the autogenerated example into your script. Then you can simply
+tweak it to your needs.
+
+If you want to do it from scratch, first, make sure to import the request into
+your code (either using the "Copy import" button near the top, or by manually
+spelling out the package under ``telethon.tl.functions.*``).
+
+Then, start reading the parameters one by one. If the parameter cannot be
+omitted, you **will** need to specify it, so make sure to spell it out as
+an input parameter when constructing the request instance. Let's look at
+`PingRequest`_ for example. First, we copy the import:
+
+.. code-block:: python
+
+    from telethon.tl.functions import PingRequest
+
+Then, we look at the parameters:
+
+    ping_id - long
+
+A single parameter, and it's a long (a integer number with a large range of
+values). It doesn't say it can be omitted, so we must provide it, like so:
+
+.. code-block:: python
+
+    PingRequest(
+        ping_id=48641868471
+    )
+
+(In this case, the ping ID is a random number. You often have to guess what
+the parameter needs just by looking at the name.)
+
+Now that we have our request, we can invoke it:
+
+.. code-block:: python
+
+    response = await client(PingRequest(
+        ping_id=48641868471
+    ))
+
+To find out what ``response`` looks like, we can do as the autogenerated
+example suggests and "stringify" the result as a pretty-printed string:
+
+.. code-block:: python
+
+    print(result.stringify())
+
+This will print out the following:
+
+.. code-block:: python
+
+    Pong(
+        msg_id=781875678118,
+        ping_id=48641868471
+    )
+
+Which is a very easy way to get a feel for a response. You should nearly
+always print the stringified result, at least once, when trying out requests,
+to get a feel for what the response may look like.
+
+But of course, you don't need to do that. Without writing any code, you could
+have navigated through the "Returns" link to learn ``PingRequest`` returns a
+``Pong``, which only has one constructor, and the constructor has two members,
+``msg_id`` and ``ping_id``.
+
+If you wanted to create your own ``Pong``, you would use both members as input
+parameters:
+
+.. code-block:: python
+
+    my_pong = Pong(
+        msg_id=781875678118,
+        ping_id=48641868471
+    )
+
+(Yes, constructing object instances can use the same code that ``.stringify``
+would return!)
+
+And if you wanted to access the ``msg_id`` member, you would simply access it
+like any other attribute access in Python:
+
+.. code-block:: python
+
+    print(response.msg_id)
+
+
+Example walkthrough
+===================
+
+Say `client.send_message()
+<telethon.client.messages.MessageMethods.send_message>` didn't exist,
+we could `use the search`_ to look for "message". There we would find
+:tl:`SendMessageRequest`, which we can work with.
+
+Every request is a Python class, and has the parameters needed for you
+to invoke it. You can also call ``help(request)`` for information on
+what input parameters it takes. Remember to "Copy import to the
+clipboard", or your script won't be aware of this class! Now we have:
+
+.. code-block:: python
+
+    from telethon.tl.functions.messages import SendMessageRequest
+
+If you're going to use a lot of these, you may do:
+
+.. code-block:: python
+
+    from telethon.tl import types, functions
+    # We now have access to 'functions.messages.SendMessageRequest'
+
+We see that this request must take at least two parameters, a ``peer``
+of type :tl:`InputPeer`, and a ``message`` which is just a Python
+`str`\ ing.
+
+How can we retrieve this :tl:`InputPeer`? We have two options. We manually
+construct one, for instance:
+
+.. code-block:: python
+
+    from telethon.tl.types import InputPeerUser
+
+    peer = InputPeerUser(user_id, user_hash)
+
+Or we call `client.get_input_entity()
+<telethon.client.users.UserMethods.get_input_entity>`:
+
+.. code-block:: python
+
+    import telethon
+
+    async def main():
+        peer = await client.get_input_entity('someone')
+
+    client.loop.run_until_complete(main())
+
+.. note::
+
+    Remember that ``await`` must occur inside an ``async def``.
+    Every full API example assumes you already know and do this.
+
+
+When you're going to invoke an API method, most require you to pass an
+:tl:`InputUser`, :tl:`InputChat`, or so on, this is why using
+`client.get_input_entity() <telethon.client.users.UserMethods.get_input_entity>`
+is more straightforward (and often immediate, if you've seen the user before,
+know their ID, etc.). If you also **need** to have information about the whole
+user, use `client.get_entity() <telethon.client.users.UserMethods.get_entity>`
+instead:
+
+.. code-block:: python
+
+    entity = await client.get_entity('someone')
+
+In the later case, when you use the entity, the library will cast it to
+its "input" version for you. If you already have the complete user and
+want to cache its input version so the library doesn't have to do this
+every time its used, simply call `telethon.utils.get_input_peer`:
+
+.. code-block:: python
+
+    from telethon import utils
+    peer = utils.get_input_peer(entity)
+
+
+.. note::
+
+    Since ``v0.16.2`` this is further simplified. The ``Request`` itself
+    will call `client.get_input_entity
+    <telethon.client.users.UserMethods.get_input_entity>` for you when
+    required, but it's good to remember what's happening.
+
+After this small parenthesis about `client.get_entity
+<telethon.client.users.UserMethods.get_entity>` versus
+`client.get_input_entity() <telethon.client.users.UserMethods.get_input_entity>`,
+we have everything we need. To invoke our
+request we do:
+
+.. code-block:: python
+
+    result = await client(SendMessageRequest(peer, 'Hello there!'))
+
+Message sent! Of course, this is only an example. There are over 250
+methods available as of layer 80, and you can use every single of them
+as you wish. Remember to use the right types! To sum up:
+
+.. code-block:: python
+
+    result = await client(SendMessageRequest(
+        await client.get_input_entity('username'), 'Hello there!'
+    ))
+
+
+This can further be simplified to:
+
+.. code-block:: python
+
+    result = await client(SendMessageRequest('username', 'Hello there!'))
+    # Or even
+    result = await client(SendMessageRequest(PeerChannel(id), 'Hello there!'))
+
+.. note::
+
+    Note that some requests have a "hash" parameter. This is **not**
+    your ``api_hash``! It likely isn't your self-user ``.access_hash`` either.
+
+    It's a special hash used by Telegram to only send a difference of new data
+    that you don't already have with that request, so you can leave it to 0,
+    and it should work (which means no hash is known yet).
+
+    For those requests having a "limit" parameter, you can often set it to
+    zero to signify "return default amount". This won't work for all of them
+    though, for instance, in "messages.search" it will actually return 0 items.
+
+
+Requests in Parallel
+====================
+
+The library will automatically merge outgoing requests into a single
+*container*. Telegram's API supports sending multiple requests in a
+single container, which is faster because it has less overhead and
+the server can run them without waiting for others. You can also
+force using a container manually:
+
+.. code-block:: python
+
+    async def main():
+
+        # Letting the library do it behind the scenes
+        await asyncio.wait([
+            client.send_message('me', 'Hello'),
+            client.send_message('me', ','),
+            client.send_message('me', 'World'),
+            client.send_message('me', '.')
+        ])
+
+        # Manually invoking many requests at once
+        await client([
+            SendMessageRequest('me', 'Hello'),
+            SendMessageRequest('me', ', '),
+            SendMessageRequest('me', 'World'),
+            SendMessageRequest('me', '.')
+        ])
+
+Note that you cannot guarantee the order in which they are run.
+Try running the above code more than one time. You will see the
+order in which the messages arrive is different.
+
+If you use the raw API (the first option), you can use ``ordered``
+to tell the server that it should run the requests sequentially.
+This will still be faster than going one by one, since the server
+knows all requests directly:
+
+.. code-block:: python
+
+    await client([
+        SendMessageRequest('me', 'Hello'),
+        SendMessageRequest('me', ', '),
+        SendMessageRequest('me', 'World'),
+        SendMessageRequest('me', '.')
+    ], ordered=True)
+
+If any of the requests fails with a Telegram error (not connection
+errors or any other unexpected events), the library will raise
+`telethon.errors.common.MultiError`. You can ``except`` this
+and still access the successful results:
+
+.. code-block:: python
+
+    from telethon.errors import MultiError
+
+    try:
+        await client([
+            SendMessageRequest('me', 'Hello'),
+            SendMessageRequest('me', ''),
+            SendMessageRequest('me', 'World')
+        ], ordered=True)
+    except MultiError as e:
+        # The first and third requests worked.
+        first = e.results[0]
+        third = e.results[2]
+        # The second request failed.
+        second = e.exceptions[1]
+
+.. _TL reference: https://tl.telethon.dev
+.. _TL diff: https://diff.telethon.dev
+.. _PingRequest: https://tl.telethon.dev/methods/ping.html
+.. _use the search: https://tl.telethon.dev/?q=message&redirect=no

readthedocs/concepts/sessions.rst

@@ -0,0 +1,165 @@
+.. _sessions:
+
+==============
+Session Files
+==============
+
+.. contents::
+
+They are an important part for the library to be efficient, such as caching
+and handling your authorization key (or you would have to login every time!).
+
+What are Sessions?
+==================
+
+The first parameter you pass to the constructor of the
+:ref:`TelegramClient <telethon-client>` is
+the ``session``, and defaults to be the session name (or full path). That is,
+if you create a ``TelegramClient('anon')`` instance and connect, an
+``anon.session`` file will be created in the working directory.
+
+Note that if you pass a string it will be a file in the current working
+directory, although you can also pass absolute paths.
+
+The session file contains enough information for you to login without
+re-sending the code, so if you have to enter the code more than once,
+maybe you're changing the working directory, renaming or removing the
+file, or using random names.
+
+These database files using ``sqlite3`` contain the required information to
+talk to the Telegram servers, such as to which IP the client should connect,
+port, authorization key so that messages can be encrypted, and so on.
+
+These files will by default also save all the input entities that you've seen,
+so that you can get information about a user or channel by just their ID.
+Telegram will **not** send their ``access_hash`` required to retrieve more
+information about them, if it thinks you have already seem them. For this
+reason, the library needs to store this information offline.
+
+The library will by default too save all the entities (chats and channels
+with their name and username, and users with the phone too) in the session
+file, so that you can quickly access them by username or phone number.
+
+If you're not going to work with updates, or don't need to cache the
+``access_hash`` associated with the entities' ID, you can disable this
+by setting ``client.session.save_entities = False``.
+
+
+Different Session Storage
+=========================
+
+If you don't want to use the default SQLite session storage, you can also
+use one of the other implementations or implement your own storage.
+
+While it's often not the case, it's possible that SQLite is slow enough to
+be noticeable, in which case you can also use a different storage. Note that
+this is rare and most people won't have this issue, but it's worth a mention.
+
+To use a custom session storage, simply pass the custom session instance to
+:ref:`TelegramClient <telethon-client>` instead of
+the session name.
+
+Telethon contains three implementations of the abstract ``Session`` class:
+
+.. currentmodule:: telethon.sessions
+
+* `MemorySession <memory.MemorySession>`: stores session data within memory.
+* `SQLiteSession <sqlite.SQLiteSession>`: stores sessions within on-disk SQLite databases. Default.
+* `StringSession <string.StringSession>`: stores session data within memory,
+  but can be saved as a string.
+
+You can import these ``from telethon.sessions``. For example, using the
+`StringSession <string.StringSession>` is done as follows:
+
+.. code-block:: python
+
+    from telethon.sync import TelegramClient
+    from telethon.sessions import StringSession
+
+    with TelegramClient(StringSession(string), api_id, api_hash) as client:
+        ...  # use the client
+
+        # Save the string session as a string; you should decide how
+        # you want to save this information (over a socket, remote
+        # database, print it and then paste the string in the code,
+        # etc.); the advantage is that you don't need to save it
+        # on the current disk as a separate file, and can be reused
+        # anywhere else once you log in.
+        string = client.session.save()
+
+    # Note that it's also possible to save any other session type
+    # as a string by using ``StringSession.save(session_instance)``:
+    client = TelegramClient('sqlite-session', api_id, api_hash)
+    string = StringSession.save(client.session)
+
+There are other community-maintained implementations available:
+
+* `SQLAlchemy <https://github.com/tulir/telethon-session-sqlalchemy>`_:
+  stores all sessions in a single database via SQLAlchemy.
+
+* `Redis <https://github.com/ezdev128/telethon-session-redis>`_:
+  stores all sessions in a single Redis data store.
+
+* `MongoDB <https://github.com/watzon/telethon-session-mongo>`_:
+  stores the current session in a MongoDB database.
+
+
+Creating your Own Storage
+=========================
+
+The easiest way to create your own storage implementation is to use
+`MemorySession <memory.MemorySession>` as the base and check out how
+`SQLiteSession <sqlite.SQLiteSession>` or one of the community-maintained
+implementations work. You can find the relevant Python files under the
+``sessions/`` directory in the Telethon's repository.
+
+After you have made your own implementation, you can add it to the
+community-maintained session implementation list above with a pull request.
+
+
+String Sessions
+===============
+
+`StringSession <string.StringSession>` are a convenient way to embed your
+login credentials directly into your code for extremely easy portability,
+since all they take is a string to be able to login without asking for your
+phone and code (or faster start if you're using a bot token).
+
+The easiest way to generate a string session is as follows:
+
+.. code-block:: python
+
+    from telethon.sync import TelegramClient
+    from telethon.sessions import StringSession
+
+    with TelegramClient(StringSession(), api_id, api_hash) as client:
+        print(client.session.save())
+
+
+Think of this as a way to export your authorization key (what's needed
+to login into your account). This will print a string in the standard
+output (likely your terminal).
+
+.. warning::
+
+    **Keep this string safe!** Anyone with this string can use it
+    to login into your account and do anything they want to.
+
+    This is similar to leaking your ``*.session`` files online,
+    but it is easier to leak a string than it is to leak a file.
+
+
+Once you have the string (which is a bit long), load it into your script
+somehow. You can use a normal text file and ``open(...).read()`` it or
+you can save it in a variable directly:
+
+.. code-block:: python
+
+    string = '1aaNk8EX-YRfwoRsebUkugFvht6DUPi_Q25UOCzOAqzc...'
+    with TelegramClient(StringSession(string), api_id, api_hash) as client:
+        client.loop.run_until_complete(client.send_message('me', 'Hi'))
+
+
+These strings are really convenient for using in places like Heroku since
+their ephemeral filesystem will delete external files once your application
+is over.

readthedocs/concepts/strings.rst

@@ -0,0 +1,88 @@
+======================
+String-based Debugging
+======================
+
+Debugging is *really* important. Telegram's API is really big and there
+are a lot of things that you should know. Such as, what attributes or fields
+does a result have? Well, the easiest thing to do is printing it:
+
+.. code-block:: python
+
+    entity = await client.get_entity('username')
+    print(entity)
+
+That will show a huge **string** similar to the following:
+
+.. code-block:: python
+
+    Channel(id=1066197625, title='Telegram Usernames', photo=ChatPhotoEmpty(), date=datetime.datetime(2016, 12, 16, 15, 15, 43, tzinfo=datetime.timezone.utc), version=0, creator=False, left=True, broadcast=True, verified=True, megagroup=False, restricted=False, signatures=False, min=False, scam=False, has_link=False, has_geo=False, slowmode_enabled=False, access_hash=-6309373984955162244, username='username', restriction_reason=[], admin_rights=None, banned_rights=None, default_banned_rights=None, participants_count=None)
+
+That's a lot of text. But as you can see, all the properties are there.
+So if you want the title you **don't use regex** or anything like
+splitting ``str(entity)`` to get what you want. You just access the
+attribute you need:
+
+.. code-block:: python
+
+    title = entity.title
+
+Can we get better than the shown string, though? Yes!
+
+.. code-block:: python
+
+    print(entity.stringify())
+
+Will show a much better representation:
+
+.. code-block:: python
+
+    Channel(
+        id=1066197625,
+        title='Telegram Usernames',
+        photo=ChatPhotoEmpty(
+        ),
+        date=datetime.datetime(2016, 12, 16, 15, 15, 43, tzinfo=datetime.timezone.utc),
+        version=0,
+        creator=False,
+        left=True,
+        broadcast=True,
+        verified=True,
+        megagroup=False,
+        restricted=False,
+        signatures=False,
+        min=False,
+        scam=False,
+        has_link=False,
+        has_geo=False,
+        slowmode_enabled=False,
+        access_hash=-6309373984955162244,
+        username='username',
+        restriction_reason=[
+        ],
+        admin_rights=None,
+        banned_rights=None,
+        default_banned_rights=None,
+        participants_count=None
+    )
+
+
+Now it's easy to see how we could get, for example,
+the ``year`` value. It's inside ``date``:
+
+.. code-block:: python
+
+    channel_year = entity.date.year
+
+You don't need to print everything to see what all the possible values
+can be. You can just search in http://tl.telethon.dev/.
+
+Remember that you can use Python's `isinstance
+<https://docs.python.org/3/library/functions.html#isinstance>`_
+to check the type of something. For example:
+
+.. code-block:: python
+
+    from telethon import types
+
+    if isinstance(entity.photo, types.ChatPhotoEmpty):
+        print('Channel has no photo')

readthedocs/concepts/updates.rst

@@ -0,0 +1,228 @@
+================
+Updates in Depth
+================
+
+Properties vs. Methods
+======================
+
+The event shown above acts just like a `custom.Message
+<telethon.tl.custom.message.Message>`, which means you
+can access all the properties it has, like ``.sender``.
+
+**However** events are different to other methods in the client, like
+`client.get_messages <telethon.client.messages.MessageMethods.get_messages>`.
+Events *may not* send information about the sender or chat, which means it
+can be `None`, but all the methods defined in the client always have this
+information so it doesn't need to be re-fetched. For this reason, you have
+``get_`` methods, which will make a network call if necessary.
+
+In short, you should do this:
+
+.. code-block:: python
+
+    @client.on(events.NewMessage)
+    async def handler(event):
+        # event.input_chat may be None, use event.get_input_chat()
+        chat = await event.get_input_chat()
+        sender = await event.get_sender()
+        buttons = await event.get_buttons()
+
+    async def main():
+        async for message in client.iter_messages('me', 10):
+            # Methods from the client always have these properties ready
+            chat = message.input_chat
+            sender = message.sender
+            buttons = message.buttons
+
+Notice, properties (`message.sender
+<telethon.tl.custom.message.Message.sender>`) don't need an ``await``, but
+methods (`message.get_sender
+<telethon.tl.custom.message.Message.get_sender>`) **do** need an ``await``,
+and you should use methods in events for these properties that may need network.
+
+Events Without the client
+=========================
+
+The code of your application starts getting big, so you decide to
+separate the handlers into different files. But how can you access
+the client from these files? You don't need to! Just `events.register
+<telethon.events.register>` them:
+
+.. code-block:: python
+
+    # handlers/welcome.py
+    from telethon import events
+
+    @events.register(events.NewMessage('(?i)hello'))
+    async def handler(event):
+        client = event.client
+        await event.respond('Hey!')
+        await client.send_message('me', 'I said hello to someone')
+
+
+Registering events is a way of saying "this method is an event handler".
+You can use `telethon.events.is_handler` to check if any method is a handler.
+You can think of them as a different approach to Flask's blueprints.
+
+It's important to note that this does **not** add the handler to any client!
+You never specified the client on which the handler should be used. You only
+declared that it is a handler, and its type.
+
+To actually use the handler, you need to `client.add_event_handler
+<telethon.client.updates.UpdateMethods.add_event_handler>` to the
+client (or clients) where they should be added to:
+
+.. code-block:: python
+
+    # main.py
+    from telethon import TelegramClient
+    import handlers.welcome
+
+    with TelegramClient(...) as client:
+        client.add_event_handler(handlers.welcome.handler)
+        client.run_until_disconnected()
+
+
+This also means that you can register an event handler once and
+then add it to many clients without re-declaring the event.
+
+
+Events Without Decorators
+=========================
+
+If for any reason you don't want to use `telethon.events.register`,
+you can explicitly pass the event handler to use to the mentioned
+`client.add_event_handler
+<telethon.client.updates.UpdateMethods.add_event_handler>`:
+
+.. code-block:: python
+
+    from telethon import TelegramClient, events
+
+    async def handler(event):
+        ...
+
+    with TelegramClient(...) as client:
+        client.add_event_handler(handler, events.NewMessage)
+        client.run_until_disconnected()
+
+
+Similarly, you also have `client.remove_event_handler
+<telethon.client.updates.UpdateMethods.remove_event_handler>`
+and `client.list_event_handlers
+<telethon.client.updates.UpdateMethods.list_event_handlers>`.
+
+The ``event`` argument is optional in all three methods and defaults to
+`events.Raw <telethon.events.raw.Raw>` for adding, and `None` when
+removing (so all callbacks would be removed).
+
+.. note::
+
+    The ``event`` type is ignored in `client.add_event_handler
+    <telethon.client.updates.UpdateMethods.add_event_handler>`
+    if you have used `telethon.events.register` on the ``callback``
+    before, since that's the point of using such method at all.
+
+
+Stopping Propagation of Updates
+===============================
+
+There might be cases when an event handler is supposed to be used solitary and
+it makes no sense to process any other handlers in the chain. For this case,
+it is possible to raise a `telethon.events.StopPropagation` exception which
+will cause the propagation of the update through your handlers to stop:
+
+.. code-block:: python
+
+    from telethon.events import StopPropagation
+
+    @client.on(events.NewMessage)
+    async def _(event):
+        # ... some conditions
+        await event.delete()
+
+        # Other handlers won't have an event to work with
+        raise StopPropagation
+
+    @client.on(events.NewMessage)
+    async def _(event):
+        # Will never be reached, because it is the second handler
+        # in the chain.
+        pass
+
+
+Remember to check :ref:`telethon-events` if you're looking for
+the methods reference.
+
+Understanding asyncio
+=====================
+
+
+With `asyncio`, the library has several tasks running in the background.
+One task is used for sending requests, another task is used to receive them,
+and a third one is used to handle updates.
+
+To handle updates, you must keep your script running. You can do this in
+several ways. For instance, if you are *not* running `asyncio`'s event
+loop, you should use `client.run_until_disconnected
+<telethon.client.updates.UpdateMethods.run_until_disconnected>`:
+
+.. code-block:: python
+
+    import asyncio
+    from telethon import TelegramClient
+
+    client = TelegramClient(...)
+    ...
+    client.run_until_disconnected()
+
+
+Behind the scenes, this method is ``await``'ing on the `client.disconnected
+<telethon.client.telegrambaseclient.TelegramBaseClient.disconnected>` property,
+so the code above and the following are equivalent:
+
+.. code-block:: python
+
+    import asyncio
+    from telethon import TelegramClient
+
+    client = TelegramClient(...)
+
+    async def main():
+        await client.disconnected
+
+    asyncio.run(main())
+
+
+You could also run `client.disconnected
+<telethon.client.telegrambaseclient.TelegramBaseClient.disconnected>`
+until it completed.
+
+But if you don't want to ``await``, then you should know what you want
+to be doing instead! What matters is that you shouldn't let your script
+die. If you don't care about updates, you don't need any of this.
+
+Notice that unlike `client.disconnected
+<telethon.client.telegrambaseclient.TelegramBaseClient.disconnected>`,
+`client.run_until_disconnected
+<telethon.client.updates.UpdateMethods.run_until_disconnected>` will
+handle ``KeyboardInterrupt`` for you. This method is special and can
+also be ran while the loop is running, so you can do this:
+
+.. code-block:: python
+
+    async def main():
+        await client.run_until_disconnected()
+
+    loop.run_until_complete(main())
+
+Sequential Updates
+==================
+
+If you need to process updates sequentially (i.e. not in parallel),
+you should set ``sequential_updates=True`` when creating the client:
+
+.. code-block:: python
+
+    with TelegramClient(..., sequential_updates=True) as client:
+        ...

readthedocs/conf.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# Telethon documentation build configuration file, created by
+# sphinx-quickstart on Fri Nov 17 15:36:11 2017.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import re
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(os.curdir))
+sys.path.insert(0, os.path.abspath(os.pardir))
+
+root = os.path.abspath(os.path.join(__file__, os.path.pardir, os.path.pardir))
+
+tl_ref_url = 'https://tl.telethon.dev'
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
+    'custom_roles'
+]
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None)
+}
+
+# Change the default role so we can avoid prefixing everything with :obj:
+default_role = "py:obj"
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'Telethon'
+copyright = '2017 - 2019, Lonami'
+author = 'Lonami'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+with open(os.path.join(root, 'telethon', 'version.py'), 'r') as f:
+    version = re.search(r"^__version__\s+=\s+'(.*)'$",
+                        f.read(), flags=re.MULTILINE).group(1)
+
+# The full version, including alpha/beta/rc tags.
+release = version
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = 'en'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'friendly'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+def skip(app, what, name, obj, would_skip, options):
+    if name.endswith('__'):
+        # We want to show special methods names, except some which add clutter
+        return name in {
+            '__init__',
+            '__abstractmethods__',
+            '__module__',
+            '__doc__',
+            '__dict__'
+        }
+
+    return would_skip
+
+
+def setup(app):
+    app.connect("autodoc-skip-member", skip)
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+html_theme_options = {
+    'collapse_navigation': True,
+    'display_version': True,
+    'navigation_depth': 3,
+}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# This is required for the alabaster theme
+# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
+html_sidebars = {
+    '**': [
+        'globaltoc.html',
+        'relations.html',  # needs 'show_related': True theme option to display
+        'searchbox.html',
+    ]
+}
+
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Telethondoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'Telethon.tex', 'Telethon Documentation',
+     author, 'manual'),
+]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'telethon', 'Telethon Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'Telethon', 'Telethon Documentation',
+     author, 'Telethon', 'One line description of project.',
+     'Miscellaneous'),
+]
+

readthedocs/custom_roles.py

@@ -0,0 +1,67 @@
+from docutils import nodes, utils
+from docutils.parsers.rst.roles import set_classes
+
+
+def make_link_node(rawtext, app, name, options):
+    """
+    Create a link to the TL reference.
+
+    :param rawtext: Text being replaced with link node.
+    :param app: Sphinx application context
+    :param name: Name of the object to link to
+    :param options: Options dictionary passed to role func.
+    """
+    try:
+        base = app.config.tl_ref_url
+        if not base:
+            raise AttributeError
+    except AttributeError as e:
+        raise ValueError('tl_ref_url config value is not set') from e
+
+    if base[-1] != '/':
+        base += '/'
+
+    set_classes(options)
+    node = nodes.reference(rawtext, utils.unescape(name),
+                           refuri='{}?q={}'.format(base, name),
+                           **options)
+    return node
+
+
+# noinspection PyUnusedLocal
+def tl_role(name, rawtext, text, lineno, inliner, options=None, content=None):
+    """
+    Link to the TL reference.
+
+    Returns 2 part tuple containing list of nodes to insert into the
+    document and a list of system messages. Both are allowed to be empty.
+
+    :param name: The role name used in the document.
+    :param rawtext: The entire markup snippet, with role.
+    :param text: The text marked with the role.
+    :param lineno: The line number where rawtext appears in the input.
+    :param inliner: The inliner instance that called us.
+    :param options: Directive options for customization.
+    :param content: The directive content for customization.
+    """
+    if options is None:
+        options = {}
+
+    # TODO Report error on type not found?
+    # Usage:
+    #   msg = inliner.reporter.error(..., line=lineno)
+    #   return [inliner.problematic(rawtext, rawtext, msg)], [msg]
+    app = inliner.document.settings.env.app
+    node = make_link_node(rawtext, app, text, options)
+    return [node], []
+
+
+def setup(app):
+    """
+    Install the plugin.
+
+    :param app: Sphinx application context.
+    """
+    app.add_role('tl', tl_role)
+    app.add_config_value('tl_ref_url', None, 'env')
+    return

readthedocs/developing/coding-style.rst

@@ -0,0 +1,22 @@
+============
+Coding Style
+============
+
+
+Basically, make it **readable**, while keeping the style similar to the
+code of whatever file you're working on.
+
+Also note that not everyone has 4K screens for their primary monitors,
+so please try to stick to the 80-columns limit. This makes it easy to
+``git diff`` changes from a terminal before committing changes. If the
+line has to be long, please don't exceed 120 characters.
+
+For the commit messages, please make them *explanatory*. Not only
+they're helpful to troubleshoot when certain issues could have been
+introduced, but they're also used to construct the change log once a new
+version is ready.
+
+If you don't know enough Python, I strongly recommend reading `Dive Into
+Python 3 <http://www.diveintopython3.net/>`__, available online for
+free. For instance, remember to do ``if x is None`` or
+``if x is not None`` instead ``if x == None``!

readthedocs/developing/philosophy.rst

@@ -0,0 +1,25 @@
+==========
+Philosophy
+==========
+
+
+The intention of the library is to have an existing MTProto library
+existing with hardly any dependencies (indeed, wherever Python is
+available, you can run this library).
+
+Being written in Python means that performance will be nowhere close to
+other implementations written in, for instance, Java, C++, Rust, or
+pretty much any other compiled language. However, the library turns out
+to actually be pretty decent for common operations such as sending
+messages, receiving updates, or other scripting. Uploading files may be
+notably slower, but if you would like to contribute, pull requests are
+appreciated!
+
+If ``libssl`` is available on your system, the library will make use of
+it to speed up some critical parts such as encrypting and decrypting the
+messages. Files will notably be sent and downloaded faster.
+
+The main focus is to keep everything clean and simple, for everyone to
+understand how working with MTProto and Telegram works. Don't be afraid
+to read the source, the code won't bite you! It may prove useful when
+using the library on your own use cases.

readthedocs/developing/project-structure.rst

@@ -0,0 +1,51 @@
+=================
+Project Structure
+=================
+
+
+Main interface
+==============
+
+The library itself is under the ``telethon/`` directory. The
+``__init__.py`` file there exposes the main ``TelegramClient``, a class
+that servers as a nice interface with the most commonly used methods on
+Telegram such as sending messages, retrieving the message history,
+handling updates, etc.
+
+The ``TelegramClient`` inherits from several mixing ``Method`` classes,
+since there are so many methods that having them in a single file would
+make maintenance painful (it was three thousand lines before this separation
+happened!). It's a "god object", but there is only a way to interact with
+Telegram really.
+
+The ``TelegramBaseClient`` is an ABC which will support all of these mixins
+so they can work together nicely. It doesn't even know how to invoke things
+because they need to be resolved with user information first (to work with
+input entities comfortably).
+
+The client makes use of the ``network/mtprotosender.py``. The
+``MTProtoSender`` is responsible for connecting, reconnecting,
+packing, unpacking, sending and receiving items from the network.
+Basically, the low-level communication with Telegram, and handling
+MTProto-related functions and types such as ``BadSalt``.
+
+The sender makes use of a ``Connection`` class which knows the format in
+which outgoing messages should be sent (how to encode their length and
+their body, if they're further encrypted).
+
+Auto-generated code
+===================
+
+The files under ``telethon_generator/`` are used to generate the code
+that gets placed under ``telethon/tl/``. The parsers take in files in
+a specific format (such as ``.tl`` for objects and ``.json`` for errors)
+and spit out the generated classes which represent, as Python classes,
+the request and types defined in the ``.tl`` file. It also constructs
+an index so that they can be imported easily.
+
+Custom documentation can also be generated to easily navigate through
+the vast amount of items offered by the API.
+
+If you clone the repository, you will have to run ``python setup.py gen``
+in order to generate the code. Installing the library runs the generator
+too, but the mentioned command will just generate code.

readthedocs/developing/telegram-api-in-other-languages.rst

@@ -0,0 +1,13 @@
+===============================
+Telegram API in Other Languages
+===============================
+
+Telethon was made for **Python**, and it has inspired other libraries such as
+`gramjs <https://github.com/gram-js/gramjs>`__ (JavaScript) and `grammers
+<https://github.com/Lonami/grammers>`__ (Rust). But there is a lot more beyond
+those, made independently by different developers.
+
+If you're looking for something like Telethon but in a different programming
+language, head over to `Telegram API in Other Languages in the official wiki
+<https://github.com/LonamiWebs/Telethon/wiki/Telegram-API-in-Other-Languages>`__
+for a (mostly) up-to-date list.

readthedocs/developing/test-servers.rst

@@ -0,0 +1,41 @@
+============
+Test Servers
+============
+
+
+To run Telethon on a test server, use the following code:
+
+.. code-block:: python
+
+    client = TelegramClient(None, api_id, api_hash)
+    client.session.set_dc(dc_id, '149.154.167.40', 80)
+
+You can check your ``'test ip'`` on https://my.telegram.org.
+
+You should set `None` session so to ensure you're generating a new
+authorization key for it (it would fail if you used a session where you
+had previously connected to another data center).
+
+Note that port 443 might not work, so you can try with 80 instead.
+
+Once you're connected, you'll likely be asked to either sign in or sign up.
+Remember `anyone can access the phone you
+choose <https://core.telegram.org/api/datacenter#testing-redirects>`__,
+so don't store sensitive data here.
+
+Valid phone numbers are ``99966XYYYY``, where ``X`` is the ``dc_id`` and
+``YYYY`` is any number you want, for example, ``1234`` in ``dc_id = 2`` would
+be ``9996621234``. The code sent by Telegram will be ``dc_id`` repeated five
+times, in this case, ``22222`` so we can hardcode that:
+
+.. code-block:: python
+
+    client = TelegramClient(None, api_id, api_hash)
+    client.session.set_dc(2, '149.154.167.40', 80)
+    client.start(
+        phone='9996621234', code_callback=lambda: '22222'
+    )
+
+Note that Telegram has changed the length of login codes multiple times in the
+past, so if ``dc_id`` repeated five times does not work, try repeating it six
+times.

readthedocs/developing/testing.rst

@@ -0,0 +1,87 @@
+=====
+Tests
+=====
+
+Telethon uses `Pytest <https://pytest.org/>`__, for testing, `Tox
+<https://tox.readthedocs.io/en/latest/>`__ for environment setup, and
+`pytest-asyncio <https://pypi.org/project/pytest-asyncio/>`__ and `pytest-cov
+<https://pytest-cov.readthedocs.io/en/latest/>`__ for asyncio and 
+`coverage <https://coverage.readthedocs.io/>`__ integration.
+
+While reading the full documentation for these is probably a good idea, there
+is a lot to read, so a brief summary of these tools is provided below for
+convienience.
+
+Brief Introduction to Pytest
+============================
+
+`Pytest <https://pytest.org/>`__ is a tool for discovering and running python
+tests, as well as allowing modular reuse of test setup code using fixtures.
+
+Most Pytest tests will look something like this::
+
+    from module import my_thing, my_other_thing
+
+    def test_my_thing(fixture):
+        assert my_thing(fixture) == 42
+
+    @pytest.mark.asyncio
+    async def test_my_thing(event_loop):
+        assert await my_other_thing(loop=event_loop) == 42
+
+Note here:
+
+ 1. The test imports one specific function. The role of unit tests is to test
+    that the implementation of some unit, like a function or class, works.
+    It's role is not so much to test that components interact well with each
+    other. I/O, such as connecting to remote servers, should be avoided. This
+    helps with quickly identifying the source of an error, finding silent
+    breakage, and makes it easier to cover all possible code paths.
+
+    System or integration tests can also be useful, but are currently out of
+    scope of Telethon's automated testing.
+
+ 2. A function ``test_my_thing`` is declared. Pytest searches for files
+    starting with ``test_``, classes starting with ``Test`` and executes any
+    functions or methods starting with ``test_`` it finds.
+
+ 3. The function is declared with a parameter ``fixture``. Fixtures are used to
+    request things required to run the test, such as temporary directories,
+    free TCP ports, Connections, etc. Fixtures are declared by simply adding
+    the fixture name as parameter. A full list of available fixtures can be
+    found with the ``pytest --fixtures`` command.
+
+ 4. The test uses a simple ``assert`` to test some condition is valid.  Pytest
+    uses some magic to ensure that the errors from this are readable and easy
+    to debug.
+
+ 5. The ``pytest.mark.asyncio`` fixture is provided by ``pytest-asyncio``. It
+    starts a loop and executes a test function as coroutine. This should be
+    used for testing asyncio code. It also declares the ``event_loop``
+    fixture, which will request an ``asyncio`` event loop.
+
+Brief Introduction to Tox
+=========================
+
+`Tox <https://tox.readthedocs.io/en/latest/>`__ is a tool for automated setup
+of virtual environments for testing. While the tests can be run directly by
+just running ``pytest``, this only tests one specific python version in your
+existing environment, which will not catch e.g. undeclared dependencies, or
+version incompatabilities.
+
+Tox environments are declared in the ``tox.ini`` file. The default
+environments, declared at the top, can be simply run with ``tox``. The option
+``tox -e py36,flake`` can be used to request specific environments to be run.
+
+Brief Introduction to Pytest-cov
+================================
+
+Coverage is a useful metric for testing. It measures the lines of code and
+branches that are exercised by the tests. The higher the coverage, the more
+likely it is that any coding errors will be caught by the tests.
+
+A brief coverage report can be generated with the ``--cov`` option to ``tox``,
+which will be passed on to ``pytest``. Additionally, the very useful HTML
+report can be generated with ``--cov --cov-report=html``, which contains a
+browsable copy of the source code, annotated with coverage information for each
+line.

readthedocs/developing/tips-for-porting-the-project.rst

@@ -0,0 +1,17 @@
+============================
+Tips for Porting the Project
+============================
+
+
+If you're going to use the code on this repository to guide you, please
+be kind and don't forget to mention it helped you!
+
+You should start by reading the source code on the `first
+release <https://github.com/LonamiWebs/Telethon/releases/tag/v0.1>`__ of
+the project, and start creating a ``MTProtoSender``. Once this is made,
+you should write by hand the code to authenticate on the Telegram's
+server, which are some steps required to get the key required to talk to
+them. Save it somewhere! Then, simply mimic, or reinvent other parts of
+the code, and it will be ready to go within a few days.
+
+Good luck!

readthedocs/developing/understanding-the-type-language.rst

@@ -0,0 +1,33 @@
+===============================
+Understanding the Type Language
+===============================
+
+
+`Telegram's Type Language <https://core.telegram.org/mtproto/TL>`__
+(also known as TL, found on ``.tl`` files) is a concise way to define
+what other programming languages commonly call classes or structs.
+
+Every definition is written as follows for a Telegram object is defined
+as follows:
+
+    ``name#id argument_name:argument_type = CommonType``
+
+This means that in a single line you know what the ``TLObject`` name is.
+You know it's unique ID, and you know what arguments it has. It really
+isn't that hard to write a generator for generating code to any
+platform!
+
+The generated code should also be able to *encode* the ``TLObject`` (let
+this be a request or a type) into bytes, so they can be sent over the
+network. This isn't a big deal either, because you know how the
+``TLObject``\ 's are made, and how the types should be serialized.
+
+You can either write your own code generator, or use the one this
+library provides, but please be kind and keep some special mention to
+this project for helping you out.
+
+This is only a introduction. The ``TL`` language is not *that* easy. But
+it's not that hard either. You're free to sniff the
+``telethon_generator/`` files and learn how to parse other more complex
+lines, such as ``flags`` (to indicate things that may or may not be
+written at all) and ``vector``\ 's.

readthedocs/examples/chats-and-channels.rst

@@ -0,0 +1,128 @@
+===============================
+Working with Chats and Channels
+===============================
+
+
+.. note::
+
+    These examples assume you have read :ref:`full-api`.
+
+.. contents::
+
+
+Joining a chat or channel
+=========================
+
+Note that :tl:`Chat` are normal groups, and :tl:`Channel` are a
+special form of :tl:`Chat`, which can also be super-groups if
+their ``megagroup`` member is `True`.
+
+
+Joining a public channel
+========================
+
+Once you have the :ref:`entity <entities>` of the channel you want to join
+to, you can make use of the :tl:`JoinChannelRequest` to join such channel:
+
+.. code-block:: python
+
+    from telethon.tl.functions.channels import JoinChannelRequest
+    await client(JoinChannelRequest(channel))
+
+    # In the same way, you can also leave such channel
+    from telethon.tl.functions.channels import LeaveChannelRequest
+    await client(LeaveChannelRequest(input_channel))
+
+
+For more on channels, check the `channels namespace`__.
+
+
+__ https://tl.telethon.dev/methods/channels/index.html
+
+
+Joining a private chat or channel
+=================================
+
+If all you have is a link like this one:
+``https://t.me/joinchat/AAAAAFFszQPyPEZ7wgxLtd``, you already have
+enough information to join! The part after the
+``https://t.me/joinchat/``, this is, ``AAAAAFFszQPyPEZ7wgxLtd`` on this
+example, is the ``hash`` of the chat or channel. Now you can use
+:tl:`ImportChatInviteRequest` as follows:
+
+.. code-block:: python
+
+    from telethon.tl.functions.messages import ImportChatInviteRequest
+    updates = await client(ImportChatInviteRequest('AAAAAEHbEkejzxUjAUCfYg'))
+
+
+Adding someone else to such chat or channel
+===========================================
+
+If you don't want to add yourself, maybe because you're already in,
+you can always add someone else with the :tl:`AddChatUserRequest`, which
+use is very straightforward, or :tl:`InviteToChannelRequest` for channels:
+
+.. code-block:: python
+
+    # For normal chats
+    from telethon.tl.functions.messages import AddChatUserRequest
+
+    # Note that ``user_to_add`` is NOT the name of the parameter.
+    # It's the user you want to add (``user_id=user_to_add``).
+    await client(AddChatUserRequest(
+        chat_id,
+        user_to_add,
+        fwd_limit=10  # Allow the user to see the 10 last messages
+    ))
+
+    # For channels (which includes megagroups)
+    from telethon.tl.functions.channels import InviteToChannelRequest
+
+    await client(InviteToChannelRequest(
+        channel,
+        [users_to_add]
+    ))
+
+Note that this method will only really work for friends or bot accounts.
+Trying to mass-add users with this approach will not work, and can put both
+your account and group to risk, possibly being flagged as spam and limited.
+
+
+Checking a link without joining
+===============================
+
+If you don't need to join but rather check whether it's a group or a
+channel, you can use the :tl:`CheckChatInviteRequest`, which takes in
+the hash of said channel or group.
+
+
+Increasing View Count in a Channel
+==================================
+
+It has been asked `quite`__ `a few`__ `times`__ (really, `many`__), and
+while I don't understand why so many people ask this, the solution is to
+use :tl:`GetMessagesViewsRequest`, setting ``increment=True``:
+
+.. code-block:: python
+
+
+    # Obtain `channel' through dialogs or through client.get_entity() or anyhow.
+    # Obtain `msg_ids' through `.get_messages()` or anyhow. Must be a list.
+
+    await client(GetMessagesViewsRequest(
+        peer=channel,
+        id=msg_ids,
+        increment=True
+    ))
+
+
+Note that you can only do this **once or twice a day** per account,
+running this in a loop will obviously not increase the views forever
+unless you wait a day between each iteration. If you run it any sooner
+than that, the views simply won't be increased.
+
+__ https://github.com/LonamiWebs/Telethon/issues/233
+__ https://github.com/LonamiWebs/Telethon/issues/305
+__ https://github.com/LonamiWebs/Telethon/issues/409
+__ https://github.com/LonamiWebs/Telethon/issues/447

readthedocs/examples/users.rst

@@ -0,0 +1,74 @@
+=====
+Users
+=====
+
+
+.. note::
+
+    These examples assume you have read :ref:`full-api`.
+
+.. contents::
+
+
+Retrieving full information
+===========================
+
+If you need to retrieve the bio, biography or about information for a user
+you should use :tl:`GetFullUser`:
+
+
+.. code-block:: python
+
+    from telethon.tl.functions.users import GetFullUserRequest
+
+    full = await client(GetFullUserRequest(user))
+    # or even
+    full = await client(GetFullUserRequest('username'))
+
+    bio = full.full_user.about
+
+
+See :tl:`UserFull` to know what other fields you can access.
+
+
+Updating your name and/or bio
+=============================
+
+The first name, last name and bio (about) can all be changed with the same
+request. Omitted fields won't change after invoking :tl:`UpdateProfile`:
+
+.. code-block:: python
+
+    from telethon.tl.functions.account import UpdateProfileRequest
+
+    await client(UpdateProfileRequest(
+        about='This is a test from Telethon'
+    ))
+
+
+Updating your username
+======================
+
+You need to use :tl:`account.UpdateUsername`:
+
+.. code-block:: python
+
+    from telethon.tl.functions.account import UpdateUsernameRequest
+
+    await client(UpdateUsernameRequest('new_username'))
+
+
+Updating your profile photo
+===========================
+
+The easiest way is to upload a new file and use that as the profile photo
+through :tl:`UploadProfilePhoto`:
+
+
+.. code-block:: python
+
+    from telethon.tl.functions.photos import UploadProfilePhotoRequest
+
+    await client(UploadProfilePhotoRequest(
+        await client.upload_file('/path/to/some/file')
+    ))

readthedocs/examples/word-of-warning.rst

@@ -0,0 +1,17 @@
+=================
+A Word of Warning
+=================
+
+Full API is **not** how you are intended to use the library. You **should**
+always prefer the :ref:`client-ref`. However, not everything is implemented
+as a friendly method, so full API is your last resort.
+
+If you select a method in :ref:`client-ref`, you will most likely find an
+example for that method. This is how you are intended to use the library.
+
+Full API **will** break between different minor versions of the library,
+since Telegram changes very often. The friendly methods will be kept
+compatible between major versions.
+
+If you need to see real-world examples, please refer to the
+`wiki page of projects using Telethon <https://github.com/LonamiWebs/Telethon/wiki/Projects-using-Telethon>`__.

readthedocs/examples/working-with-messages.rst

@@ -0,0 +1,13 @@
+=====================
+Working with messages
+=====================
+
+.. note::
+
+    These examples assume you have read :ref:`full-api`.
+
+This section has been `moved to the wiki`_, where it can be easily edited as new
+features arrive and the API changes. Please refer to the linked page to learn how
+to send spoilers, custom emoji, stickers, react to messages, and more things.
+
+.. _moved to the wiki: https://github.com/LonamiWebs/Telethon/wiki/Sending-more-than-just-messages

readthedocs/index.rst

@@ -0,0 +1,119 @@
+========================
+Telethon's Documentation
+========================
+
+.. code-block:: python
+
+   from telethon.sync import TelegramClient, events
+
+   with TelegramClient('name', api_id, api_hash) as client:
+      client.send_message('me', 'Hello, myself!')
+      print(client.download_profile_photo('me'))
+
+      @client.on(events.NewMessage(pattern='(?i).*Hello'))
+      async def handler(event):
+         await event.reply('Hey!')
+
+      client.run_until_disconnected()
+
+
+* Are you new here? Jump straight into :ref:`installation`!
+* Looking for the method reference? See :ref:`client-ref`.
+* Did you upgrade the library? Please read :ref:`changelog`.
+* Used Telethon before v1.0? See :ref:`compatibility-and-convenience`.
+* Coming from Bot API or want to create new bots? See :ref:`botapi`.
+* Need the full API reference? https://tl.telethon.dev/.
+
+
+What is this?
+-------------
+
+Telegram is a popular messaging application. This library is meant
+to make it easy for you to write Python programs that can interact
+with Telegram. Think of it as a wrapper that has already done the
+heavy job for you, so you can focus on developing an application.
+
+
+How should I use the documentation?
+-----------------------------------
+
+If you are getting started with the library, you should follow the
+documentation in order by pressing the "Next" button at the bottom-right
+of every page.
+
+You can also use the menu on the left to quickly skip over sections.
+
+.. toctree::
+    :hidden:
+    :caption: First Steps
+
+    basic/installation
+    basic/signing-in
+    basic/quick-start
+    basic/updates
+    basic/next-steps
+
+.. toctree::
+    :hidden:
+    :caption: Quick References
+
+    quick-references/faq
+    quick-references/client-reference
+    quick-references/events-reference
+    quick-references/objects-reference
+
+.. toctree::
+    :hidden:
+    :caption: Concepts
+
+    concepts/strings
+    concepts/entities
+    concepts/chats-vs-channels
+    concepts/updates
+    concepts/sessions
+    concepts/full-api
+    concepts/errors
+    concepts/botapi-vs-mtproto
+    concepts/asyncio
+
+.. toctree::
+    :hidden:
+    :caption: Full API Examples
+
+    examples/word-of-warning
+    examples/chats-and-channels
+    examples/users
+    examples/working-with-messages
+
+.. toctree::
+    :hidden:
+    :caption: Developing
+
+    developing/philosophy.rst
+    developing/test-servers.rst
+    developing/project-structure.rst
+    developing/coding-style.rst
+    developing/testing.rst
+    developing/understanding-the-type-language.rst
+    developing/tips-for-porting-the-project.rst
+    developing/telegram-api-in-other-languages.rst
+
+.. toctree::
+    :hidden:
+    :caption: Miscellaneous
+
+    misc/changelog
+    misc/compatibility-and-convenience
+
+.. toctree::
+    :hidden:
+    :caption: Telethon Modules
+
+    modules/client
+    modules/events
+    modules/custom
+    modules/utils
+    modules/errors
+    modules/sessions
+    modules/network
+    modules/helpers

readthedocs/make.bat

@@ -0,0 +1,36 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+set SPHINXPROJ=Telethon
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

readthedocs/misc/compatibility-and-convenience.rst

@@ -0,0 +1,185 @@
+.. _compatibility-and-convenience:
+
+=============================
+Compatibility and Convenience
+=============================
+
+Telethon is an `asyncio` library. Compatibility is an important concern,
+and while it can't always be kept and mistakes happens, the :ref:`changelog`
+is there to tell you when these important changes happen.
+
+.. contents::
+
+
+Compatibility
+=============
+
+Some decisions when developing will inevitable be proven wrong in the future.
+One of these decisions was using threads. Now that Python 3.4 is reaching EOL
+and using `asyncio` is usable as of Python 3.5 it makes sense for a library
+like Telethon to make a good use of it.
+
+If you have old code, **just use old versions** of the library! There is
+nothing wrong with that other than not getting new updates or fixes, but
+using a fixed version with ``pip install telethon==0.19.1.6`` is easy
+enough to do.
+
+You might want to consider using `Virtual Environments
+<https://docs.python.org/3/tutorial/venv.html>`_ in your projects.
+
+There's no point in maintaining a synchronous version because the whole point
+is that people don't have time to upgrade, and there has been several changes
+and clean-ups. Using an older version is the right way to go.
+
+Sometimes, other small decisions are made. These all will be reflected in the
+:ref:`changelog` which you should read when upgrading.
+
+If you want to jump the `asyncio` boat, here are some of the things you will
+need to start migrating really old code:
+
+.. code-block:: python
+
+    # 1. Import the client from telethon.sync
+    from telethon.sync import TelegramClient
+
+    # 2. Change this monster...
+    try:
+        assert client.connect()
+        if not client.is_user_authorized():
+            client.send_code_request(phone_number)
+            me = client.sign_in(phone_number, input('Enter code: '))
+
+        ...  # REST OF YOUR CODE
+    finally:
+        client.disconnect()
+
+    # ...for this:
+    with client:
+        ...  # REST OF YOUR CODE
+
+    # 3. client.idle() no longer exists.
+    # Change this...
+    client.idle()
+    # ...to this:
+    client.run_until_disconnected()
+
+    # 4. client.add_update_handler no longer exists.
+    # Change this...
+    client.add_update_handler(handler)
+    # ...to this:
+    client.add_event_handler(handler)
+
+
+In addition, all the update handlers must be ``async def``, and you need
+to ``await`` method calls that rely on network requests, such as getting
+the chat or sender. If you don't use updates, you're done!
+
+
+Convenience
+===========
+
+.. note::
+
+    The entire documentation assumes you have done one of the following:
+
+    .. code-block:: python
+
+        from telethon import TelegramClient, sync
+        # or
+        from telethon.sync import TelegramClient
+
+    This makes the examples shorter and easier to think about.
+
+For quick scripts that don't need updates, it's a lot more convenient to
+forget about `asyncio` and just work with sequential code. This can prove
+to be a powerful hybrid for running under the Python REPL too.
+
+.. code-block:: python
+
+    from telethon.sync import TelegramClient
+    #            ^~~~~ note this part; it will manage the asyncio loop for you
+
+    with TelegramClient(...) as client:
+        print(client.get_me().username)
+        #     ^ notice the lack of await, or loop.run_until_complete().
+        #       Since there is no loop running, this is done behind the scenes.
+        #
+        message = client.send_message('me', 'Hi!')
+        import time
+        time.sleep(5)
+        message.delete()
+
+        # You can also have an hybrid between a synchronous
+        # part and asynchronous event handlers.
+        #
+        from telethon import events
+        @client.on(events.NewMessage(pattern='(?i)hi|hello'))
+        async def handler(event):
+            await event.reply('hey')
+
+        client.run_until_disconnected()
+
+
+Some methods, such as ``with``, ``start``, ``disconnect`` and
+``run_until_disconnected`` work both in synchronous and asynchronous
+contexts by default for convenience, and to avoid the little overhead
+it has when using methods like sending a message, getting messages, etc.
+This keeps the best of both worlds as a sane default.
+
+.. note::
+
+    As a rule of thumb, if you're inside an ``async def`` and you need
+    the client, you need to ``await`` calls to the API. If you call other
+    functions that also need API calls, make them ``async def`` and ``await``
+    them too. Otherwise, there is no need to do so with this mode.
+
+Speed
+=====
+
+When you're ready to micro-optimize your application, or if you simply
+don't need to call any non-basic methods from a synchronous context,
+just get rid of ``telethon.sync`` and work inside an ``async def``:
+
+.. code-block:: python
+
+    import asyncio
+    from telethon import TelegramClient, events
+
+    async def main():
+        async with TelegramClient(...) as client:
+            print((await client.get_me()).username)
+            #     ^_____________________^ notice these parenthesis
+            #     You want to ``await`` the call, not the username.
+            #
+            message = await client.send_message('me', 'Hi!')
+            await asyncio.sleep(5)
+            await message.delete()
+
+            @client.on(events.NewMessage(pattern='(?i)hi|hello'))
+            async def handler(event):
+                await event.reply('hey')
+
+            await client.run_until_disconnected()
+
+    asyncio.run(main())
+
+
+The ``telethon.sync`` magic module essentially wraps every method behind:
+
+.. code-block:: python
+
+    asyncio.run(main())
+
+With some other tricks, so that you don't have to write it yourself every time.
+That's the overhead you pay if you import it, and what you save if you don't.
+
+Learning
+========
+
+You know the library uses `asyncio` everywhere, and you want to learn
+how to do things right. Even though `asyncio` is its own topic, the
+documentation wants you to learn how to use Telethon correctly, and for
+that, you need to use `asyncio` correctly too. For this reason, there
+is a section called :ref:`mastering-asyncio` that will introduce you to
+the `asyncio` world, with links to more resources for learning how to
+use it. Feel free to check that section out once you have read the rest.

readthedocs/modules/client.rst

@@ -0,0 +1,103 @@
+.. _telethon-client:
+
+==============
+TelegramClient
+==============
+
+.. currentmodule:: telethon.client
+
+The `TelegramClient <telegramclient.TelegramClient>` aggregates several mixin
+classes to provide all the common functionality in a nice, Pythonic interface.
+Each mixin has its own methods, which you all can use.
+
+**In short, to create a client you must run:**
+
+.. code-block:: python
+
+    from telethon import TelegramClient
+
+    client = TelegramClient(name, api_id, api_hash)
+
+    async def main():
+        # Now you can use all client methods listed below, like for example...
+        await client.send_message('me', 'Hello to myself!')
+
+    with client:
+        client.loop.run_until_complete(main())
+
+
+You **don't** need to import these `AuthMethods`, `MessageMethods`, etc.
+Together they are the `TelegramClient <telegramclient.TelegramClient>` and
+you can access all of their methods.
+
+See :ref:`client-ref` for a short summary.
+
+.. automodule:: telethon.client.telegramclient
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.client.telegrambaseclient
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.client.account
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.client.auth
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.client.bots
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.client.buttons
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.client.chats
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.client.dialogs
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.client.downloads
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.client.messageparse
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.client.messages
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.client.updates
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.client.uploads
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.client.users
+    :members:
+    :undoc-members:
+    :show-inheritance:

readthedocs/modules/custom.rst

@@ -0,0 +1,163 @@
+==============
+Custom package
+==============
+
+The `telethon.tl.custom` package contains custom classes that the library
+uses in order to make working with Telegram easier. Only those that you
+are supposed to use will be documented here. You can use undocumented ones
+at your own risk.
+
+More often than not, you don't need to import these (unless you want
+type hinting), nor do you need to manually create instances of these
+classes. They are returned by client methods.
+
+.. contents::
+
+.. automodule:: telethon.tl.custom
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+AdminLogEvent
+=============
+
+.. automodule:: telethon.tl.custom.adminlogevent
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Button
+======
+
+.. automodule:: telethon.tl.custom.button
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+ChatGetter
+==========
+
+.. automodule:: telethon.tl.custom.chatgetter
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Conversation
+============
+
+.. automodule:: telethon.tl.custom.conversation
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Dialog
+======
+
+.. automodule:: telethon.tl.custom.dialog
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Draft
+=====
+
+.. automodule:: telethon.tl.custom.draft
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+File
+====
+
+.. automodule:: telethon.tl.custom.file
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Forward
+=======
+
+.. automodule:: telethon.tl.custom.forward
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+InlineBuilder
+=============
+
+.. automodule:: telethon.tl.custom.inlinebuilder
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+InlineResult
+============
+
+.. automodule:: telethon.tl.custom.inlineresult
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+InlineResults
+=============
+
+.. automodule:: telethon.tl.custom.inlineresults
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Message
+=======
+
+.. automodule:: telethon.tl.custom.message
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+MessageButton
+=============
+
+.. automodule:: telethon.tl.custom.messagebutton
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+ParticipantPermissions
+======================
+
+.. automodule:: telethon.tl.custom.participantpermissions
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+QRLogin
+=======
+
+.. automodule:: telethon.tl.custom.qrlogin
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+SenderGetter
+============
+
+.. automodule:: telethon.tl.custom.sendergetter
+    :members:
+    :undoc-members:
+    :show-inheritance:

readthedocs/modules/errors.rst

@@ -0,0 +1,20 @@
+.. _telethon-errors:
+
+==========
+API Errors
+==========
+
+These are the base errors that Telegram's API may raise.
+
+See :ref:`rpc-errors` for a more in-depth explanation on how to handle all
+known possible errors and learning to determine what a method may raise.
+
+.. automodule:: telethon.errors.common
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.errors.rpcbaseerrors
+    :members:
+    :undoc-members:
+    :show-inheritance:

readthedocs/modules/events.rst

@@ -0,0 +1,70 @@
+.. _telethon-events:
+
+=============
+Update Events
+=============
+
+.. currentmodule:: telethon.events
+
+Every event (builder) subclasses `common.EventBuilder`,
+so all the methods in it can be used from any event builder/event instance.
+
+.. automodule:: telethon.events.common
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.events.newmessage
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.events.chataction
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.events.userupdate
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.events.messageedited
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.events.messagedeleted
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.events.messageread
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.events.callbackquery
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.events.inlinequery
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.events.album
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.events.raw
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.events
+    :members:
+    :undoc-members:
+    :show-inheritance:

readthedocs/modules/helpers.rst

@@ -0,0 +1,8 @@
+=======
+Helpers
+=======
+
+.. automodule:: telethon.helpers
+    :members:
+    :undoc-members:
+    :show-inheritance:

readthedocs/modules/network.rst

@@ -0,0 +1,33 @@
+.. _telethon-network:
+
+================
+Connection Modes
+================
+
+The only part about network that you should worry about are
+the different connection modes, which are the following:
+
+.. automodule:: telethon.network.connection.tcpfull
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.network.connection.tcpabridged
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.network.connection.tcpintermediate
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.network.connection.tcpobfuscated
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.network.connection.http
+    :members:
+    :undoc-members:
+    :show-inheritance:

readthedocs/modules/sessions.rst

@@ -0,0 +1,27 @@
+.. _telethon-sessions:
+
+========
+Sessions
+========
+
+These are the different built-in session storage that you may subclass.
+
+.. automodule:: telethon.sessions.abstract
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.sessions.memory
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.sessions.sqlite
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: telethon.sessions.string
+    :members:
+    :undoc-members:
+    :show-inheritance:

readthedocs/modules/utils.rst

@@ -0,0 +1,12 @@
+.. _telethon-utils:
+
+=========
+Utilities
+=========
+
+These are the utilities that the library has to offer.
+
+.. automodule:: telethon.utils
+    :members:
+    :undoc-members:
+    :show-inheritance:

readthedocs/quick-references/client-reference.rst

@@ -0,0 +1,202 @@
+.. _client-ref:
+
+================
+Client Reference
+================
+
+This page contains a summary of all the important methods and properties that
+you may need when using Telethon. They are sorted by relevance and are not in
+alphabetical order.
+
+You should use this page to learn about which methods are available, and
+if you need a usage example or further description of the arguments, be
+sure to follow the links.
+
+.. contents::
+
+TelegramClient
+==============
+
+This is a summary of the methods and
+properties you will find at :ref:`telethon-client`.
+
+Auth
+----
+
+.. currentmodule:: telethon.client.auth.AuthMethods
+
+.. autosummary::
+    :nosignatures:
+
+    start
+    send_code_request
+    sign_in
+    qr_login
+    log_out
+    edit_2fa
+
+Base
+----
+
+.. py:currentmodule:: telethon.client.telegrambaseclient.TelegramBaseClient
+
+.. autosummary::
+    :nosignatures:
+
+    connect
+    disconnect
+    is_connected
+    disconnected
+    loop
+    set_proxy
+
+Messages
+--------
+
+.. py:currentmodule:: telethon.client.messages.MessageMethods
+
+.. autosummary::
+    :nosignatures:
+
+    send_message
+    edit_message
+    delete_messages
+    forward_messages
+    iter_messages
+    get_messages
+    pin_message
+    unpin_message
+    send_read_acknowledge
+
+Uploads
+-------
+
+.. py:currentmodule:: telethon.client.uploads.UploadMethods
+
+.. autosummary::
+    :nosignatures:
+
+    send_file
+    upload_file
+
+Downloads
+---------
+
+.. currentmodule:: telethon.client.downloads.DownloadMethods
+
+.. autosummary::
+    :nosignatures:
+
+    download_media
+    download_profile_photo
+    download_file
+    iter_download
+
+Dialogs
+-------
+
+.. py:currentmodule:: telethon.client.dialogs.DialogMethods
+
+.. autosummary::
+    :nosignatures:
+
+    iter_dialogs
+    get_dialogs
+    edit_folder
+    iter_drafts
+    get_drafts
+    delete_dialog
+    conversation
+
+Users
+-----
+
+.. py:currentmodule:: telethon.client.users.UserMethods
+
+.. autosummary::
+    :nosignatures:
+
+    get_me
+    is_bot
+    is_user_authorized
+    get_entity
+    get_input_entity
+    get_peer_id
+
+Chats
+-----
+
+.. currentmodule:: telethon.client.chats.ChatMethods
+
+.. autosummary::
+    :nosignatures:
+
+    iter_participants
+    get_participants
+    kick_participant
+    iter_admin_log
+    get_admin_log
+    iter_profile_photos
+    get_profile_photos
+    edit_admin
+    edit_permissions
+    get_permissions
+    get_stats
+    action
+
+Parse Mode
+----------
+
+.. py:currentmodule:: telethon.client.messageparse.MessageParseMethods
+
+.. autosummary::
+    :nosignatures:
+
+    parse_mode
+
+Updates
+-------
+
+.. py:currentmodule:: telethon.client.updates.UpdateMethods
+
+.. autosummary::
+    :nosignatures:
+
+    on
+    run_until_disconnected
+    add_event_handler
+    remove_event_handler
+    list_event_handlers
+    catch_up
+    set_receive_updates
+
+Bots
+----
+
+.. currentmodule:: telethon.client.bots.BotMethods
+
+.. autosummary::
+    :nosignatures:
+
+    inline_query
+
+Buttons
+-------
+
+.. currentmodule:: telethon.client.buttons.ButtonMethods
+
+.. autosummary::
+    :nosignatures:
+
+    build_reply_markup
+
+Account
+-------
+
+.. currentmodule:: telethon.client.account.AccountMethods
+
+.. autosummary::
+    :nosignatures:
+
+    takeout
+    end_takeout

readthedocs/quick-references/events-reference.rst

@@ -0,0 +1,247 @@
+================
+Events Reference
+================
+
+Here you will find a quick summary of all the methods
+and properties that you can access when working with events.
+
+You can access the client that creates this event by doing
+``event.client``, and you should view the description of the
+events to find out what arguments it allows on creation and
+its **attributes** (the properties will be shown here).
+
+.. important::
+
+    Remember that **all events base** `ChatGetter
+    <telethon.tl.custom.chatgetter.ChatGetter>`! Please see :ref:`faq`
+    if you don't know what this means or the implications of it.
+
+.. contents::
+
+
+NewMessage
+==========
+
+Occurs whenever a new text message or a message with media arrives.
+
+.. note::
+
+    The new message event **should be treated as** a
+    normal `Message <telethon.tl.custom.message.Message>`, with
+    the following exceptions:
+
+    * ``pattern_match`` is the match object returned by ``pattern=``.
+    * ``message`` is **not** the message string. It's the `Message
+      <telethon.tl.custom.message.Message>` object.
+
+    Remember, this event is just a proxy over the message, so while
+    you won't see its attributes and properties, you can still access
+    them. Please see the full documentation for examples.
+
+Full documentation for the `NewMessage
+<telethon.events.newmessage.NewMessage>`.
+
+
+MessageEdited
+=============
+
+Occurs whenever a message is edited. Just like `NewMessage
+<telethon.events.newmessage.NewMessage>`, you should treat
+this event as a `Message <telethon.tl.custom.message.Message>`.
+
+Full documentation for the `MessageEdited
+<telethon.events.messageedited.MessageEdited>`.
+
+
+MessageDeleted
+==============
+
+Occurs whenever a message is deleted. Note that this event isn't 100%
+reliable, since Telegram doesn't always notify the clients that a message
+was deleted.
+
+It only has the ``deleted_id`` and ``deleted_ids`` attributes
+(in addition to the chat if the deletion happened in a channel).
+
+Full documentation for the `MessageDeleted
+<telethon.events.messagedeleted.MessageDeleted>`.
+
+
+MessageRead
+===========
+
+Occurs whenever one or more messages are read in a chat.
+
+Full documentation for the `MessageRead
+<telethon.events.messageread.MessageRead>`.
+
+.. currentmodule:: telethon.events.messageread.MessageRead.Event
+
+.. autosummary::
+    :nosignatures:
+
+        inbox
+        message_ids
+
+        get_messages
+        is_read
+
+
+ChatAction
+==========
+
+Occurs on certain chat actions, such as chat title changes,
+user join or leaves, pinned messages, photo changes, etc.
+
+Full documentation for the `ChatAction
+<telethon.events.chataction.ChatAction>`.
+
+.. currentmodule:: telethon.events.chataction.ChatAction.Event
+
+.. autosummary::
+    :nosignatures:
+
+        added_by
+        kicked_by
+        user
+        input_user
+        user_id
+        users
+        input_users
+        user_ids
+
+        respond
+        reply
+        delete
+        get_pinned_message
+        get_added_by
+        get_kicked_by
+        get_user
+        get_input_user
+        get_users
+        get_input_users
+
+
+UserUpdate
+==========
+
+Occurs whenever a user goes online, starts typing, etc.
+
+Full documentation for the `UserUpdate
+<telethon.events.userupdate.UserUpdate>`.
+
+.. currentmodule:: telethon.events.userupdate.UserUpdate.Event
+
+.. autosummary::
+    :nosignatures:
+
+        user
+        input_user
+        user_id
+
+        get_user
+        get_input_user
+
+        typing
+        uploading
+        recording
+        playing
+        cancel
+        geo
+        audio
+        round
+        video
+        contact
+        document
+        photo
+        last_seen
+        until
+        online
+        recently
+        within_weeks
+        within_months
+
+
+CallbackQuery
+=============
+
+Occurs whenever you sign in as a bot and a user
+clicks one of the inline buttons on your messages.
+
+Full documentation for the `CallbackQuery
+<telethon.events.callbackquery.CallbackQuery>`.
+
+.. currentmodule:: telethon.events.callbackquery.CallbackQuery.Event
+
+.. autosummary::
+    :nosignatures:
+
+        id
+        message_id
+        data
+        chat_instance
+        via_inline
+
+        respond
+        reply
+        edit
+        delete
+        answer
+        get_message
+
+InlineQuery
+===========
+
+Occurs whenever you sign in as a bot and a user
+sends an inline query such as ``@bot query``.
+
+Full documentation for the `InlineQuery
+<telethon.events.inlinequery.InlineQuery>`.
+
+.. currentmodule:: telethon.events.inlinequery.InlineQuery.Event
+
+.. autosummary::
+    :nosignatures:
+
+        id
+        text
+        offset
+        geo
+        builder
+
+        answer
+
+Album
+=====
+
+Occurs whenever you receive an entire album.
+
+Full documentation for the `Album
+<telethon.events.album.Album>`.
+
+.. currentmodule:: telethon.events.album.Album.Event
+
+.. autosummary::
+    :nosignatures:
+
+        grouped_id
+        text
+        raw_text
+        is_reply
+        forward
+
+        get_reply_message
+        respond
+        reply
+        forward_to
+        edit
+        delete
+        mark_read
+        pin
+
+Raw
+===
+
+Raw events are not actual events. Instead, they are the raw
+:tl:`Update` object that Telegram sends. You normally shouldn't
+need these.

readthedocs/quick-references/faq.rst

@@ -0,0 +1,423 @@
+.. _faq:
+
+===
+FAQ
+===
+
+Let's start the quick references section with some useful tips to keep in
+mind, with the hope that you will understand why certain things work the
+way that they do.
+
+.. contents::
+
+
+Code without errors doesn't work
+================================
+
+Then it probably has errors, but you haven't enabled logging yet.
+To enable logging, at the following code to the top of your main file:
+
+.. code-block:: python
+
+    import logging
+    logging.basicConfig(format='[%(levelname) %(asctime)s] %(name)s: %(message)s',
+                        level=logging.WARNING)
+
+You can change the logging level to be something different, from less to more information:
+
+.. code-block:: python
+
+    level=logging.CRITICAL  # won't show errors (same as disabled)
+    level=logging.ERROR     # will only show errors that you didn't handle
+    level=logging.WARNING   # will also show messages with medium severity, such as internal Telegram issues
+    level=logging.INFO      # will also show informational messages, such as connection or disconnections
+    level=logging.DEBUG     # will show a lot of output to help debugging issues in the library
+
+See the official Python documentation for more information on logging_.
+
+
+How can I except FloodWaitError?
+================================
+
+You can use all errors from the API by importing:
+
+.. code-block:: python
+
+    from telethon import errors
+
+And except them as such:
+
+.. code-block:: python
+
+    try:
+        await client.send_message(chat, 'Hi')
+    except errors.FloodWaitError as e:
+        # e.seconds is how many seconds you have
+        # to wait before making the request again.
+        print('Flood for', e.seconds)
+
+
+My account was deleted/limited when using the library
+=====================================================
+
+First and foremost, **this is not a problem exclusive to Telethon.
+Any third-party library is prone to cause the accounts to appear banned.**
+Even official applications can make Telegram ban an account under certain
+circumstances. Third-party libraries such as Telethon are a lot easier to
+use, and as such, they are misused to spam, which causes Telegram to learn
+certain patterns and ban suspicious activity.
+
+There is no point in Telethon trying to circumvent this. Even if it succeeded,
+spammers would then abuse the library again, and the cycle would repeat.
+
+The library will only do things that you tell it to do. If you use
+the library with bad intentions, Telegram will hopefully ban you.
+
+However, you may also be part of a limited country, such as Iran or Russia.
+In that case, we have bad news for you. Telegram is much more likely to ban
+these numbers, as they are often used to spam other accounts, likely through
+the use of libraries like this one. The best advice we can give you is to not
+abuse the API, like calling many requests really quickly.
+
+We have also had reports from Kazakhstan and China, where connecting
+would fail. To solve these connection problems, you should use a proxy.
+
+Telegram may also ban virtual (VoIP) phone numbers,
+as again, they're likely to be used for spam.
+
+More recently (year 2023 onwards), Telegram has started putting a lot more
+measures to prevent spam (with even additions such as anonymous participants
+in groups or the inability to fetch group members at all). This means some
+of the anti-spam measures have gotten more aggressive.
+
+The recommendation has usually been to use the library only on well-established
+accounts (and not an account you just created), and to not perform actions that
+could be seen as abuse. Telegram decides what those actions are, and they're
+free to change how they operate at any time.
+
+If you want to check if your account has been limited,
+simply send a private message to `@SpamBot`_ through Telegram itself.
+You should notice this by getting errors like ``PeerFloodError``,
+which means you're limited, for instance,
+when sending a message to some accounts but not others.
+
+For more discussion, please see `issue 297`_.
+
+
+How can I use a proxy?
+======================
+
+This was one of the first things described in :ref:`signing-in`.
+
+
+How do I access a field?
+========================
+
+This is basic Python knowledge. You should use the dot operator:
+
+.. code-block:: python
+
+    me = await client.get_me()
+    print(me.username)
+    #       ^ we used the dot operator to access the username attribute
+
+    result = await client(functions.photos.GetUserPhotosRequest(
+        user_id='me',
+        offset=0,
+        max_id=0,
+        limit=100
+    ))
+
+    # Working with list is also pretty basic
+    print(result.photos[0].sizes[-1].type)
+    #           ^       ^ ^       ^ ^
+    #           |       | |       | \ type
+    #           |       | |       \ last size
+    #           |       | \ list of sizes
+    #  access   |       \ first photo from the list
+    #  the...   \ list of photos
+    #
+    # To print all, you could do (or mix-and-match):
+    for photo in result.photos:
+        for size in photo.sizes:
+            print(size.type)
+
+
+AttributeError: 'coroutine' object has no attribute 'id'
+========================================================
+
+You either forgot to:
+
+.. code-block:: python
+
+    import telethon.sync
+    #              ^^^^^ import sync
+
+Or:
+
+.. code-block:: python
+
+    async def handler(event):
+        me = await client.get_me()
+        #    ^^^^^ note the await
+        print(me.username)
+
+
+sqlite3.OperationalError: database is locked
+============================================
+
+An older process is still running and is using the same ``'session'`` file.
+
+This error occurs when **two or more clients use the same session**,
+that is, when you write the same session name to be used in the client:
+
+* You have an older process using the same session file.
+* You have two different scripts running (interactive sessions count too).
+* You have two clients in the same script running at the same time.
+
+The solution is, if you need two clients, use two sessions. If the
+problem persists and you're on Linux, you can use ``fuser my.session``
+to find out the process locking the file. As a last resort, you can
+reboot your system.
+
+If you really dislike SQLite, use a different session storage. There
+is an entire section covering that at :ref:`sessions`.
+
+
+event.chat or event.sender is None
+==================================
+
+Telegram doesn't always send this information in order to save bandwidth.
+If you need the information, you should fetch it yourself, since the library
+won't do unnecessary work unless you need to:
+
+.. code-block:: python
+
+    async def handler(event):
+        chat = await event.get_chat()
+        sender = await event.get_sender()
+
+
+File download is slow or sending files takes too long
+=====================================================
+
+The communication with Telegram is encrypted. Encryption requires a lot of
+math, and doing it in pure Python is very slow. ``cryptg`` is a library which
+containns the encryption functions used by Telethon. If it is installed (via
+``pip install cryptg``), it will automatically be used and should provide
+a considerable speed boost. You can know whether it's used by configuring
+``logging`` (at ``INFO`` level or lower) *before* importing ``telethon``.
+
+Note that the library does *not* download or upload files in parallel, which
+can also help with the speed of downloading or uploading a single file. There
+are snippets online implementing that. The reason why this is not built-in
+is because the limiting factor in the long run are ``FloodWaitError``, and
+using parallel download or uploads only makes them occur sooner.
+
+
+What does "Server sent a very new message with ID" mean?
+========================================================
+
+You may also see this error as "Server sent a very old message with ID".
+
+This is a security feature from Telethon that cannot be disabled and is
+meant to protect you against replay attacks.
+
+When this message is incorrectly reported as a "bug",
+the most common patterns seem to be:
+
+* Your system time is incorrect.
+* The proxy you're using may be interfering somehow.
+* The Telethon session is being used or has been used from somewhere else.
+  Make sure that you created the session from Telethon, and are not using the
+  same session anywhere else. If you need to use the same account from
+  multiple places, login and use a different session for each place you need.
+
+
+What does "Server replied with a wrong session ID" mean?
+========================================================
+
+This is a security feature from Telethon that cannot be disabled and is
+meant to protect you against unwanted session reuse.
+
+When this message is reported as a "bug", the most common patterns seem to be:
+
+* The proxy you're using may be interfering somehow.
+* The Telethon session is being used or has been used from somewhere else.
+  Make sure that you created the session from Telethon, and are not using the
+  same session anywhere else. If you need to use the same account from
+  multiple places, login and use a different session for each place you need.
+* You may be using multiple connections to the Telegram server, which seems
+  to confuse Telegram.
+
+Most of the time it should be safe to ignore this warning. If the library
+still doesn't behave correctly, make sure to check if any of the above bullet
+points applies in your case and try to work around it.
+
+If the issue persists and there is a way to reliably reproduce this error,
+please add a comment with any additional details you can provide to
+`issue 3759`_, and perhaps some additional investigation can be done
+(but it's unlikely, as Telegram *is* sending unexpected data).
+
+
+What does "Could not find a matching Constructor ID for the TLObject" mean?
+===========================================================================
+
+Telegram uses "layers", which you can think of as "versions" of the API they
+offer. When Telethon reads responses that the Telegram servers send, these
+need to be deserialized (into what Telethon calls "TLObjects").
+
+Every Telethon version understands a single Telegram layer. When Telethon
+connects to Telegram, both agree on the layer to use. If the layers don't
+match, Telegram may send certain objects which Telethon no longer understands.
+
+When this message is reported as a "bug", the most common patterns seem to be
+that the Telethon session is being used or has been used from somewhere else.
+Make sure that you created the session from Telethon, and are not using the
+same session anywhere else. If you need to use the same account from
+multiple places, login and use a different session for each place you need.
+
+
+What does "Task was destroyed but it is pending" mean?
+======================================================
+
+Your script likely finished abruptly, the ``asyncio`` event loop got
+destroyed, and the library did not get a chance to properly close the
+connection and close the session.
+
+Make sure you're either using the context manager for the client or always
+call ``await client.disconnect()`` (by e.g. using a ``try/finally``).
+
+
+What does "The asyncio event loop must not change after connection" mean?
+=========================================================================
+
+Telethon uses ``asyncio``, and makes use of things like tasks and queues
+internally to manage the connection to the server and match responses to the
+requests you make. Most of them are initialized after the client is connected.
+
+For example, if the library expects a result to a request made in loop A, but
+you attempt to get that result in loop B, you will very likely find a deadlock.
+To avoid a deadlock, the library checks to make sure the loop in use is the
+same as the one used to initialize everything, and if not, it throws an error.
+
+The most common cause is ``asyncio.run``, since it creates a new event loop.
+If you ``asyncio.run`` a function to create the client and set it up, and then
+you ``asyncio.run`` another function to do work, things won't work, so the
+library throws an error early to let you know something is wrong.
+
+Instead, it's often a good idea to have a single ``async def main`` and simply
+``asyncio.run()`` it and do all the work there. From it, you're also able to
+call other ``async def`` without having to touch ``asyncio.run`` again:
+
+.. code-block:: python
+
+    # It's fine to create the client outside as long as you don't connect
+    client = TelegramClient(...)
+
+    async def main():
+        # Now the client will connect, so the loop must not change from now on.
+        # But as long as you do all the work inside main, including calling
+        # other async functions, things will work.
+        async with client:
+            ....
+
+    if __name__ == '__main__':
+        asyncio.run(main())
+
+Be sure to read the ``asyncio`` documentation if you want a better
+understanding of event loop, tasks, and what functions you can use.
+
+
+What does "bases ChatGetter" mean?
+==================================
+
+In Python, classes can base others. This is called `inheritance
+<https://ddg.gg/python%20inheritance>`_. What it means is that
+"if a class bases another, you can use the other's methods too".
+
+For example, `Message <telethon.tl.custom.message.Message>` *bases*
+`ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>`. In turn,
+`ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>` defines
+things like `obj.chat_id <telethon.tl.custom.chatgetter.ChatGetter>`.
+
+So if you have a message, you can access that too:
+
+.. code-block:: python
+
+    # ChatGetter has a chat_id property, and Message bases ChatGetter.
+    # Thus you can use ChatGetter properties and methods from Message
+    print(message.chat_id)
+
+
+Telegram has a lot to offer, and inheritance helps the library reduce
+boilerplate, so it's important to know this concept. For newcomers,
+this may be a problem, so we explain what it means here in the FAQ.
+
+Can I send files by ID?
+=======================
+
+When people talk about IDs, they often refer to one of two things:
+the integer ID inside media, and a random-looking long string.
+
+You cannot use the integer ID to send media. Generally speaking, sending media
+requires a combination of ID, ``access_hash`` and ``file_reference``.
+The first two are integers, while the last one is a random ``bytes`` sequence.
+
+* The integer ``id`` will always be the same for every account, so every user
+  or bot looking at a particular media file, will see a consistent ID.
+* The ``access_hash`` will always be the same for a given account, but
+  different accounts will each see their own, different ``access_hash``.
+  This makes it impossible to get media object from one account and use it in
+  another. The other account must fetch the media object itself.
+* The ``file_reference`` is random for everyone and will only work for a few
+  hours before it expires. It must be refetched before the media can be used
+  (to either resend the media or download it).
+
+The second type of "`file ID <https://core.telegram.org/bots/api#inputfile>`_"
+people refer to is a concept from the HTTP Bot API. It's a custom format which
+encodes enough information to use the media.
+
+Telethon provides an old version of these HTTP Bot API-style file IDs via
+``message.file.id``, however, this feature is no longer maintained, so it may
+not work. It will be removed in future versions. Nonetheless, it is possible
+to find a different Python package (or write your own) to parse these file IDs
+and construct the necessary input file objects to send or download the media.
+
+
+Can I use Flask with the library?
+=================================
+
+Yes, if you know what you are doing. However, you will probably have a
+lot of headaches to get threads and asyncio to work together. Instead,
+consider using `Quart <https://pgjones.gitlab.io/quart/>`_, an asyncio-based
+alternative to `Flask <flask.pocoo.org/>`_.
+
+Check out `quart_login.py`_ for an example web-application based on Quart.
+
+Can I use Anaconda/Spyder/IPython with the library?
+===================================================
+
+Yes, but these interpreters run the asyncio event loop implicitly,
+which interferes with the ``telethon.sync`` magic module.
+
+If you use them, you should **not** import ``sync``:
+
+.. code-block:: python
+
+    # Change any of these...:
+    from telethon import TelegramClient, sync, ...
+    from telethon.sync import TelegramClient, ...
+
+    # ...with this:
+    from telethon import TelegramClient, ...
+
+You are also more likely to get "sqlite3.OperationalError: database is locked"
+with them. If they cause too much trouble, just write your code in a ``.py``
+file and run that, or use the normal ``python`` interpreter.
+
+.. _logging: https://docs.python.org/3/library/logging.html
+.. _@SpamBot: https://t.me/SpamBot
+.. _issue 297: https://github.com/LonamiWebs/Telethon/issues/297
+.. _issue 3759: https://github.com/LonamiWebs/Telethon/issues/3759
+.. _quart_login.py: https://github.com/LonamiWebs/Telethon/tree/v1/telethon_examples#quart_loginpy

readthedocs/quick-references/objects-reference.rst

@@ -0,0 +1,353 @@
+=================
+Objects Reference
+=================
+
+This is the quick reference for those objects returned by client methods
+or other useful modules that the library has to offer. They are kept in
+a separate page to help finding and discovering them.
+
+Remember that this page only shows properties and methods,
+**not attributes**. Make sure to open the full documentation
+to find out about the attributes.
+
+.. contents::
+
+
+ChatGetter
+==========
+
+All events base `ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>`,
+and some of the objects below do too, so it's important to know its methods.
+
+.. currentmodule:: telethon.tl.custom.chatgetter.ChatGetter
+
+.. autosummary::
+    :nosignatures:
+
+    chat
+    input_chat
+    chat_id
+    is_private
+    is_group
+    is_channel
+
+    get_chat
+    get_input_chat
+
+
+SenderGetter
+============
+
+Similar to `ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>`, a
+`SenderGetter <telethon.tl.custom.sendergetter.SenderGetter>` is the same,
+but it works for senders instead.
+
+.. currentmodule:: telethon.tl.custom.sendergetter.SenderGetter
+
+.. autosummary::
+    :nosignatures:
+
+    sender
+    input_sender
+    sender_id
+
+    get_sender
+    get_input_sender
+
+
+Message
+=======
+
+.. currentmodule:: telethon.tl.custom.message
+
+The `Message` type is very important, mostly because we are working
+with a library for a *messaging* platform, so messages are widely used:
+in events, when fetching history, replies, etc.
+
+It bases `ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>` and
+`SenderGetter <telethon.tl.custom.sendergetter.SenderGetter>`.
+
+Properties
+----------
+
+.. note::
+
+    We document *custom properties* here, not all the attributes of the
+    `Message` (which is the information Telegram actually returns).
+
+.. currentmodule:: telethon.tl.custom.message.Message
+
+.. autosummary::
+    :nosignatures:
+
+    text
+    raw_text
+    is_reply
+    forward
+    buttons
+    button_count
+    file
+    photo
+    document
+    web_preview
+    audio
+    voice
+    video
+    video_note
+    gif
+    sticker
+    contact
+    game
+    geo
+    invoice
+    poll
+    venue
+    action_entities
+    via_bot
+    via_input_bot
+    client
+
+
+Methods
+-------
+
+.. autosummary::
+    :nosignatures:
+
+    respond
+    reply
+    forward_to
+    edit
+    delete
+    get_reply_message
+    click
+    mark_read
+    pin
+    download_media
+    get_entities_text
+    get_buttons
+
+
+File
+====
+
+The `File <telethon.tl.custom.file.File>` type is a wrapper object
+returned by `Message.file <telethon.tl.custom.message.Message.file>`,
+and you can use it to easily access a document's attributes, such as
+its name, bot-API style file ID, etc.
+
+.. currentmodule:: telethon.tl.custom.file.File
+
+.. autosummary::
+    :nosignatures:
+
+    id
+    name
+    ext
+    mime_type
+    width
+    height
+    size
+    duration
+    title
+    performer
+    emoji
+    sticker_set
+
+
+Conversation
+============
+
+The `Conversation <telethon.tl.custom.conversation.Conversation>` object
+is returned by the `client.conversation()
+<telethon.client.dialogs.DialogMethods.conversation>` method to easily
+send and receive responses like a normal conversation.
+
+It bases `ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>`.
+
+.. currentmodule:: telethon.tl.custom.conversation.Conversation
+
+.. autosummary::
+    :nosignatures:
+
+    send_message
+    send_file
+    mark_read
+    get_response
+    get_reply
+    get_edit
+    wait_read
+    wait_event
+    cancel
+    cancel_all
+
+
+AdminLogEvent
+=============
+
+The `AdminLogEvent <telethon.tl.custom.adminlogevent.AdminLogEvent>` object
+is returned by the `client.iter_admin_log()
+<telethon.client.chats.ChatMethods.iter_admin_log>` method to easily iterate
+over past "events" (deleted messages, edits, title changes, leaving members…)
+
+These are all the properties you can find in it:
+
+.. currentmodule:: telethon.tl.custom.adminlogevent.AdminLogEvent
+
+.. autosummary::
+    :nosignatures:
+
+    id
+    date
+    user_id
+    action
+    old
+    new
+    changed_about
+    changed_title
+    changed_username
+    changed_photo
+    changed_sticker_set
+    changed_message
+    deleted_message
+    changed_admin
+    changed_restrictions
+    changed_invites
+    joined
+    joined_invite
+    left
+    changed_hide_history
+    changed_signatures
+    changed_pin
+    changed_default_banned_rights
+    stopped_poll
+
+
+Button
+======
+
+The `Button <telethon.tl.custom.button.Button>` class is used when you login
+as a bot account to send messages with reply markup, such as inline buttons
+or custom keyboards.
+
+These are the static methods you can use to create instances of the markup:
+
+.. currentmodule:: telethon.tl.custom.button.Button
+
+.. autosummary::
+    :nosignatures:
+
+    inline
+    switch_inline
+    url
+    auth
+    text
+    request_location
+    request_phone
+    request_poll
+    clear
+    force_reply
+
+
+InlineResult
+============
+
+The `InlineResult <telethon.tl.custom.inlineresult.InlineResult>` object
+is returned inside a list by the `client.inline_query()
+<telethon.client.bots.BotMethods.inline_query>` method to make an inline
+query to a bot that supports being used in inline mode, such as
+`@like <https://t.me/like>`_.
+
+Note that the list returned is in fact a *subclass* of a list called
+`InlineResults <telethon.tl.custom.inlineresults.InlineResults>`, which,
+in addition of being a list (iterator, indexed access, etc.), has extra
+attributes and methods.
+
+These are the constants for the types, properties and methods you
+can find the individual results:
+
+.. currentmodule:: telethon.tl.custom.inlineresult.InlineResult
+
+.. autosummary::
+    :nosignatures:
+
+    ARTICLE
+    PHOTO
+    GIF
+    VIDEO
+    VIDEO_GIF
+    AUDIO
+    DOCUMENT
+    LOCATION
+    VENUE
+    CONTACT
+    GAME
+    type
+    message
+    title
+    description
+    url
+    photo
+    document
+    click
+    download_media
+
+
+Dialog
+======
+
+The `Dialog <telethon.tl.custom.dialog.Dialog>` object is returned when
+you call `client.iter_dialogs() <telethon.client.dialogs.DialogMethods.iter_dialogs>`.
+
+.. currentmodule:: telethon.tl.custom.dialog.Dialog
+
+.. autosummary::
+    :nosignatures:
+
+    send_message
+    archive
+    delete
+
+
+Draft
+======
+
+The `Draft <telethon.tl.custom.draft.Draft>` object is returned when
+you call `client.iter_drafts() <telethon.client.dialogs.DialogMethods.iter_drafts>`.
+
+.. currentmodule:: telethon.tl.custom.draft.Draft
+
+.. autosummary::
+    :nosignatures:
+
+    entity
+    input_entity
+    get_entity
+    get_input_entity
+    text
+    raw_text
+    is_empty
+    set_message
+    send
+    delete
+
+
+Utils
+=====
+
+The `telethon.utils` module has plenty of methods that make using the
+library a lot easier. Only the interesting ones will be listed here.
+
+.. currentmodule:: telethon.utils
+
+.. autosummary::
+    :nosignatures:
+
+    get_display_name
+    get_extension
+    get_inner_text
+    get_peer_id
+    resolve_id
+    pack_bot_file_id
+    resolve_bot_file_id
+    resolve_invite_link

readthedocs/requirements.txt

@@ -0,0 +1,2 @@
+./
+sphinx-rtd-theme~=1.3.0

requirements.txt

@@ -0,0 +1,2 @@
+pyaes
+rsa

run_tests.py

@@ -1,24 +0,0 @@
-#!/usr/bin/env python3
-import unittest
-
-if __name__ == '__main__':
-    from telethon_tests import \
-        CryptoTests, ParserTests, TLTests, UtilsTests, NetworkTests
-
-    test_classes = [CryptoTests, ParserTests, TLTests, UtilsTests]
-
-    network = input('Run network tests (y/n)?: ').lower() == 'y'
-    if network:
-        test_classes.append(NetworkTests)
-
-    loader = unittest.TestLoader()
-
-    suites_list = []
-    for test_class in test_classes:
-        suite = loader.loadTestsFromTestCase(test_class)
-        suites_list.append(suite)
-
-    big_suite = unittest.TestSuite(suites_list)
-
-    runner = unittest.TextTestRunner()
-    results = runner.run(big_suite)

setup.py

@@ -6,96 +6,213 @@ https://packaging.python.org/en/latest/distributing.html
 https://github.com/pypa/sampleproject
 
 Extra supported commands are:
-* gen_tl, to generate the classes required for Telethon to run
-* clean_tl, to clean these generated classes
+* gen, to generate the classes required for Telethon to run or docs
 * pypi, to generate sdist, bdist_wheel, and push to PyPi
 """
 
-# To use a consistent encoding
-from codecs import open
-from sys import argv
+import itertools
+import json
 import os
+import re
+import shutil
+import sys
+import urllib.request
+from pathlib import Path
+from subprocess import run
 
-# Always prefer setuptools over distutils
 from setuptools import find_packages, setup
 
-try:
-    from telethon import TelegramClient
-except Exception as e:
-    print('Failed to import TelegramClient due to', e)
-    TelegramClient = None
-
+# Needed since we're importing local files
+sys.path.insert(0, os.path.dirname(__file__))
 
 class TempWorkDir:
     """Switches the working directory to be the one on which this file lives,
        while within the 'with' block.
     """
-    def __init__(self):
+    def __init__(self, new=None):
         self.original = None
+        self.new = new or str(Path(__file__).parent.resolve())
 
     def __enter__(self):
-        self.original = os.path.abspath(os.path.curdir)
-        os.chdir(os.path.abspath(os.path.dirname(__file__)))
+        # os.chdir does not work with Path in Python 3.5.x
+        self.original = str(Path('.').resolve())
+        os.makedirs(self.new, exist_ok=True)
+        os.chdir(self.new)
         return self
 
     def __exit__(self, *args):
         os.chdir(self.original)
 
 
-def gen_tl():
-    from telethon_generator.tl_generator import TLGenerator
-    generator = TLGenerator('telethon/tl')
-    if generator.tlobjects_exist():
-        print('Detected previous TLObjects. Cleaning...')
-        generator.clean_tlobjects()
+API_REF_URL = 'https://tl.telethon.dev/'
 
-    print('Generating TLObjects...')
-    generator.generate_tlobjects(
-        'telethon_generator/scheme.tl', import_depth=2
-    )
-    print('Done.')
+GENERATOR_DIR = Path('telethon_generator')
+LIBRARY_DIR = Path('telethon')
+
+ERRORS_IN = GENERATOR_DIR / 'data/errors.csv'
+ERRORS_OUT = LIBRARY_DIR / 'errors/rpcerrorlist.py'
+
+METHODS_IN = GENERATOR_DIR / 'data/methods.csv'
+
+# Which raw API methods are covered by *friendly* methods in the client?
+FRIENDLY_IN = GENERATOR_DIR / 'data/friendly.csv'
+
+TLOBJECT_IN_TLS = [Path(x) for x in GENERATOR_DIR.glob('data/*.tl')]
+TLOBJECT_OUT = LIBRARY_DIR / 'tl'
+IMPORT_DEPTH = 2
+
+DOCS_IN_RES = GENERATOR_DIR / 'data/html'
+DOCS_OUT = Path('docs')
 
 
-def main():
-    if len(argv) >= 2 and argv[1] == 'gen_tl':
-        gen_tl()
+def generate(which, action='gen'):
+    from telethon_generator.parsers import\
+        parse_errors, parse_methods, parse_tl, find_layer
 
-    elif len(argv) >= 2 and argv[1] == 'clean_tl':
-        from telethon_generator.tl_generator import TLGenerator
-        print('Cleaning...')
-        TLGenerator('telethon/tl').clean_tlobjects()
-        print('Done.')
+    from telethon_generator.generators import\
+        generate_errors, generate_tlobjects, generate_docs, clean_tlobjects
+
+    layer = next(filter(None, map(find_layer, TLOBJECT_IN_TLS)))
+    errors = list(parse_errors(ERRORS_IN))
+    methods = list(parse_methods(METHODS_IN, FRIENDLY_IN, {e.str_code: e for e in errors}))
+
+    tlobjects = list(itertools.chain(*(
+        parse_tl(file, layer, methods) for file in TLOBJECT_IN_TLS)))
+
+    if not which:
+        which.extend(('tl', 'errors'))
+
+    clean = action == 'clean'
+    action = 'Cleaning' if clean else 'Generating'
+
+    if 'all' in which:
+        which.remove('all')
+        for x in ('tl', 'errors', 'docs'):
+            if x not in which:
+                which.append(x)
+
+    if 'tl' in which:
+        which.remove('tl')
+        print(action, 'TLObjects...')
+        if clean:
+            clean_tlobjects(TLOBJECT_OUT)
+        else:
+            generate_tlobjects(tlobjects, layer, IMPORT_DEPTH, TLOBJECT_OUT)
+
+    if 'errors' in which:
+        which.remove('errors')
+        print(action, 'RPCErrors...')
+        if clean:
+            if ERRORS_OUT.is_file():
+                ERRORS_OUT.unlink()
+        else:
+            with ERRORS_OUT.open('w') as file:
+                generate_errors(errors, file)
+
+    if 'docs' in which:
+        which.remove('docs')
+        print(action, 'documentation...')
+        if clean:
+            if DOCS_OUT.is_dir():
+                shutil.rmtree(str(DOCS_OUT))
+        else:
+            in_path = DOCS_IN_RES.resolve()
+            with TempWorkDir(DOCS_OUT):
+                generate_docs(tlobjects, methods, layer, in_path)
+
+    if 'json' in which:
+        which.remove('json')
+        print(action, 'JSON schema...')
+        json_files = [x.with_suffix('.json') for x in TLOBJECT_IN_TLS]
+        if clean:
+            for file in json_files:
+                if file.is_file():
+                    file.unlink()
+        else:
+            def gen_json(fin, fout):
+                meths = []
+                constructors = []
+                for tl in parse_tl(fin, layer):
+                    if tl.is_function:
+                        meths.append(tl.to_dict())
+                    else:
+                        constructors.append(tl.to_dict())
+                what = {'constructors': constructors, 'methods': meths}
+                with open(fout, 'w') as f:
+                    json.dump(what, f, indent=2)
+
+            for fs in zip(TLOBJECT_IN_TLS, json_files):
+                gen_json(*fs)
+
+    if which:
+        print(
+            'The following items were not understood:', which,
+            '\n  Consider using only "tl", "errors" and/or "docs".'
+            '\n  Using only "clean" will clean them. "all" to act on all.'
+            '\n  For instance "gen tl errors".'
+        )
+
+
+def main(argv):
+    if len(argv) >= 2 and argv[1] in ('gen', 'clean'):
+        generate(argv[2:], argv[1])
 
     elif len(argv) >= 2 and argv[1] == 'pypi':
-        # Need python3.5 or higher, but Telethon is supposed to support 3.x
-        # Place it here since noone should be running ./setup.py pypi anyway
-        from subprocess import run
-        from shutil import rmtree
+        # Make sure tl.telethon.dev is up-to-date first
+        with urllib.request.urlopen(API_REF_URL) as resp:
+            html = resp.read()
+            m = re.search(br'layer\s+(\d+)', html)
+            if not m:
+                print('Failed to check that the API reference is up to date:', API_REF_URL)
+                return
+
+            from telethon_generator.parsers import find_layer
+            layer = next(filter(None, map(find_layer, TLOBJECT_IN_TLS)))
+            published_layer = int(m[1])
+            if published_layer != layer:
+                print('Published layer', published_layer, 'does not match current layer', layer, '.')
+                print('Make sure to update the API reference site first:', API_REF_URL)
+                return
+
+        # (Re)generate the code to make sure we don't push without it
+        generate(['tl', 'errors'])
+
+        # Try importing the telethon module to assert it has no errors
+        try:
+            import telethon
+        except Exception as e:
+            print('Packaging for PyPi aborted, importing the module failed.')
+            print(e)
+            return
+
+        remove_dirs = ['__pycache__', 'build', 'dist', 'Telethon.egg-info']
+        for root, _dirs, _files in os.walk(LIBRARY_DIR, topdown=False):
+            # setuptools is including __pycache__ for some reason (#1605)
+            if root.endswith('/__pycache__'):
+                remove_dirs.append(root)
+        for x in remove_dirs:
+            shutil.rmtree(x, ignore_errors=True)
 
-        for x in ('build', 'dist', 'Telethon.egg-info'):
-            rmtree(x, ignore_errors=True)
         run('python3 setup.py sdist', shell=True)
         run('python3 setup.py bdist_wheel', shell=True)
         run('twine upload dist/*', shell=True)
         for x in ('build', 'dist', 'Telethon.egg-info'):
-            rmtree(x, ignore_errors=True)
+            shutil.rmtree(x, ignore_errors=True)
 
     else:
-        if not TelegramClient:
-            gen_tl()
-            from telethon import TelegramClient as TgClient
-            version = TgClient.__version__
-        else:
-            version = TelegramClient.__version__
+        # e.g. install from GitHub
+        if GENERATOR_DIR.is_dir():
+            generate(['tl', 'errors'])
 
         # Get the long description from the README file
-        with open('README.rst', encoding='utf-8') as f:
+        with open('README.rst', 'r', encoding='utf-8') as f:
             long_description = f.read()
 
+        with open('telethon/version.py', 'r', encoding='utf-8') as f:
+            version = re.search(r"^__version__\s*=\s*'(.*)'.*$",
+                                f.read(), flags=re.MULTILINE).group(1)
         setup(
             name='Telethon',
-
-            # Versions should comply with PEP440.
             version=version,
             description="Full-featured Telegram client library for Python 3",
             long_description=long_description,
@@ -108,12 +225,17 @@ def main():
 
             license='MIT',
 
+            # See https://stackoverflow.com/a/40300957/4759433
+            # -> https://www.python.org/dev/peps/pep-0345/#requires-python
+            # -> http://setuptools.readthedocs.io/en/latest/setuptools.html
+            python_requires='>=3.5',
+
             # See https://pypi.python.org/pypi?%3Aaction=list_classifiers
             classifiers=[
                 #   3 - Alpha
                 #   4 - Beta
                 #   5 - Production/Stable
-                'Development Status :: 3 - Alpha',
+                'Development Status :: 5 - Production/Stable',
 
                 'Intended Audience :: Developers',
                 'Topic :: Communications :: Chat',
@@ -121,20 +243,22 @@ def main():
                 'License :: OSI Approved :: MIT License',
 
                 'Programming Language :: Python :: 3',
-                'Programming Language :: Python :: 3.3',
-                'Programming Language :: Python :: 3.4',
                 'Programming Language :: Python :: 3.5',
-                'Programming Language :: Python :: 3.6'
+                'Programming Language :: Python :: 3.6',
+                'Programming Language :: Python :: 3.7',
+                'Programming Language :: Python :: 3.8',
             ],
             keywords='telegram api chat client library messaging mtproto',
             packages=find_packages(exclude=[
-                'telethon_generator', 'telethon_tests', 'run_tests.py',
-                'try_telethon.py'
+                'telethon_*', 'tests*'
             ]),
-            install_requires=['pyaes', 'rsa']
+            install_requires=['pyaes', 'rsa'],
+            extras_require={
+                'cryptg': ['cryptg']
+            }
         )
 
 
 if __name__ == '__main__':
-    with TempWorkDir():  # Could just use a try/finally but this is + reusable
-        main()
+    with TempWorkDir():
+        main(sys.argv)

telethon/__init__.py

@@ -1,4 +1,13 @@
-from .telegram_bare_client import TelegramBareClient
-from .telegram_client import TelegramClient
-from .network import ConnectionMode
-from . import tl
+from .client.telegramclient import TelegramClient
+from .network import connection
+from .tl.custom import Button
+from .tl import patched as _  # import for its side-effects
+from . import version, events, utils, errors, types, functions, custom
+
+__version__ = version.__version__
+
+__all__ = [
+    'TelegramClient', 'Button',
+    'types', 'functions', 'custom', 'errors',
+    'events', 'utils', 'connection'
+]

telethon/_updates/__init__.py

@@ -0,0 +1,3 @@
+from .entitycache import EntityCache
+from .messagebox import MessageBox, GapError, PrematureEndReason
+from .session import SessionState, ChannelState, Entity, EntityType

telethon/_updates/entitycache.py

@@ -0,0 +1,59 @@
+from .session import EntityType, Entity
+
+
+_sentinel = object()
+
+
+class EntityCache:
+    def __init__(
+        self,
+        hash_map: dict = _sentinel,
+        self_id: int = None,
+        self_bot: bool = None
+    ):
+        self.hash_map = {} if hash_map is _sentinel else hash_map
+        self.self_id = self_id
+        self.self_bot = self_bot
+
+    def set_self_user(self, id, bot, hash):
+        self.self_id = id
+        self.self_bot = bot
+        if hash:
+            self.hash_map[id] = (hash, EntityType.BOT if bot else EntityType.USER)
+
+    def get(self, id):
+        try:
+            hash, ty = self.hash_map[id]
+            return Entity(ty, id, hash)
+        except KeyError:
+            return None
+
+    def extend(self, users, chats):
+        # See https://core.telegram.org/api/min for "issues" with "min constructors".
+        self.hash_map.update(
+            (u.id, (
+                u.access_hash,
+                EntityType.BOT if u.bot else EntityType.USER,
+            ))
+            for u in users
+            if getattr(u, 'access_hash', None) and not u.min
+        )
+        self.hash_map.update(
+            (c.id, (
+                c.access_hash,
+                EntityType.MEGAGROUP if c.megagroup else (
+                    EntityType.GIGAGROUP if getattr(c, 'gigagroup', None) else EntityType.CHANNEL
+                ),
+            ))
+            for c in chats
+            if getattr(c, 'access_hash', None) and not getattr(c, 'min', None)
+        )
+
+    def put(self, entity):
+        self.hash_map[entity.id] = (entity.hash, entity.ty)
+
+    def retain(self, filter):
+        self.hash_map = {k: v for k, v in self.hash_map.items() if filter(k)}
+
+    def __len__(self):
+        return len(self.hash_map)

telethon/_updates/messagebox.py

@@ -0,0 +1,825 @@
+"""
+This module deals with correct handling of updates, including gaps, and knowing when the code
+should "get difference" (the set of updates that the client should know by now minus the set
+of updates that it actually knows).
+
+Each chat has its own [`Entry`] in the [`MessageBox`] (this `struct` is the "entry point").
+At any given time, the message box may be either getting difference for them (entry is in
+[`MessageBox::getting_diff_for`]) or not. If not getting difference, a possible gap may be
+found for the updates (entry is in [`MessageBox::possible_gaps`]). Otherwise, the entry is
+on its happy path.
+
+Gaps are cleared when they are either resolved on their own (by waiting for a short time)
+or because we got the difference for the corresponding entry.
+
+While there are entries for which their difference must be fetched,
+[`MessageBox::check_deadlines`] will always return [`Instant::now`], since "now" is the time
+to get the difference.
+"""
+import asyncio
+import datetime
+import time
+import logging
+from enum import Enum
+from .session import SessionState, ChannelState
+from ..tl import types as tl, functions as fn
+from ..helpers import get_running_loop
+
+
+# Telegram sends `seq` equal to `0` when "it doesn't matter", so we use that value too.
+NO_SEQ = 0
+
+# See https://core.telegram.org/method/updates.getChannelDifference.
+BOT_CHANNEL_DIFF_LIMIT = 100000
+USER_CHANNEL_DIFF_LIMIT = 100
+
+# > It may be useful to wait up to 0.5 seconds
+POSSIBLE_GAP_TIMEOUT = 0.5
+
+# After how long without updates the client will "timeout".
+#
+# When this timeout occurs, the client will attempt to fetch updates by itself, ignoring all the
+# updates that arrive in the meantime. After all updates are fetched when this happens, the
+# client will resume normal operation, and the timeout will reset.
+#
+# Documentation recommends 15 minutes without updates (https://core.telegram.org/api/updates).
+NO_UPDATES_TIMEOUT = 15 * 60
+
+# object() but with a tag to make it easier to debug
+class Sentinel:
+    __slots__ = ('tag',)
+
+    def __init__(self, tag=None):
+        self.tag = tag or '_'
+
+    def __repr__(self):
+        return self.tag
+
+# Entry "enum".
+# Account-wide `pts` includes private conversations (one-to-one) and small group chats.
+ENTRY_ACCOUNT = Sentinel('ACCOUNT')
+# Account-wide `qts` includes only "secret" one-to-one chats.
+ENTRY_SECRET = Sentinel('SECRET')
+# Integers will be Channel-specific `pts`, and includes "megagroup", "broadcast" and "supergroup" channels.
+
+# Python's logging doesn't define a TRACE level. Pick halfway between DEBUG and NOTSET.
+# We don't define a name for this as libraries shouldn't do that though.
+LOG_LEVEL_TRACE = (logging.DEBUG - logging.NOTSET) // 2
+
+_sentinel = Sentinel()
+
+def next_updates_deadline():
+    return get_running_loop().time() + NO_UPDATES_TIMEOUT
+
+def epoch():
+    return datetime.datetime(*time.gmtime(0)[:6]).replace(tzinfo=datetime.timezone.utc)
+
+class GapError(ValueError):
+    def __repr__(self):
+        return 'GapError()'
+
+
+class PrematureEndReason(Enum):
+    TEMPORARY_SERVER_ISSUES = 'tmp'
+    BANNED = 'ban'
+
+
+# Represents the information needed to correctly handle a specific `tl::enums::Update`.
+class PtsInfo:
+    __slots__ = ('pts', 'pts_count', 'entry')
+
+    def __init__(
+        self,
+        pts: int,
+        pts_count: int,
+        entry: object
+    ):
+        self.pts = pts
+        self.pts_count = pts_count
+        self.entry = entry
+
+    @classmethod
+    def from_update(cls, update):
+        pts = getattr(update, 'pts', None)
+        if pts:
+            pts_count = getattr(update, 'pts_count', None) or 0
+            try:
+                entry = update.message.peer_id.channel_id
+            except AttributeError:
+                entry = getattr(update, 'channel_id', None) or ENTRY_ACCOUNT
+            return cls(pts=pts, pts_count=pts_count, entry=entry)
+
+        qts = getattr(update, 'qts', None)
+        if qts:
+            return cls(pts=qts, pts_count=1, entry=ENTRY_SECRET)
+
+        return None
+
+    def __repr__(self):
+        return f'PtsInfo(pts={self.pts}, pts_count={self.pts_count}, entry={self.entry})'
+
+
+# The state of a particular entry in the message box.
+class State:
+    __slots__ = ('pts', 'deadline')
+
+    def __init__(
+        self,
+        # Current local persistent timestamp.
+        pts: int,
+        # Next instant when we would get the update difference if no updates arrived before then.
+        deadline: float
+    ):
+        self.pts = pts
+        self.deadline = deadline
+
+    def __repr__(self):
+        return f'State(pts={self.pts}, deadline={self.deadline})'
+
+
+# > ### Recovering gaps
+# > […] Manually obtaining updates is also required in the following situations:
+# > • Loss of sync: a gap was found in `seq` / `pts` / `qts` (as described above).
+# >   It may be useful to wait up to 0.5 seconds in this situation and abort the sync in case a new update
+# >   arrives, that fills the gap.
+#
+# This is really easy to trigger by spamming messages in a channel (with as little as 3 members works), because
+# the updates produced by the RPC request take a while to arrive (whereas the read update comes faster alone).
+class PossibleGap:
+    __slots__ = ('deadline', 'updates')
+
+    def __init__(
+        self,
+        deadline: float,
+        # Pending updates (those with a larger PTS, producing the gap which may later be filled).
+        updates: list  # of updates
+    ):
+        self.deadline = deadline
+        self.updates = updates
+
+    def __repr__(self):
+        return f'PossibleGap(deadline={self.deadline}, update_count={len(self.updates)})'
+
+
+# Represents a "message box" (event `pts` for a specific entry).
+#
+# See https://core.telegram.org/api/updates#message-related-event-sequences.
+class MessageBox:
+    __slots__ = ('_log', 'map', 'date', 'seq', 'next_deadline', 'possible_gaps', 'getting_diff_for')
+
+    def __init__(
+        self,
+        log,
+        # Map each entry to their current state.
+        map: dict = _sentinel,  # entry -> state
+
+        # Additional fields beyond PTS needed by `ENTRY_ACCOUNT`.
+        date: datetime.datetime = epoch() + datetime.timedelta(seconds=1),
+        seq: int = NO_SEQ,
+
+        # Holds the entry with the closest deadline (optimization to avoid recalculating the minimum deadline).
+        next_deadline: object = None,  # entry
+
+        # Which entries have a gap and may soon trigger a need to get difference.
+        #
+        # If a gap is found, stores the required information to resolve it (when should it timeout and what updates
+        # should be held in case the gap is resolved on its own).
+        #
+        # Not stored directly in `map` as an optimization (else we would need another way of knowing which entries have
+        # a gap in them).
+        possible_gaps: dict = _sentinel,  # entry -> possiblegap
+
+        # For which entries are we currently getting difference.
+        getting_diff_for: set = _sentinel,  # entry
+    ):
+        self._log = log
+        self.map = {} if map is _sentinel else map
+        self.date = date
+        self.seq = seq
+        self.next_deadline = next_deadline
+        self.possible_gaps = {} if possible_gaps is _sentinel else possible_gaps
+        self.getting_diff_for = set() if getting_diff_for is _sentinel else getting_diff_for
+
+        if __debug__:
+            self._trace('MessageBox initialized')
+
+    def _trace(self, msg, *args, **kwargs):
+        # Calls to trace can't really be removed beforehand without some dark magic.
+        # So every call to trace is prefixed with `if __debug__`` instead, to remove
+        # it when using `python -O`. Probably unnecessary, but it's nice to avoid
+        # paying the cost for something that is not used.
+        self._log.log(LOG_LEVEL_TRACE, 'Current MessageBox state: seq = %r, date = %s, map = %r',
+                      self.seq, self.date.isoformat(), self.map)
+        self._log.log(LOG_LEVEL_TRACE, msg, *args, **kwargs)
+
+    # region Creation, querying, and setting base state.
+
+    def load(self, session_state, channel_states):
+        """
+        Create a [`MessageBox`] from a previously known update state.
+        """
+        if __debug__:
+            self._trace('Loading MessageBox with session_state = %r, channel_states = %r', session_state, channel_states)
+
+        deadline = next_updates_deadline()
+
+        self.map.clear()
+        if session_state.pts != NO_SEQ:
+            self.map[ENTRY_ACCOUNT] = State(pts=session_state.pts, deadline=deadline)
+        if session_state.qts != NO_SEQ:
+            self.map[ENTRY_SECRET] = State(pts=session_state.qts, deadline=deadline)
+        self.map.update((s.channel_id, State(pts=s.pts, deadline=deadline)) for s in channel_states)
+
+        self.date = datetime.datetime.fromtimestamp(session_state.date, tz=datetime.timezone.utc)
+        self.seq = session_state.seq
+        self.next_deadline = ENTRY_ACCOUNT
+
+    def session_state(self):
+        """
+        Return the current state.
+
+        This should be used for persisting the state.
+        """
+        return dict(
+            pts=self.map[ENTRY_ACCOUNT].pts if ENTRY_ACCOUNT in self.map else NO_SEQ,
+            qts=self.map[ENTRY_SECRET].pts if ENTRY_SECRET in self.map else NO_SEQ,
+            date=self.date,
+            seq=self.seq,
+        ), {id: state.pts for id, state in self.map.items() if isinstance(id, int)}
+
+    def is_empty(self) -> bool:
+        """
+        Return true if the message box is empty and has no state yet.
+        """
+        return ENTRY_ACCOUNT not in self.map
+
+    def check_deadlines(self):
+        """
+        Return the next deadline when receiving updates should timeout.
+
+        If a deadline expired, the corresponding entries will be marked as needing to get its difference.
+        While there are entries pending of getting their difference, this method returns the current instant.
+        """
+        now = get_running_loop().time()
+
+        if self.getting_diff_for:
+            return now
+
+        deadline = next_updates_deadline()
+
+        # Most of the time there will be zero or one gap in flight so finding the minimum is cheap.
+        if self.possible_gaps:
+            deadline = min(deadline, *(gap.deadline for gap in self.possible_gaps.values()))
+        elif self.next_deadline in self.map:
+            deadline = min(deadline, self.map[self.next_deadline].deadline)
+
+        # asyncio's loop time precision only seems to be about 3 decimal places, so it's possible that
+        # we find the same number again on repeated calls. Without the "or equal" part we would log the
+        # timeout for updates several times (it also makes sense to get difference if now is the deadline).
+        if now >= deadline:
+            # Check all expired entries and add them to the list that needs getting difference.
+            self.getting_diff_for.update(entry for entry, gap in self.possible_gaps.items() if now >= gap.deadline)
+            self.getting_diff_for.update(entry for entry, state in self.map.items() if now >= state.deadline)
+
+            if __debug__:
+                self._trace('Deadlines met, now getting diff for %r', self.getting_diff_for)
+
+            # When extending `getting_diff_for`, it's important to have the moral equivalent of
+            # `begin_get_diff` (that is, clear possible gaps if we're now getting difference).
+            for entry in self.getting_diff_for:
+                self.possible_gaps.pop(entry, None)
+
+        return deadline
+
+    # Reset the deadline for the periods without updates for the given entries.
+    #
+    # It also updates the next deadline time to reflect the new closest deadline.
+    def reset_deadlines(self, entries, deadline):
+        if not entries:
+            return
+        for entry in entries:
+            if entry not in self.map:
+                raise RuntimeError('Called reset_deadline on an entry for which we do not have state')
+            self.map[entry].deadline = deadline
+
+        if self.next_deadline in entries:
+            # If the updated deadline was the closest one, recalculate the new minimum.
+            self.next_deadline = min(self.map.items(), key=lambda entry_state: entry_state[1].deadline)[0]
+        elif self.next_deadline in self.map and deadline < self.map[self.next_deadline].deadline:
+            # If the updated deadline is smaller than the next deadline, change the next deadline to be the new one.
+            # Any entry will do, so the one from the last iteration is fine.
+            self.next_deadline = entry
+        # else an unrelated deadline was updated, so the closest one remains unchanged.
+
+    # Convenience to reset a channel's deadline, with optional timeout.
+    def reset_channel_deadline(self, channel_id, timeout):
+        self.reset_deadlines({channel_id}, get_running_loop().time() + (timeout or NO_UPDATES_TIMEOUT))
+
+    # Sets the update state.
+    #
+    # Should be called right after login if [`MessageBox::new`] was used, otherwise undesirable
+    # updates will be fetched.
+    def set_state(self, state, reset=True):
+        if __debug__:
+            self._trace('Setting state %s', state)
+
+        deadline = next_updates_deadline()
+
+        if state.pts != NO_SEQ or not reset:
+            self.map[ENTRY_ACCOUNT] = State(pts=state.pts, deadline=deadline)
+        else:
+            self.map.pop(ENTRY_ACCOUNT, None)
+
+        # Telegram seems to use the `qts` for bot accounts, but while applying difference,
+        # it might be reset back to 0. See issue #3873 for more details.
+        #
+        # During login, a value of zero would mean the `pts` is unknown,
+        # so the map shouldn't contain that entry.
+        # But while applying difference, if the value is zero, it (probably)
+        # truly means that's what should be used (hence the `reset` flag).
+        if state.qts != NO_SEQ or not reset:
+            self.map[ENTRY_SECRET] = State(pts=state.qts, deadline=deadline)
+        else:
+            self.map.pop(ENTRY_SECRET, None)
+
+        self.date = state.date
+        self.seq = state.seq
+
+    # Like [`MessageBox::set_state`], but for channels. Useful when getting dialogs.
+    #
+    # The update state will only be updated if no entry was known previously.
+    def try_set_channel_state(self, id, pts):
+        if __debug__:
+            self._trace('Trying to set channel state for %r: %r', id, pts)
+
+        if id not in self.map:
+            self.map[id] = State(pts=pts, deadline=next_updates_deadline())
+
+    # Try to begin getting difference for the given entry.
+    # Fails if the entry does not have a previously-known state that can be used to get its difference.
+    #
+    # Clears any previous gaps.
+    def try_begin_get_diff(self, entry, reason):
+        if entry not in self.map:
+            # Won't actually be able to get difference for this entry if we don't have a pts to start off from.
+            if entry in self.possible_gaps:
+                raise RuntimeError('Should not have a possible_gap for an entry not in the state map')
+
+            if __debug__:
+                self._trace('Should get difference for %r because %s but cannot due to missing hash', entry, reason)
+            return
+
+        if __debug__:
+            self._trace('Marking %r as needing difference because %s', entry, reason)
+        self.getting_diff_for.add(entry)
+        self.possible_gaps.pop(entry, None)
+
+    # Finish getting difference for the given entry.
+    #
+    # It also resets the deadline.
+    def end_get_diff(self, entry):
+        try:
+            self.getting_diff_for.remove(entry)
+        except KeyError:
+            raise RuntimeError('Called end_get_diff on an entry which was not getting diff for')
+
+        self.reset_deadlines({entry}, next_updates_deadline())
+        assert entry not in self.possible_gaps, "gaps shouldn't be created while getting difference"
+
+    # endregion Creation, querying, and setting base state.
+
+    # region "Normal" updates flow (processing and detection of gaps).
+
+    # Process an update and return what should be done with it.
+    #
+    # Updates corresponding to entries for which their difference is currently being fetched
+    # will be ignored. While according to the [updates' documentation]:
+    #
+    # > Implementations [have] to postpone updates received via the socket while
+    # > filling gaps in the event and `Update` sequences, as well as avoid filling
+    # > gaps in the same sequence.
+    #
+    # In practice, these updates should have also been retrieved through getting difference.
+    #
+    # [updates documentation] https://core.telegram.org/api/updates
+    def process_updates(
+        self,
+        updates,
+        chat_hashes,
+        result,  # out list of updates; returns list of user, chat, or raise if gap
+    ):
+
+        # v1 has never sent updates produced by the client itself to the handlers.
+        # However proper update handling requires those to be processed.
+        # This is an ugly workaround for that.
+        self_outgoing = getattr(updates, '_self_outgoing', False)
+        real_result = result
+        result = []
+
+        date = getattr(updates, 'date', None)
+        seq = getattr(updates, 'seq', None)
+        seq_start = getattr(updates, 'seq_start', None)
+        users = getattr(updates, 'users', None) or []
+        chats = getattr(updates, 'chats', None) or []
+
+        if __debug__:
+            self._trace('Processing updates with seq = %r, seq_start = %r, date = %s: %s',
+                        seq, seq_start, date.isoformat() if date else None, updates)
+
+        if date is None:
+            # updatesTooLong is the only one with no date (we treat it as a gap)
+            self.try_begin_get_diff(ENTRY_ACCOUNT, 'received updatesTooLong')
+            raise GapError
+        if seq is None:
+            seq = NO_SEQ
+        if seq_start is None:
+            seq_start = seq
+
+        # updateShort is the only update which cannot be dispatched directly but doesn't have 'updates' field
+        updates = getattr(updates, 'updates', None) or [updates.update if isinstance(updates, tl.UpdateShort) else updates]
+
+        for u in updates:
+            u._self_outgoing = self_outgoing
+
+        # > For all the other [not `updates` or `updatesCombined`] `Updates` type constructors
+        # > there is no need to check `seq` or change a local state.
+        if seq_start != NO_SEQ:
+            if self.seq + 1 > seq_start:
+                # Skipping updates that were already handled
+                if __debug__:
+                    self._trace('Skipping updates as they should have already been handled')
+                return (users, chats)
+            elif self.seq + 1 < seq_start:
+                # Gap detected
+                self.try_begin_get_diff(ENTRY_ACCOUNT, 'detected gap')
+                raise GapError
+            # else apply
+
+        def _sort_gaps(update):
+            pts = PtsInfo.from_update(update)
+            return pts.pts - pts.pts_count if pts else 0
+
+        reset_deadlines = set()  # temporary buffer
+
+        result.extend(filter(None, (
+            self.apply_pts_info(u, reset_deadlines=reset_deadlines)
+            # Telegram can send updates out of order (e.g. ReadChannelInbox first
+            # and then NewChannelMessage, both with the same pts, but the count is
+            # 0 and 1 respectively), so we sort them first.
+            for u in sorted(updates, key=_sort_gaps))))
+
+        self.reset_deadlines(reset_deadlines, next_updates_deadline())
+
+        if self.possible_gaps:
+            if __debug__:
+                self._trace('Trying to re-apply %r possible gaps', len(self.possible_gaps))
+
+            # For each update in possible gaps, see if the gap has been resolved already.
+            for key in list(self.possible_gaps.keys()):
+                self.possible_gaps[key].updates.sort(key=_sort_gaps)
+
+                for _ in range(len(self.possible_gaps[key].updates)):
+                    update = self.possible_gaps[key].updates.pop(0)
+
+                    # If this fails to apply, it will get re-inserted at the end.
+                    # All should fail, so the order will be preserved (it would've cycled once).
+                    update = self.apply_pts_info(update, reset_deadlines=None)
+                    if update:
+                        result.append(update)
+                        if __debug__:
+                            self._trace('Resolved gap with %r: %s', PtsInfo.from_update(update), update)
+
+            # Clear now-empty gaps.
+            self.possible_gaps = {entry: gap for entry, gap in self.possible_gaps.items() if gap.updates}
+
+        real_result.extend(u for u in result if not u._self_outgoing)
+
+        if result and not self.possible_gaps:
+            # > If the updates were applied, local *Updates* state must be updated
+            # > with `seq` (unless it's 0) and `date` from the constructor.
+            if __debug__:
+                self._trace('Updating seq as all updates were applied')
+            if date != epoch():
+                self.date = date
+            if seq != NO_SEQ:
+                self.seq = seq
+
+        return (users, chats)
+
+    # Tries to apply the input update if its `PtsInfo` follows the correct order.
+    #
+    # If the update can be applied, it is returned; otherwise, the update is stored in a
+    # possible gap (unless it was already handled or would be handled through getting
+    # difference) and `None` is returned.
+    def apply_pts_info(
+        self,
+        update,
+        *,
+        reset_deadlines,
+    ):
+        # This update means we need to call getChannelDifference to get the updates from the channel
+        if isinstance(update, tl.UpdateChannelTooLong):
+            self.try_begin_get_diff(update.channel_id, 'received updateChannelTooLong')
+            return None
+
+        pts = PtsInfo.from_update(update)
+        if not pts:
+            # No pts means that the update can be applied in any order.
+            if __debug__:
+                self._trace('No pts in update, so it can be applied in any order: %s', update)
+            return update
+
+        # As soon as we receive an update of any form related to messages (has `PtsInfo`),
+        # the "no updates" period for that entry is reset.
+        #
+        # Build the `HashSet` to avoid calling `reset_deadline` more than once for the same entry.
+        #
+        # By the time this method returns, self.map will have an entry for which we can reset its deadline.
+        if reset_deadlines:
+            reset_deadlines.add(pts.entry)
+
+        if pts.entry in self.getting_diff_for:
+            # Note: early returning here also prevents gap from being inserted (which they should
+            # not be while getting difference).
+            if __debug__:
+                self._trace('Skipping update with %r as its difference is being fetched', pts)
+            return None
+
+        if pts.entry in self.map:
+            local_pts = self.map[pts.entry].pts
+            if local_pts + pts.pts_count > pts.pts:
+                # Ignore
+                if __debug__:
+                    self._trace('Skipping update since local pts %r > %r: %s', local_pts, pts, update)
+                return None
+            elif local_pts + pts.pts_count < pts.pts:
+                # Possible gap
+                # TODO store chats too?
+                if __debug__:
+                    self._trace('Possible gap since local pts %r < %r: %s', local_pts, pts, update)
+                if pts.entry not in self.possible_gaps:
+                    self.possible_gaps[pts.entry] = PossibleGap(
+                        deadline=get_running_loop().time() + POSSIBLE_GAP_TIMEOUT,
+                        updates=[]
+                    )
+
+                self.possible_gaps[pts.entry].updates.append(update)
+                return None
+            else:
+                # Apply
+                if __debug__:
+                    self._trace('Applying update pts since local pts %r = %r: %s', local_pts, pts, update)
+
+        # In a channel, we may immediately receive:
+        # * ReadChannelInbox (pts = X, pts_count = 0)
+        # * NewChannelMessage (pts = X, pts_count = 1)
+        #
+        # Notice how both `pts` are the same. If they were to be applied out of order, the first
+        # one however would've triggered a gap because `local_pts` + `pts_count` of 0 would be
+        # less than `remote_pts`. So there is no risk by setting the `local_pts` to match the
+        # `remote_pts` here of missing the new message.
+        #
+        # The message would however be lost if we initialized the pts with the first one, since
+        # the second one would appear "already handled". To prevent this we set the pts to be
+        # one less when the count is 0 (which might be wrong and trigger a gap later on, but is
+        # unlikely). This will prevent us from losing updates in the unlikely scenario where these
+        # two updates arrive in different packets (and therefore couldn't be sorted beforehand).
+        if pts.entry in self.map:
+            self.map[pts.entry].pts = pts.pts
+        else:
+            # When a chat is migrated to a megagroup, the first update can be a `ReadChannelInbox`
+            # with `pts = 1, pts_count = 0` followed by a `NewChannelMessage` with `pts = 2, pts_count=1`.
+            # Note how the `pts` for the message is 2 and not 1 unlike the case described before!
+            # This is likely because the `pts` cannot be 0 (or it would fail with PERSISTENT_TIMESTAMP_EMPTY),
+            # which forces the first update to be 1. But if we got difference with 1 and the second update
+            # also used 1, we would miss it, so Telegram probably uses 2 to work around that.
+            self.map[pts.entry] = State(
+                pts=(pts.pts - (0 if pts.pts_count else 1)) or 1,
+                deadline=next_updates_deadline()
+            )
+
+        return update
+
+    # endregion "Normal" updates flow (processing and detection of gaps).
+
+    # region Getting and applying account difference.
+
+    # Return the request that needs to be made to get the difference, if any.
+    def get_difference(self):
+        for entry in (ENTRY_ACCOUNT, ENTRY_SECRET):
+            if entry in self.getting_diff_for:
+                if entry not in self.map:
+                    raise RuntimeError('Should not try to get difference for an entry without known state')
+
+                gd = fn.updates.GetDifferenceRequest(
+                    pts=self.map[ENTRY_ACCOUNT].pts,
+                    pts_total_limit=None,
+                    date=self.date,
+                    qts=self.map[ENTRY_SECRET].pts if ENTRY_SECRET in self.map else NO_SEQ,
+                )
+                if __debug__:
+                    self._trace('Requesting account difference %s', gd)
+                return gd
+
+        return None
+
+    # Similar to [`MessageBox::process_updates`], but using the result from getting difference.
+    def apply_difference(
+        self,
+        diff,
+        chat_hashes,
+    ):
+        if __debug__:
+            self._trace('Applying account difference %s', diff)
+
+        finish = None
+        result = None
+
+        if isinstance(diff, tl.updates.DifferenceEmpty):
+            finish = True
+            self.date = diff.date
+            self.seq = diff.seq
+            result = [], [], []
+        elif isinstance(diff, tl.updates.Difference):
+            finish = True
+            chat_hashes.extend(diff.users, diff.chats)
+            result = self.apply_difference_type(diff, chat_hashes)
+        elif isinstance(diff, tl.updates.DifferenceSlice):
+            finish = False
+            chat_hashes.extend(diff.users, diff.chats)
+            result = self.apply_difference_type(diff, chat_hashes)
+        elif isinstance(diff, tl.updates.DifferenceTooLong):
+            finish = True
+            self.map[ENTRY_ACCOUNT].pts = diff.pts  # the deadline will be reset once the diff ends
+            result = [], [], []
+
+        if finish:
+            account = ENTRY_ACCOUNT in self.getting_diff_for
+            secret = ENTRY_SECRET in self.getting_diff_for
+
+            if not account and not secret:
+                raise RuntimeError('Should not be applying the difference when neither account or secret was diff was active')
+
+            # Both may be active if both expired at the same time.
+            if account:
+                self.end_get_diff(ENTRY_ACCOUNT)
+            if secret:
+                self.end_get_diff(ENTRY_SECRET)
+
+        return result
+
+    def apply_difference_type(
+        self,
+        diff,
+        chat_hashes,
+    ):
+        state = getattr(diff, 'intermediate_state', None) or diff.state
+        self.set_state(state, reset=False)
+
+        # diff.other_updates can contain things like UpdateChannelTooLong and UpdateNewChannelMessage.
+        # We need to process those as if they were socket updates to discard any we have already handled.
+        updates = []
+        self.process_updates(tl.Updates(
+            updates=diff.other_updates,
+            users=diff.users,
+            chats=diff.chats,
+            date=epoch(),
+            seq=NO_SEQ,  # this way date is not used
+        ), chat_hashes, updates)
+
+        updates.extend(tl.UpdateNewMessage(
+            message=m,
+            pts=NO_SEQ,
+            pts_count=NO_SEQ,
+        ) for m in diff.new_messages)
+        updates.extend(tl.UpdateNewEncryptedMessage(
+            message=m,
+            qts=NO_SEQ,
+        ) for m in diff.new_encrypted_messages)
+
+        return updates, diff.users, diff.chats
+
+    def end_difference(self):
+        if __debug__:
+            self._trace('Ending account difference')
+
+        account = ENTRY_ACCOUNT in self.getting_diff_for
+        secret = ENTRY_SECRET in self.getting_diff_for
+
+        if not account and not secret:
+            raise RuntimeError('Should not be ending get difference when neither account or secret was diff was active')
+
+        # Both may be active if both expired at the same time.
+        if account:
+            self.end_get_diff(ENTRY_ACCOUNT)
+        if secret:
+            self.end_get_diff(ENTRY_SECRET)
+
+    # endregion Getting and applying account difference.
+
+    # region Getting and applying channel difference.
+
+    # Return the request that needs to be made to get a channel's difference, if any.
+    def get_channel_difference(
+        self,
+        chat_hashes,
+    ):
+        entry = next((id for id in self.getting_diff_for if isinstance(id, int)), None)
+        if not entry:
+            return None
+
+        packed = chat_hashes.get(entry)
+        if not packed:
+            # Cannot get channel difference as we're missing its hash
+            # TODO we should probably log this
+            self.end_get_diff(entry)
+            # Remove the outdated `pts` entry from the map so that the next update can correct
+            # it. Otherwise, it will spam that the access hash is missing.
+            self.map.pop(entry, None)
+            return None
+
+        state = self.map.get(entry)
+        if not state:
+            raise RuntimeError('Should not try to get difference for an entry without known state')
+
+        gd = fn.updates.GetChannelDifferenceRequest(
+            force=False,
+            channel=tl.InputChannel(packed.id, packed.hash),
+            filter=tl.ChannelMessagesFilterEmpty(),
+            pts=state.pts,
+            limit=BOT_CHANNEL_DIFF_LIMIT if chat_hashes.self_bot else USER_CHANNEL_DIFF_LIMIT
+        )
+        if __debug__:
+            self._trace('Requesting channel difference %s', gd)
+        return gd
+
+    # Similar to [`MessageBox::process_updates`], but using the result from getting difference.
+    def apply_channel_difference(
+        self,
+        request,
+        diff,
+        chat_hashes,
+    ):
+        entry = request.channel.channel_id
+        if __debug__:
+            self._trace('Applying channel difference for %r: %s', entry, diff)
+
+        self.possible_gaps.pop(entry, None)
+
+        if isinstance(diff, tl.updates.ChannelDifferenceEmpty):
+            assert diff.final
+            self.end_get_diff(entry)
+            self.map[entry].pts = diff.pts
+            return [], [], []
+        elif isinstance(diff, tl.updates.ChannelDifferenceTooLong):
+            assert diff.final
+            self.map[entry].pts = diff.dialog.pts
+            chat_hashes.extend(diff.users, diff.chats)
+            self.reset_channel_deadline(entry, diff.timeout)
+            # This `diff` has the "latest messages and corresponding chats", but it would
+            # be strange to give the user only partial changes of these when they would
+            # expect all updates to be fetched. Instead, nothing is returned.
+            return [], [], []
+        elif isinstance(diff, tl.updates.ChannelDifference):
+            if diff.final:
+                self.end_get_diff(entry)
+
+            self.map[entry].pts = diff.pts
+            chat_hashes.extend(diff.users, diff.chats)
+
+            updates = []
+            self.process_updates(tl.Updates(
+                updates=diff.other_updates,
+                users=diff.users,
+                chats=diff.chats,
+                date=epoch(),
+                seq=NO_SEQ,  # this way date is not used
+            ), chat_hashes, updates)
+
+            updates.extend(tl.UpdateNewChannelMessage(
+                message=m,
+                pts=NO_SEQ,
+                pts_count=NO_SEQ,
+            ) for m in diff.new_messages)
+            self.reset_channel_deadline(entry, None)
+
+            return updates, diff.users, diff.chats
+
+    def end_channel_difference(self, request, reason: PrematureEndReason, chat_hashes):
+        entry = request.channel.channel_id
+        if __debug__:
+            self._trace('Ending channel difference for %r because %s', entry, reason)
+
+        if reason == PrematureEndReason.TEMPORARY_SERVER_ISSUES:
+            # Temporary issues. End getting difference without updating the pts so we can retry later.
+            self.possible_gaps.pop(entry, None)
+            self.end_get_diff(entry)
+        elif reason == PrematureEndReason.BANNED:
+            # Banned in the channel. Forget its state since we can no longer fetch updates from it.
+            self.possible_gaps.pop(entry, None)
+            self.end_get_diff(entry)
+            del self.map[entry]
+        else:
+            raise RuntimeError('Unknown reason to end channel difference')
+
+    # endregion Getting and applying channel difference.

telethon/_updates/session.py

@@ -0,0 +1,195 @@
+from typing import Optional, Tuple
+from enum import IntEnum
+from ..tl.types import InputPeerUser, InputPeerChat, InputPeerChannel
+import struct
+
+class SessionState:
+    """
+    Stores the information needed to fetch updates and about the current user.
+
+    * user_id: 64-bit number representing the user identifier.
+    * dc_id: 32-bit number relating to the datacenter identifier where the user is.
+    * bot: is the logged-in user a bot?
+    * pts: 64-bit number holding the state needed to fetch updates.
+    * qts: alternative 64-bit number holding the state needed to fetch updates.
+    * date: 64-bit number holding the date needed to fetch updates.
+    * seq: 64-bit-number holding the sequence number needed to fetch updates.
+    * takeout_id: 64-bit-number holding the identifier of the current takeout session.
+
+    Note that some of the numbers will only use 32 out of the 64 available bits.
+    However, for future-proofing reasons, we recommend you pretend they are 64-bit long.
+    """
+    __slots__ = ('user_id', 'dc_id', 'bot', 'pts', 'qts', 'date', 'seq', 'takeout_id')
+
+    def __init__(
+        self,
+        user_id: int,
+        dc_id: int,
+        bot: bool,
+        pts: int,
+        qts: int,
+        date: int,
+        seq: int,
+        takeout_id: Optional[int]
+    ):
+        self.user_id = user_id
+        self.dc_id = dc_id
+        self.bot = bot
+        self.pts = pts
+        self.qts = qts
+        self.date = date
+        self.seq = seq
+        self.takeout_id = takeout_id
+
+    def __repr__(self):
+        return repr({k: getattr(self, k) for k in self.__slots__})
+
+
+class ChannelState:
+    """
+    Stores the information needed to fetch updates from a channel.
+
+    * channel_id: 64-bit number representing the channel identifier.
+    * pts: 64-bit number holding the state needed to fetch updates.
+    """
+    __slots__ = ('channel_id', 'pts')
+
+    def __init__(
+        self,
+        channel_id: int,
+        pts: int,
+    ):
+        self.channel_id = channel_id
+        self.pts = pts
+
+    def __repr__(self):
+        return repr({k: getattr(self, k) for k in self.__slots__})
+
+
+class EntityType(IntEnum):
+    """
+    You can rely on the type value to be equal to the ASCII character one of:
+
+    * 'U' (85): this entity belongs to a :tl:`User` who is not a ``bot``.
+    * 'B' (66): this entity belongs to a :tl:`User` who is a ``bot``.
+    * 'G' (71): this entity belongs to a small group :tl:`Chat`.
+    * 'C' (67): this entity belongs to a standard broadcast :tl:`Channel`.
+    * 'M' (77): this entity belongs to a megagroup :tl:`Channel`.
+    * 'E' (69): this entity belongs to an "enormous" "gigagroup" :tl:`Channel`.
+    """
+    USER = ord('U')
+    BOT = ord('B')
+    GROUP = ord('G')
+    CHANNEL = ord('C')
+    MEGAGROUP = ord('M')
+    GIGAGROUP = ord('E')
+
+    def canonical(self):
+        """
+        Return the canonical version of this type.
+        """
+        return _canon_entity_types[self]
+
+
+_canon_entity_types = {
+    EntityType.USER: EntityType.USER,
+    EntityType.BOT: EntityType.USER,
+    EntityType.GROUP: EntityType.GROUP,
+    EntityType.CHANNEL: EntityType.CHANNEL,
+    EntityType.MEGAGROUP: EntityType.CHANNEL,
+    EntityType.GIGAGROUP: EntityType.CHANNEL,
+}
+
+
+class Entity:
+    """
+    Stores the information needed to use a certain user, chat or channel with the API.
+
+    * ty: 8-bit number indicating the type of the entity (of type `EntityType`).
+    * id: 64-bit number uniquely identifying the entity among those of the same type.
+    * hash: 64-bit signed number needed to use this entity with the API.
+
+    The string representation of this class is considered to be stable, for as long as
+    Telegram doesn't need to add more fields to the entities. It can also be converted
+    to bytes with ``bytes(entity)``, for a more compact representation.
+    """
+    __slots__ = ('ty', 'id', 'hash')
+
+    def __init__(
+        self,
+        ty: EntityType,
+        id: int,
+        hash: int
+    ):
+        self.ty = ty
+        self.id = id
+        self.hash = hash
+
+    @property
+    def is_user(self):
+        """
+        ``True`` if the entity is either a user or a bot.
+        """
+        return self.ty in (EntityType.USER, EntityType.BOT)
+
+    @property
+    def is_group(self):
+        """
+        ``True`` if the entity is a small group chat or `megagroup`_.
+
+        .. _megagroup: https://telegram.org/blog/supergroups5k
+        """
+        return self.ty in (EntityType.GROUP, EntityType.MEGAGROUP)
+
+    @property
+    def is_broadcast(self):
+        """
+        ``True`` if the entity is a broadcast channel or `broadcast group`_.
+
+        .. _broadcast group: https://telegram.org/blog/autodelete-inv2#groups-with-unlimited-members
+        """
+        return self.ty in (EntityType.CHANNEL, EntityType.GIGAGROUP)
+
+    @classmethod
+    def from_str(cls, string: str):
+        """
+        Convert the string into an `Entity`.
+        """
+        try:
+            ty, id, hash = string.split('.')
+            ty, id, hash = ord(ty), int(id), int(hash)
+        except AttributeError:
+            raise TypeError(f'expected str, got {string!r}') from None
+        except (TypeError, ValueError):
+            raise ValueError(f'malformed entity str (must be T.id.hash), got {string!r}') from None
+
+        return cls(EntityType(ty), id, hash)
+
+    @classmethod
+    def from_bytes(cls, blob):
+        """
+        Convert the bytes into an `Entity`.
+        """
+        try:
+            ty, id, hash = struct.unpack('<Bqq', blob)
+        except struct.error:
+            raise ValueError(f'malformed entity data, got {blob!r}') from None
+
+        return cls(EntityType(ty), id, hash)
+
+    def __str__(self):
+        return f'{chr(self.ty)}.{self.id}.{self.hash}'
+
+    def __bytes__(self):
+        return struct.pack('<Bqq', self.ty, self.id, self.hash)
+
+    def _as_input_peer(self):
+        if self.is_user:
+            return InputPeerUser(self.id, self.hash)
+        elif self.ty == EntityType.GROUP:
+            return InputPeerChat(self.id)
+        else:
+            return InputPeerChannel(self.id, self.hash)
+
+    def __repr__(self):
+        return repr({k: getattr(self, k) for k in self.__slots__})

telethon/client/__init__.py

@@ -0,0 +1,25 @@
+"""
+This package defines clients as subclasses of others, and then a single
+`telethon.client.telegramclient.TelegramClient` which is subclass of them
+all to provide the final unified interface while the methods can live in
+different subclasses to be more maintainable.
+
+The ABC is `telethon.client.telegrambaseclient.TelegramBaseClient` and the
+first implementor is `telethon.client.users.UserMethods`, since calling
+requests require them to be resolved first, and that requires accessing
+entities (users).
+"""
+from .telegrambaseclient import TelegramBaseClient
+from .users import UserMethods  # Required for everything
+from .messageparse import MessageParseMethods  # Required for messages
+from .uploads import UploadMethods  # Required for messages to send files
+from .updates import UpdateMethods  # Required for buttons (register callbacks)
+from .buttons import ButtonMethods  # Required for messages to use buttons
+from .messages import MessageMethods
+from .chats import ChatMethods
+from .dialogs import DialogMethods
+from .downloads import DownloadMethods
+from .account import AccountMethods
+from .auth import AuthMethods
+from .bots import BotMethods
+from .telegramclient import TelegramClient

telethon/client/account.py

@@ -0,0 +1,243 @@
+import functools
+import inspect
+import typing
+
+from .users import _NOT_A_REQUEST
+from .. import helpers, utils
+from ..tl import functions, TLRequest
+
+if typing.TYPE_CHECKING:
+    from .telegramclient import TelegramClient
+
+
+# TODO Make use of :tl:`InvokeWithMessagesRange` somehow
+#      For that, we need to use :tl:`GetSplitRanges` first.
+class _TakeoutClient:
+    """
+    Proxy object over the client.
+    """
+    __PROXY_INTERFACE = ('__enter__', '__exit__', '__aenter__', '__aexit__')
+
+    def __init__(self, finalize, client, request):
+        # We use the name mangling for attributes to make them inaccessible
+        # from within the shadowed client object and to distinguish them from
+        # its own attributes where needed.
+        self.__finalize = finalize
+        self.__client = client
+        self.__request = request
+        self.__success = None
+
+    @property
+    def success(self):
+        return self.__success
+
+    @success.setter
+    def success(self, value):
+        self.__success = value
+
+    async def __aenter__(self):
+        # Enter/Exit behaviour is "overrode", we don't want to call start.
+        client = self.__client
+        if client.session.takeout_id is None:
+            client.session.takeout_id = (await client(self.__request)).id
+        elif self.__request is not None:
+            raise ValueError("Can't send a takeout request while another "
+                "takeout for the current session still not been finished yet.")
+        return self
+
+    async def __aexit__(self, exc_type, exc_value, traceback):
+        if self.__success is None and self.__finalize:
+            self.__success = exc_type is None
+
+        if self.__success is not None:
+            result = await self(functions.account.FinishTakeoutSessionRequest(
+                self.__success))
+            if not result:
+                raise ValueError("Failed to finish the takeout.")
+            self.session.takeout_id = None
+
+    __enter__ = helpers._sync_enter
+    __exit__ = helpers._sync_exit
+
+    async def __call__(self, request, ordered=False):
+        takeout_id = self.__client.session.takeout_id
+        if takeout_id is None:
+            raise ValueError('Takeout mode has not been initialized '
+                '(are you calling outside of "with"?)')
+
+        single = not utils.is_list_like(request)
+        requests = ((request,) if single else request)
+        wrapped = []
+        for r in requests:
+            if not isinstance(r, TLRequest):
+                raise _NOT_A_REQUEST()
+            await r.resolve(self, utils)
+            wrapped.append(functions.InvokeWithTakeoutRequest(takeout_id, r))
+
+        return await self.__client(
+            wrapped[0] if single else wrapped, ordered=ordered)
+
+    def __getattribute__(self, name):
+        # We access class via type() because __class__ will recurse infinitely.
+        # Also note that since we've name-mangled our own class attributes,
+        # they'll be passed to __getattribute__() as already decorated. For
+        # example, 'self.__client' will be passed as '_TakeoutClient__client'.
+        # https://docs.python.org/3/tutorial/classes.html#private-variables
+        if name.startswith('__') and name not in type(self).__PROXY_INTERFACE:
+            raise AttributeError  # force call of __getattr__
+
+        # Try to access attribute in the proxy object and check for the same
+        # attribute in the shadowed object (through our __getattr__) if failed.
+        return super().__getattribute__(name)
+
+    def __getattr__(self, name):
+        value = getattr(self.__client, name)
+        if inspect.ismethod(value):
+            # Emulate bound methods behavior by partially applying our proxy
+            # class as the self parameter instead of the client.
+            return functools.partial(
+                getattr(self.__client.__class__, name), self)
+
+        return value
+
+    def __setattr__(self, name, value):
+        if name.startswith('_{}__'.format(type(self).__name__.lstrip('_'))):
+            # This is our own name-mangled attribute, keep calm.
+            return super().__setattr__(name, value)
+        return setattr(self.__client, name, value)
+
+
+class AccountMethods:
+    def takeout(
+            self: 'TelegramClient',
+            finalize: bool = True,
+            *,
+            contacts: bool = None,
+            users: bool = None,
+            chats: bool = None,
+            megagroups: bool = None,
+            channels: bool = None,
+            files: bool = None,
+            max_file_size: bool = None) -> 'TelegramClient':
+        """
+        Returns a :ref:`telethon-client` which calls methods behind a takeout session.
+
+        It does so by creating a proxy object over the current client through
+        which making requests will use :tl:`InvokeWithTakeoutRequest` to wrap
+        them. In other words, returns the current client modified so that
+        requests are done as a takeout:
+
+        Some of the calls made through the takeout session will have lower
+        flood limits. This is useful if you want to export the data from
+        conversations or mass-download media, since the rate limits will
+        be lower. Only some requests will be affected, and you will need
+        to adjust the `wait_time` of methods like `client.iter_messages
+        <telethon.client.messages.MessageMethods.iter_messages>`.
+
+        By default, all parameters are `None`, and you need to enable those
+        you plan to use by setting them to either `True` or `False`.
+
+        You should ``except errors.TakeoutInitDelayError as e``, since this
+        exception will raise depending on the condition of the session. You
+        can then access ``e.seconds`` to know how long you should wait for
+        before calling the method again.
+
+        There's also a `success` property available in the takeout proxy
+        object, so from the `with` body you can set the boolean result that
+        will be sent back to Telegram. But if it's left `None` as by
+        default, then the action is based on the `finalize` parameter. If
+        it's `True` then the takeout will be finished, and if no exception
+        occurred during it, then `True` will be considered as a result.
+        Otherwise, the takeout will not be finished and its ID will be
+        preserved for future usage as `client.session.takeout_id
+        <telethon.sessions.abstract.Session.takeout_id>`.
+
+        Arguments
+            finalize (`bool`):
+                Whether the takeout session should be finalized upon
+                exit or not.
+
+            contacts (`bool`):
+                Set to `True` if you plan on downloading contacts.
+
+            users (`bool`):
+                Set to `True` if you plan on downloading information
+                from users and their private conversations with you.
+
+            chats (`bool`):
+                Set to `True` if you plan on downloading information
+                from small group chats, such as messages and media.
+
+            megagroups (`bool`):
+                Set to `True` if you plan on downloading information
+                from megagroups (channels), such as messages and media.
+
+            channels (`bool`):
+                Set to `True` if you plan on downloading information
+                from broadcast channels, such as messages and media.
+
+            files (`bool`):
+                Set to `True` if you plan on downloading media and
+                you don't only wish to export messages.
+
+            max_file_size (`int`):
+                The maximum file size, in bytes, that you plan
+                to download for each message with media.
+
+        Example
+            .. code-block:: python
+
+                from telethon import errors
+
+                try:
+                    async with client.takeout() as takeout:
+                        await client.get_messages('me')  # normal call
+                        await takeout.get_messages('me')  # wrapped through takeout (less limits)
+
+                        async for message in takeout.iter_messages(chat, wait_time=0):
+                            ...  # Do something with the message
+
+                except errors.TakeoutInitDelayError as e:
+                    print('Must wait', e.seconds, 'before takeout')
+        """
+        request_kwargs = dict(
+            contacts=contacts,
+            message_users=users,
+            message_chats=chats,
+            message_megagroups=megagroups,
+            message_channels=channels,
+            files=files,
+            file_max_size=max_file_size
+        )
+        arg_specified = (arg is not None for arg in request_kwargs.values())
+
+        if self.session.takeout_id is None or any(arg_specified):
+            request = functions.account.InitTakeoutSessionRequest(
+                **request_kwargs)
+        else:
+            request = None
+
+        return _TakeoutClient(finalize, self, request)
+
+    async def end_takeout(self: 'TelegramClient', success: bool) -> bool:
+        """
+        Finishes the current takeout session.
+
+        Arguments
+            success (`bool`):
+                Whether the takeout completed successfully or not.
+
+        Returns
+            `True` if the operation was successful, `False` otherwise.
+
+        Example
+            .. code-block:: python
+
+                await client.end_takeout(success=False)
+        """
+        try:
+            async with _TakeoutClient(True, self, None) as takeout:
+                takeout.success = success
+        except ValueError:
+            return False
+        return True

telethon/client/auth.py

@@ -0,0 +1,677 @@
+import getpass
+import inspect
+import os
+import sys
+import typing
+import warnings
+
+from .. import utils, helpers, errors, password as pwd_mod
+from ..tl import types, functions, custom
+from .._updates import SessionState
+
+if typing.TYPE_CHECKING:
+    from .telegramclient import TelegramClient
+
+
+class AuthMethods:
+
+    # region Public methods
+
+    def start(
+            self: 'TelegramClient',
+            phone: typing.Union[typing.Callable[[], str], str] = lambda: input('Please enter your phone (or bot token): '),
+            password: typing.Union[typing.Callable[[], str], str] = lambda: getpass.getpass('Please enter your password: '),
+            *,
+            bot_token: str = None,
+            force_sms: bool = False,
+            code_callback: typing.Callable[[], typing.Union[str, int]] = None,
+            first_name: str = 'New User',
+            last_name: str = '',
+            max_attempts: int = 3) -> 'TelegramClient':
+        """
+        Starts the client (connects and logs in if necessary).
+
+        By default, this method will be interactive (asking for
+        user input if needed), and will handle 2FA if enabled too.
+
+        If the event loop is already running, this method returns a
+        coroutine that you should await on your own code; otherwise
+        the loop is ran until said coroutine completes.
+
+        Arguments
+            phone (`str` | `int` | `callable`):
+                The phone (or callable without arguments to get it)
+                to which the code will be sent. If a bot-token-like
+                string is given, it will be used as such instead.
+                The argument may be a coroutine.
+
+            password (`str`, `callable`, optional):
+                The password for 2 Factor Authentication (2FA).
+                This is only required if it is enabled in your account.
+                The argument may be a coroutine.
+
+            bot_token (`str`):
+                Bot Token obtained by `@BotFather <https://t.me/BotFather>`_
+                to log in as a bot. Cannot be specified with ``phone`` (only
+                one of either allowed).
+
+            force_sms (`bool`, optional):
+                Whether to force sending the code request as SMS.
+                This only makes sense when signing in with a `phone`.
+
+            code_callback (`callable`, optional):
+                A callable that will be used to retrieve the Telegram
+                login code. Defaults to `input()`.
+                The argument may be a coroutine.
+
+            first_name (`str`, optional):
+                The first name to be used if signing up. This has no
+                effect if the account already exists and you sign in.
+
+            last_name (`str`, optional):
+                Similar to the first name, but for the last. Optional.
+
+            max_attempts (`int`, optional):
+                How many times the code/password callback should be
+                retried or switching between signing in and signing up.
+
+        Returns
+            This `TelegramClient`, so initialization
+            can be chained with ``.start()``.
+
+        Example
+            .. code-block:: python
+
+                client = TelegramClient('anon', api_id, api_hash)
+
+                # Starting as a bot account
+                await client.start(bot_token=bot_token)
+
+                # Starting as a user account
+                await client.start(phone)
+                # Please enter the code you received: 12345
+                # Please enter your password: *******
+                # (You are now logged in)
+
+                # Starting using a context manager (this calls start()):
+                with client:
+                    pass
+        """
+        if code_callback is None:
+            def code_callback():
+                return input('Please enter the code you received: ')
+        elif not callable(code_callback):
+            raise ValueError(
+                'The code_callback parameter needs to be a callable '
+                'function that returns the code you received by Telegram.'
+            )
+
+        if not phone and not bot_token:
+            raise ValueError('No phone number or bot token provided.')
+
+        if phone and bot_token and not callable(phone):
+            raise ValueError('Both a phone and a bot token provided, '
+                             'must only provide one of either')
+
+        coro = self._start(
+            phone=phone,
+            password=password,
+            bot_token=bot_token,
+            force_sms=force_sms,
+            code_callback=code_callback,
+            first_name=first_name,
+            last_name=last_name,
+            max_attempts=max_attempts
+        )
+        return (
+            coro if self.loop.is_running()
+            else self.loop.run_until_complete(coro)
+        )
+
+    async def _start(
+            self: 'TelegramClient', phone, password, bot_token, force_sms,
+            code_callback, first_name, last_name, max_attempts):
+        if not self.is_connected():
+            await self.connect()
+
+        # Rather than using `is_user_authorized`, use `get_me`. While this is
+        # more expensive and needs to retrieve more data from the server, it
+        # enables the library to warn users trying to login to a different
+        # account. See #1172.
+        me = await self.get_me()
+        if me is not None:
+            # The warnings here are on a best-effort and may fail.
+            if bot_token:
+                # bot_token's first part has the bot ID, but it may be invalid
+                # so don't try to parse as int (instead cast our ID to string).
+                if bot_token[:bot_token.find(':')] != str(me.id):
+                    warnings.warn(
+                        'the session already had an authorized user so it did '
+                        'not login to the bot account using the provided bot_token; '
+                        'if you were expecting a different user, check whether '
+                        'you are accidentally reusing an existing session'
+                    )
+            elif phone and not callable(phone) and utils.parse_phone(phone) != me.phone:
+                warnings.warn(
+                    'the session already had an authorized user so it did '
+                    'not login to the user account using the provided phone; '
+                    'if you were expecting a different user, check whether '
+                    'you are accidentally reusing an existing session'
+                )
+
+            return self
+
+        if not bot_token:
+            # Turn the callable into a valid phone number (or bot token)
+            while callable(phone):
+                value = phone()
+                if inspect.isawaitable(value):
+                    value = await value
+
+                if ':' in value:
+                    # Bot tokens have 'user_id:access_hash' format
+                    bot_token = value
+                    break
+
+                phone = utils.parse_phone(value) or phone
+
+        if bot_token:
+            await self.sign_in(bot_token=bot_token)
+            return self
+
+        me = None
+        attempts = 0
+        two_step_detected = False
+
+        await self.send_code_request(phone, force_sms=force_sms)
+        while attempts < max_attempts:
+            try:
+                value = code_callback()
+                if inspect.isawaitable(value):
+                    value = await value
+
+                # Since sign-in with no code works (it sends the code)
+                # we must double-check that here. Else we'll assume we
+                # logged in, and it will return None as the User.
+                if not value:
+                    raise errors.PhoneCodeEmptyError(request=None)
+
+                # Raises SessionPasswordNeededError if 2FA enabled
+                me = await self.sign_in(phone, code=value)
+                break
+            except errors.SessionPasswordNeededError:
+                two_step_detected = True
+                break
+            except (errors.PhoneCodeEmptyError,
+                    errors.PhoneCodeExpiredError,
+                    errors.PhoneCodeHashEmptyError,
+                    errors.PhoneCodeInvalidError):
+                print('Invalid code. Please try again.', file=sys.stderr)
+
+            attempts += 1
+        else:
+            raise RuntimeError(
+                '{} consecutive sign-in attempts failed. Aborting'
+                .format(max_attempts)
+            )
+
+        if two_step_detected:
+            if not password:
+                raise ValueError(
+                    "Two-step verification is enabled for this account. "
+                    "Please provide the 'password' argument to 'start()'."
+                )
+
+            if callable(password):
+                for _ in range(max_attempts):
+                    try:
+                        value = password()
+                        if inspect.isawaitable(value):
+                            value = await value
+
+                        me = await self.sign_in(phone=phone, password=value)
+                        break
+                    except errors.PasswordHashInvalidError:
+                        print('Invalid password. Please try again',
+                              file=sys.stderr)
+                else:
+                    raise errors.PasswordHashInvalidError(request=None)
+            else:
+                me = await self.sign_in(phone=phone, password=password)
+
+        # We won't reach here if any step failed (exit by exception)
+        signed, name = 'Signed in successfully as ', utils.get_display_name(me)
+        tos = '; remember to not break the ToS or you will risk an account ban!'
+        try:
+            print(signed, name, tos, sep='')
+        except UnicodeEncodeError:
+            # Some terminals don't support certain characters
+            print(signed, name.encode('utf-8', errors='ignore')
+                              .decode('ascii', errors='ignore'), tos, sep='')
+
+        return self
+
+    def _parse_phone_and_hash(self, phone, phone_hash):
+        """
+        Helper method to both parse and validate phone and its hash.
+        """
+        phone = utils.parse_phone(phone) or self._phone
+        if not phone:
+            raise ValueError(
+                'Please make sure to call send_code_request first.'
+            )
+
+        phone_hash = phone_hash or self._phone_code_hash.get(phone, None)
+        if not phone_hash:
+            raise ValueError('You also need to provide a phone_code_hash.')
+
+        return phone, phone_hash
+
+    async def sign_in(
+            self: 'TelegramClient',
+            phone: str = None,
+            code: typing.Union[str, int] = None,
+            *,
+            password: str = None,
+            bot_token: str = None,
+            phone_code_hash: str = None) -> 'typing.Union[types.User, types.auth.SentCode]':
+        """
+        Logs in to Telegram to an existing user or bot account.
+
+        You should only use this if you are not authorized yet.
+
+        This method will send the code if it's not provided.
+
+        .. note::
+
+            In most cases, you should simply use `start()` and not this method.
+
+        Arguments
+            phone (`str` | `int`):
+                The phone to send the code to if no code was provided,
+                or to override the phone that was previously used with
+                these requests.
+
+            code (`str` | `int`):
+                The code that Telegram sent. Note that if you have sent this
+                code through the application itself it will immediately
+                expire. If you want to send the code, obfuscate it somehow.
+                If you're not doing any of this you can ignore this note.
+
+            password (`str`):
+                2FA password, should be used if a previous call raised
+                ``SessionPasswordNeededError``.
+
+            bot_token (`str`):
+                Used to sign in as a bot. Not all requests will be available.
+                This should be the hash the `@BotFather <https://t.me/BotFather>`_
+                gave you.
+
+            phone_code_hash (`str`, optional):
+                The hash returned by `send_code_request`. This can be left as
+                `None` to use the last hash known for the phone to be used.
+
+        Returns
+            The signed in user, or the information about
+            :meth:`send_code_request`.
+
+        Example
+            .. code-block:: python
+
+                phone = '+34 123 123 123'
+                await client.sign_in(phone)  # send code
+
+                code = input('enter code: ')
+                await client.sign_in(phone, code)
+        """
+        me = await self.get_me()
+        if me:
+            return me
+
+        if phone and not code and not password:
+            return await self.send_code_request(phone)
+        elif code:
+            phone, phone_code_hash = \
+                self._parse_phone_and_hash(phone, phone_code_hash)
+
+            # May raise PhoneCodeEmptyError, PhoneCodeExpiredError,
+            # PhoneCodeHashEmptyError or PhoneCodeInvalidError.
+            request = functions.auth.SignInRequest(
+                phone, phone_code_hash, str(code)
+            )
+        elif password:
+            pwd = await self(functions.account.GetPasswordRequest())
+            request = functions.auth.CheckPasswordRequest(
+                pwd_mod.compute_check(pwd, password)
+            )
+        elif bot_token:
+            request = functions.auth.ImportBotAuthorizationRequest(
+                flags=0, bot_auth_token=bot_token,
+                api_id=self.api_id, api_hash=self.api_hash
+            )
+        else:
+            raise ValueError(
+                'You must provide a phone and a code the first time, '
+                'and a password only if an RPCError was raised before.'
+            )
+
+        try:
+            result = await self(request)
+        except errors.PhoneCodeExpiredError:
+            self._phone_code_hash.pop(phone, None)
+            raise
+
+        if isinstance(result, types.auth.AuthorizationSignUpRequired):
+            # Emulate pre-layer 104 behaviour
+            self._tos = result.terms_of_service
+            raise errors.PhoneNumberUnoccupiedError(request=request)
+
+        return await self._on_login(result.user)
+
+    async def sign_up(
+            self: 'TelegramClient',
+            code: typing.Union[str, int],
+            first_name: str,
+            last_name: str = '',
+            *,
+            phone: str = None,
+            phone_code_hash: str = None) -> 'types.User':
+        """
+        This method can no longer be used, and will immediately raise a ``ValueError``.
+        See `issue #4050 <https://github.com/LonamiWebs/Telethon/issues/4050>`_ for context.
+        """
+        raise ValueError('Third-party applications cannot sign up for Telegram. See https://github.com/LonamiWebs/Telethon/issues/4050 for details')
+
+    async def _on_login(self, user):
+        """
+        Callback called whenever the login or sign up process completes.
+
+        Returns the input user parameter.
+        """
+        self._mb_entity_cache.set_self_user(user.id, user.bot, user.access_hash)
+        self._authorized = True
+
+        state = await self(functions.updates.GetStateRequest())
+        # the server may send an old qts in getState
+        difference = await self(functions.updates.GetDifferenceRequest(pts=state.pts, date=state.date, qts=state.qts))
+
+        if isinstance(difference, types.updates.Difference):
+            state = difference.state
+        elif isinstance(difference, types.updates.DifferenceSlice):
+            state = difference.intermediate_state
+        elif isinstance(difference, types.updates.DifferenceTooLong):
+            state.pts = difference.pts
+
+        self._message_box.load(SessionState(0, 0, 0, state.pts, state.qts, int(state.date.timestamp()), state.seq, 0), [])
+
+        return user
+
+    async def send_code_request(
+            self: 'TelegramClient',
+            phone: str,
+            *,
+            force_sms: bool = False,
+            _retry_count: int = 0) -> 'types.auth.SentCode':
+        """
+        Sends the Telegram code needed to login to the given phone number.
+
+        Arguments
+            phone (`str` | `int`):
+                The phone to which the code will be sent.
+
+            force_sms (`bool`, optional):
+                Whether to force sending as SMS. This has been deprecated.
+                See `issue #4050 <https://github.com/LonamiWebs/Telethon/issues/4050>`_ for context.
+
+        Returns
+            An instance of :tl:`SentCode`.
+
+        Example
+            .. code-block:: python
+
+                phone = '+34 123 123 123'
+                sent = await client.send_code_request(phone)
+                print(sent)
+        """
+        if force_sms:
+            warnings.warn('force_sms has been deprecated and no longer works')
+            force_sms = False
+
+        result = None
+        phone = utils.parse_phone(phone) or self._phone
+        phone_hash = self._phone_code_hash.get(phone)
+
+        if not phone_hash:
+            try:
+                result = await self(functions.auth.SendCodeRequest(
+                    phone, self.api_id, self.api_hash, types.CodeSettings()))
+            except errors.AuthRestartError:
+                if _retry_count > 2:
+                    raise
+                return await self.send_code_request(
+                    phone, force_sms=force_sms, _retry_count=_retry_count+1)
+
+            # TODO figure out when/if/how this can happen
+            if isinstance(result, types.auth.SentCodeSuccess):
+                raise RuntimeError('logged in right after sending the code')
+
+            # If we already sent a SMS, do not resend the code (hash may be empty)
+            if isinstance(result.type, types.auth.SentCodeTypeSms):
+                force_sms = False
+
+            # phone_code_hash may be empty, if it is, do not save it (#1283)
+            if result.phone_code_hash:
+                self._phone_code_hash[phone] = phone_hash = result.phone_code_hash
+        else:
+            force_sms = True
+
+        self._phone = phone
+
+        if force_sms:
+            try:
+                result = await self(
+                    functions.auth.ResendCodeRequest(phone, phone_hash))
+            except errors.PhoneCodeExpiredError:
+                if _retry_count > 2:
+                    raise
+                self._phone_code_hash.pop(phone, None)
+                self._log[__name__].info(
+                    "Phone code expired in ResendCodeRequest, requesting a new code"
+                )
+                return await self.send_code_request(
+                    phone, force_sms=False, _retry_count=_retry_count+1)
+
+            if isinstance(result, types.auth.SentCodeSuccess):
+                raise RuntimeError('logged in right after resending the code')
+
+            self._phone_code_hash[phone] = result.phone_code_hash
+
+        return result
+
+    async def qr_login(self: 'TelegramClient', ignored_ids: typing.List[int] = None) -> custom.QRLogin:
+        """
+        Initiates the QR login procedure.
+
+        Note that you must be connected before invoking this, as with any
+        other request.
+
+        It is up to the caller to decide how to present the code to the user,
+        whether it's the URL, using the token bytes directly, or generating
+        a QR code and displaying it by other means.
+
+        See the documentation for `QRLogin` to see how to proceed after this.
+
+        Arguments
+            ignored_ids (List[`int`]):
+                List of already logged-in user IDs, to prevent logging in
+                twice with the same user.
+
+        Returns
+            An instance of `QRLogin`.
+
+        Example
+            .. code-block:: python
+
+                def display_url_as_qr(url):
+                    pass  # do whatever to show url as a qr to the user
+
+                qr_login = await client.qr_login()
+                display_url_as_qr(qr_login.url)
+
+                # Important! You need to wait for the login to complete!
+                await qr_login.wait()
+
+                # If you have 2FA enabled, `wait` will raise `telethon.errors.SessionPasswordNeededError`.
+                # You should except that error and call `sign_in` with the password if this happens.
+        """
+        qr_login = custom.QRLogin(self, ignored_ids or [])
+        await qr_login.recreate()
+        return qr_login
+
+    async def log_out(self: 'TelegramClient') -> bool:
+        """
+        Logs out Telegram and deletes the current ``*.session`` file.
+
+        The client is unusable after logging out and a new instance should be created.
+
+        Returns
+            `True` if the operation was successful.
+
+        Example
+            .. code-block:: python
+
+                # Note: you will need to login again!
+                await client.log_out()
+        """
+        try:
+            await self(functions.auth.LogOutRequest())
+        except errors.RPCError:
+            return False
+
+        self._mb_entity_cache.set_self_user(None, None, None)
+        self._authorized = False
+
+        await self.disconnect()
+        await utils.maybe_async(self.session.delete())
+        self.session = None
+        return True
+
+    async def edit_2fa(
+            self: 'TelegramClient',
+            current_password: str = None,
+            new_password: str = None,
+            *,
+            hint: str = '',
+            email: str = None,
+            email_code_callback: typing.Callable[[int], str] = None) -> bool:
+        """
+        Changes the 2FA settings of the logged in user.
+
+        Review carefully the parameter explanations before using this method.
+
+        Note that this method may be *incredibly* slow depending on the
+        prime numbers that must be used during the process to make sure
+        that everything is safe.
+
+        Has no effect if both current and new password are omitted.
+
+        Arguments
+            current_password (`str`, optional):
+                The current password, to authorize changing to ``new_password``.
+                Must be set if changing existing 2FA settings.
+                Must **not** be set if 2FA is currently disabled.
+                Passing this by itself will remove 2FA (if correct).
+
+            new_password (`str`, optional):
+                The password to set as 2FA.
+                If 2FA was already enabled, ``current_password`` **must** be set.
+                Leaving this blank or `None` will remove the password.
+
+            hint (`str`, optional):
+                Hint to be displayed by Telegram when it asks for 2FA.
+                Leaving unspecified is highly discouraged.
+                Has no effect if ``new_password`` is not set.
+
+            email (`str`, optional):
+                Recovery and verification email. If present, you must also
+                set `email_code_callback`, else it raises ``ValueError``.
+
+            email_code_callback (`callable`, optional):
+                If an email is provided, a callback that returns the code sent
+                to it must also be set. This callback may be asynchronous.
+                It should return a string with the code. The length of the
+                code will be passed to the callback as an input parameter.
+
+                If the callback returns an invalid code, it will raise
+                ``CodeInvalidError``.
+
+        Returns
+            `True` if successful, `False` otherwise.
+
+        Example
+            .. code-block:: python
+
+                # Setting a password for your account which didn't have
+                await client.edit_2fa(new_password='I_<3_Telethon')
+
+                # Removing the password
+                await client.edit_2fa(current_password='I_<3_Telethon')
+        """
+        if new_password is None and current_password is None:
+            return False
+
+        if email and not callable(email_code_callback):
+            raise ValueError('email present without email_code_callback')
+
+        pwd = await self(functions.account.GetPasswordRequest())
+        pwd.new_algo.salt1 += os.urandom(32)
+        assert isinstance(pwd, types.account.Password)
+        if not pwd.has_password and current_password:
+            current_password = None
+
+        if current_password:
+            password = pwd_mod.compute_check(pwd, current_password)
+        else:
+            password = types.InputCheckPasswordEmpty()
+
+        if new_password:
+            new_password_hash = pwd_mod.compute_digest(
+                pwd.new_algo, new_password)
+        else:
+            new_password_hash = b''
+
+        try:
+            await self(functions.account.UpdatePasswordSettingsRequest(
+                password=password,
+                new_settings=types.account.PasswordInputSettings(
+                    new_algo=pwd.new_algo,
+                    new_password_hash=new_password_hash,
+                    hint=hint,
+                    email=email,
+                    new_secure_settings=None
+                )
+            ))
+        except errors.EmailUnconfirmedError as e:
+            code = email_code_callback(e.code_length)
+            if inspect.isawaitable(code):
+                code = await code
+
+            code = str(code)
+            await self(functions.account.ConfirmPasswordEmailRequest(code))
+
+        return True
+
+    # endregion
+
+    # region with blocks
+
+    async def __aenter__(self):
+        return await self.start()
+
+    async def __aexit__(self, *args):
+        await self.disconnect()
+
+    __enter__ = helpers._sync_enter
+    __exit__ = helpers._sync_exit
+
+    # endregion

telethon/client/bots.py

@@ -0,0 +1,72 @@
+import typing
+
+from .. import hints
+from ..tl import types, functions, custom
+
+if typing.TYPE_CHECKING:
+    from .telegramclient import TelegramClient
+
+
+class BotMethods:
+    async def inline_query(
+            self: 'TelegramClient',
+            bot: 'hints.EntityLike',
+            query: str,
+            *,
+            entity: 'hints.EntityLike' = None,
+            offset: str = None,
+            geo_point: 'types.GeoPoint' = None) -> custom.InlineResults:
+        """
+        Makes an inline query to the specified bot (``@vote New Poll``).
+
+        Arguments
+            bot (`entity`):
+                The bot entity to which the inline query should be made.
+
+            query (`str`):
+                The query that should be made to the bot.
+
+            entity (`entity`, optional):
+                The entity where the inline query is being made from. Certain
+                bots use this to display different results depending on where
+                it's used, such as private chats, groups or channels.
+
+                If specified, it will also be the default entity where the
+                message will be sent after clicked. Otherwise, the "empty
+                peer" will be used, which some bots may not handle correctly.
+
+            offset (`str`, optional):
+                The string offset to use for the bot.
+
+            geo_point (:tl:`GeoPoint`, optional)
+                The geo point location information to send to the bot
+                for localised results. Available under some bots.
+
+        Returns
+            A list of `custom.InlineResult
+            <telethon.tl.custom.inlineresult.InlineResult>`.
+
+        Example
+            .. code-block:: python
+
+                # Make an inline query to @like
+                results = await client.inline_query('like', 'Do you like Telethon?')
+
+                # Send the first result to some chat
+                message = await results[0].click('TelethonOffTopic')
+        """
+        bot = await self.get_input_entity(bot)
+        if entity:
+            peer = await self.get_input_entity(entity)
+        else:
+            peer = types.InputPeerEmpty()
+
+        result = await self(functions.messages.GetInlineBotResultsRequest(
+            bot=bot,
+            peer=peer,
+            query=query,
+            offset=offset or '',
+            geo_point=geo_point
+        ))
+
+        return custom.InlineResults(self, result, entity=peer if entity else None)

telethon/client/buttons.py

@@ -0,0 +1,101 @@
+import typing
+
+from .. import utils, hints
+from ..tl import types, custom
+
+
+class ButtonMethods:
+    @staticmethod
+    def build_reply_markup(
+            buttons: 'typing.Optional[hints.MarkupLike]'
+    ) -> 'typing.Optional[types.TypeReplyMarkup]':
+        """
+        Builds a :tl:`ReplyInlineMarkup` or :tl:`ReplyKeyboardMarkup` for
+        the given buttons.
+
+        Does nothing if either no buttons are provided or the provided
+        argument is already a reply markup.
+
+        You should consider using this method if you are going to reuse
+        the markup very often. Otherwise, it is not necessary.
+
+        This method is **not** asynchronous (don't use ``await`` on it).
+
+        Arguments
+            buttons (`hints.MarkupLike`):
+                The button, list of buttons, array of buttons or markup
+                to convert into a markup.
+
+        Example
+            .. code-block:: python
+
+                from telethon import Button
+
+                markup = client.build_reply_markup(Button.inline('hi'))
+                # later
+                await client.send_message(chat, 'click me', buttons=markup)
+        """
+        if buttons is None:
+            return None
+
+        try:
+            if buttons.SUBCLASS_OF_ID == 0xe2e10ef2:  # crc32(b'ReplyMarkup'):
+                return buttons
+        except AttributeError:
+            pass
+
+        if not utils.is_list_like(buttons):
+            buttons = [[buttons]]
+        elif not buttons or not utils.is_list_like(buttons[0]):
+            buttons = [buttons]
+
+        is_inline = False
+        is_normal = False
+        resize = None
+        single_use = None
+        selective = None
+        persistent = None
+        placeholder = None
+
+        rows = []
+        for row in buttons:
+            current = []
+            for button in row:
+                if isinstance(button, custom.Button):
+                    if button.resize is not None:
+                        resize = button.resize
+                    if button.single_use is not None:
+                        single_use = button.single_use
+                    if button.selective is not None:
+                        selective = button.selective
+                    if button.persistent is not None:
+                        persistent = button.persistent
+                    if button.placeholder is not None:
+                        placeholder = button.placeholder
+
+                    button = button.button
+                elif isinstance(button, custom.MessageButton):
+                    button = button.button
+
+                inline = custom.Button._is_inline(button)
+                is_inline |= inline
+                is_normal |= not inline
+
+                if button.SUBCLASS_OF_ID == 0xbad74a3:  # crc32(b'KeyboardButton')
+                    current.append(button)
+
+            if current:
+                rows.append(types.KeyboardButtonRow(current))
+
+        if is_inline and is_normal:
+            raise ValueError('You cannot mix inline with normal buttons')
+        elif is_inline:
+            return types.ReplyInlineMarkup(rows)
+        return types.ReplyKeyboardMarkup(
+            rows=rows,
+            resize=resize,
+            single_use=single_use,
+            selective=selective,
+            persistent=persistent,
+            placeholder=placeholder
+        )

telethon/client/dialogs.py

@@ -0,0 +1,610 @@
+import asyncio
+import inspect
+import itertools
+import typing
+
+from .. import helpers, utils, hints, errors
+from ..requestiter import RequestIter
+from ..tl import types, functions, custom
+
+_MAX_CHUNK_SIZE = 100
+
+if typing.TYPE_CHECKING:
+    from .telegramclient import TelegramClient
+
+
+def _dialog_message_key(peer, message_id):
+    """
+    Get the key to get messages from a dialog.
+
+    We cannot just use the message ID because channels share message IDs,
+    and the peer ID is required to distinguish between them. But it is not
+    necessary in small group chats and private chats.
+    """
+    return (peer.channel_id if isinstance(peer, types.PeerChannel) else None), message_id
+
+
+class _DialogsIter(RequestIter):
+    async def _init(
+            self, offset_date, offset_id, offset_peer, ignore_pinned, ignore_migrated, folder
+    ):
+        self.request = functions.messages.GetDialogsRequest(
+            offset_date=offset_date,
+            offset_id=offset_id,
+            offset_peer=offset_peer,
+            limit=1,
+            hash=0,
+            exclude_pinned=ignore_pinned,
+            folder_id=folder
+        )
+
+        if self.limit <= 0:
+            # Special case, get a single dialog and determine count
+            dialogs = await self.client(self.request)
+            self.total = getattr(dialogs, 'count', len(dialogs.dialogs))
+            raise StopAsyncIteration
+
+        self.seen = set()
+        self.offset_date = offset_date
+        self.ignore_migrated = ignore_migrated
+
+    async def _load_next_chunk(self):
+        self.request.limit = min(self.left, _MAX_CHUNK_SIZE)
+        r = await self.client(self.request)
+
+        self.total = getattr(r, 'count', len(r.dialogs))
+
+        entities = {utils.get_peer_id(x): x
+                    for x in itertools.chain(r.users, r.chats)
+                    if not isinstance(x, (types.UserEmpty, types.ChatEmpty))}
+
+        self.client._mb_entity_cache.extend(r.users, r.chats)
+
+        messages = {}
+        for m in r.messages:
+            m._finish_init(self.client, entities, None)
+            messages[_dialog_message_key(m.peer_id, m.id)] = m
+
+        for d in r.dialogs:
+            # We check the offset date here because Telegram may ignore it
+            message = messages.get(_dialog_message_key(d.peer, d.top_message))
+            if self.offset_date:
+                date = getattr(message, 'date', None)
+                if not date or date.timestamp() > self.offset_date.timestamp():
+                    continue
+
+            peer_id = utils.get_peer_id(d.peer)
+            if peer_id not in self.seen:
+                self.seen.add(peer_id)
+                if peer_id not in entities:
+                    # > In which case can a UserEmpty appear in the list of banned members?
+                    # > In a very rare cases. This is possible but isn't an expected behavior.
+                    # Real world example: https://t.me/TelethonChat/271471
+                    continue
+
+                cd = custom.Dialog(self.client, d, entities, message)
+                if cd.dialog.pts:
+                    self.client._message_box.try_set_channel_state(
+                        utils.get_peer_id(d.peer, add_mark=False), cd.dialog.pts)
+
+                if not self.ignore_migrated or getattr(
+                        cd.entity, 'migrated_to', None) is None:
+                    self.buffer.append(cd)
+
+        if not self.buffer or len(r.dialogs) < self.request.limit\
+                or not isinstance(r, types.messages.DialogsSlice):
+            # Buffer being empty means all returned dialogs were skipped (due to offsets).
+            # Less than we requested means we reached the end, or
+            # we didn't get a DialogsSlice which means we got all.
+            return True
+
+        # We can't use `messages[-1]` as the offset ID / date.
+        # Why? Because pinned dialogs will mess with the order
+        # in this list. Instead, we find the last dialog which
+        # has a message, and use it as an offset.
+        last_message = next(filter(None, (
+            messages.get(_dialog_message_key(d.peer, d.top_message))
+            for d in reversed(r.dialogs)
+        )), None)
+
+        self.request.exclude_pinned = True
+        self.request.offset_id = last_message.id if last_message else 0
+        self.request.offset_date = last_message.date if last_message else None
+        self.request.offset_peer = self.buffer[-1].input_entity
+
+
+class _DraftsIter(RequestIter):
+    async def _init(self, entities, **kwargs):
+        if not entities:
+            r = await self.client(functions.messages.GetAllDraftsRequest())
+            items = r.updates
+        else:
+            peers = []
+            for entity in entities:
+                peers.append(types.InputDialogPeer(
+                    await self.client.get_input_entity(entity)))
+
+            r = await self.client(functions.messages.GetPeerDialogsRequest(peers))
+            items = r.dialogs
+
+        # TODO Maybe there should be a helper method for this?
+        entities = {utils.get_peer_id(x): x
+                    for x in itertools.chain(r.users, r.chats)}
+
+        self.buffer.extend(
+            custom.Draft(self.client, entities[utils.get_peer_id(d.peer)], d.draft)
+            for d in items
+        )
+
+    async def _load_next_chunk(self):
+        return []
+
+
+class DialogMethods:
+
+    # region Public methods
+
+    def iter_dialogs(
+            self: 'TelegramClient',
+            limit: float = None,
+            *,
+            offset_date: 'hints.DateLike' = None,
+            offset_id: int = 0,
+            offset_peer: 'hints.EntityLike' = types.InputPeerEmpty(),
+            ignore_pinned: bool = False,
+            ignore_migrated: bool = False,
+            folder: int = None,
+            archived: bool = None
+    ) -> _DialogsIter:
+        """
+        Iterator over the dialogs (open conversations/subscribed channels).
+
+        The order is the same as the one seen in official applications
+        (first pinned, them from those with the most recent message to
+        those with the oldest message).
+
+        Arguments
+            limit (`int` | `None`):
+                How many dialogs to be retrieved as maximum. Can be set to
+                `None` to retrieve all dialogs. Note that this may take
+                whole minutes if you have hundreds of dialogs, as Telegram
+                will tell the library to slow down through a
+                ``FloodWaitError``.
+
+            offset_date (`datetime`, optional):
+                The offset date to be used.
+
+            offset_id (`int`, optional):
+                The message ID to be used as an offset.
+
+            offset_peer (:tl:`InputPeer`, optional):
+                The peer to be used as an offset.
+
+            ignore_pinned (`bool`, optional):
+                Whether pinned dialogs should be ignored or not.
+                When set to `True`, these won't be yielded at all.
+
+            ignore_migrated (`bool`, optional):
+                Whether :tl:`Chat` that have ``migrated_to`` a :tl:`Channel`
+                should be included or not. By default all the chats in your
+                dialogs are returned, but setting this to `True` will ignore
+                (i.e. skip) them in the same way official applications do.
+
+            folder (`int`, optional):
+                The folder from which the dialogs should be retrieved.
+
+                If left unspecified, all dialogs (including those from
+                folders) will be returned.
+
+                If set to ``0``, all dialogs that don't belong to any
+                folder will be returned.
+
+                If set to a folder number like ``1``, only those from
+                said folder will be returned.
+
+                By default Telegram assigns the folder ID ``1`` to
+                archived chats, so you should use that if you need
+                to fetch the archived dialogs.
+
+            archived (`bool`, optional):
+                Alias for `folder`. If unspecified, all will be returned,
+                `False` implies ``folder=0`` and `True` implies ``folder=1``.
+        Yields
+            Instances of `Dialog <telethon.tl.custom.dialog.Dialog>`.
+
+        Example
+            .. code-block:: python
+
+                # Print all dialog IDs and the title, nicely formatted
+                async for dialog in client.iter_dialogs():
+                    print('{:>14}: {}'.format(dialog.id, dialog.title))
+        """
+        if archived is not None:
+            folder = 1 if archived else 0
+
+        return _DialogsIter(
+            self,
+            limit,
+            offset_date=offset_date,
+            offset_id=offset_id,
+            offset_peer=offset_peer,
+            ignore_pinned=ignore_pinned,
+            ignore_migrated=ignore_migrated,
+            folder=folder
+        )
+
+    async def get_dialogs(self: 'TelegramClient', *args, **kwargs) -> 'hints.TotalList':
+        """
+        Same as `iter_dialogs()`, but returns a
+        `TotalList <telethon.helpers.TotalList>` instead.
+
+        Example
+            .. code-block:: python
+
+                # Get all open conversation, print the title of the first
+                dialogs = await client.get_dialogs()
+                first = dialogs[0]
+                print(first.title)
+
+                # Use the dialog somewhere else
+                await client.send_message(first, 'hi')
+
+                # Getting only non-archived dialogs (both equivalent)
+                non_archived = await client.get_dialogs(folder=0)
+                non_archived = await client.get_dialogs(archived=False)
+
+                # Getting only archived dialogs (both equivalent)
+                archived = await client.get_dialogs(folder=1)
+                archived = await client.get_dialogs(archived=True)
+        """
+        return await self.iter_dialogs(*args, **kwargs).collect()
+
+    get_dialogs.__signature__ = inspect.signature(iter_dialogs)
+
+    def iter_drafts(
+            self: 'TelegramClient',
+            entity: 'hints.EntitiesLike' = None
+    ) -> _DraftsIter:
+        """
+        Iterator over draft messages.
+
+        The order is unspecified.
+
+        Arguments
+            entity (`hints.EntitiesLike`, optional):
+                The entity or entities for which to fetch the draft messages.
+                If left unspecified, all draft messages will be returned.
+
+        Yields
+            Instances of `Draft <telethon.tl.custom.draft.Draft>`.
+
+        Example
+            .. code-block:: python
+
+                # Clear all drafts
+                async for draft in client.get_drafts():
+                    await draft.delete()
+
+                # Getting the drafts with 'bot1' and 'bot2'
+                async for draft in client.iter_drafts(['bot1', 'bot2']):
+                    print(draft.text)
+        """
+        if entity and not utils.is_list_like(entity):
+            entity = (entity,)
+
+        # TODO Passing a limit here makes no sense
+        return _DraftsIter(self, None, entities=entity)
+
+    async def get_drafts(
+            self: 'TelegramClient',
+            entity: 'hints.EntitiesLike' = None
+    ) -> 'hints.TotalList':
+        """
+        Same as `iter_drafts()`, but returns a list instead.
+
+        Example
+            .. code-block:: python
+
+                # Get drafts, print the text of the first
+                drafts = await client.get_drafts()
+                print(drafts[0].text)
+
+                # Get the draft in your chat
+                draft = await client.get_drafts('me')
+                print(drafts.text)
+        """
+        items = await self.iter_drafts(entity).collect()
+        if not entity or utils.is_list_like(entity):
+            return items
+        else:
+            return items[0]
+
+    async def edit_folder(
+            self: 'TelegramClient',
+            entity: 'hints.EntitiesLike' = None,
+            folder: typing.Union[int, typing.Sequence[int]] = None,
+            *,
+            unpack=None
+    ) -> types.Updates:
+        """
+        Edits the folder used by one or more dialogs to archive them.
+
+        Arguments
+            entity (entities):
+                The entity or list of entities to move to the desired
+                archive folder.
+
+            folder (`int`):
+                The folder to which the dialog should be archived to.
+
+                If you want to "archive" a dialog, use ``folder=1``.
+
+                If you want to "un-archive" it, use ``folder=0``.
+
+                You may also pass a list with the same length as
+                `entities` if you want to control where each entity
+                will go.
+
+            unpack (`int`, optional):
+                If you want to unpack an archived folder, set this
+                parameter to the folder number that you want to
+                delete.
+
+                When you unpack a folder, all the dialogs inside are
+                moved to the folder number 0.
+
+                You can only use this parameter if the other two
+                are not set.
+
+        Returns
+            The :tl:`Updates` object that the request produces.
+
+        Example
+            .. code-block:: python
+
+                # Archiving the first 5 dialogs
+                dialogs = await client.get_dialogs(5)
+                await client.edit_folder(dialogs, 1)
+
+                # Un-archiving the third dialog (archiving to folder 0)
+                await client.edit_folder(dialog[2], 0)
+
+                # Moving the first dialog to folder 0 and the second to 1
+                dialogs = await client.get_dialogs(2)
+                await client.edit_folder(dialogs, [0, 1])
+
+                # Un-archiving all dialogs
+                await client.edit_folder(unpack=1)
+        """
+        if (entity is None) == (unpack is None):
+            raise ValueError('You can only set either entities or unpack, not both')
+
+        if unpack is not None:
+            return await self(functions.folders.DeleteFolderRequest(
+                folder_id=unpack
+            ))
+
+        if not utils.is_list_like(entity):
+            entities = [await self.get_input_entity(entity)]
+        else:
+            entities = await asyncio.gather(
+                *(self.get_input_entity(x) for x in entity))
+
+        if folder is None:
+            raise ValueError('You must specify a folder')
+        elif not utils.is_list_like(folder):
+            folder = [folder] * len(entities)
+        elif len(entities) != len(folder):
+            raise ValueError('Number of folders does not match number of entities')
+
+        return await self(functions.folders.EditPeerFoldersRequest([
+            types.InputFolderPeer(x, folder_id=y)
+            for x, y in zip(entities, folder)
+        ]))
+
+    async def delete_dialog(
+            self: 'TelegramClient',
+            entity: 'hints.EntityLike',
+            *,
+            revoke: bool = False
+    ):
+        """
+        Deletes a dialog (leaves a chat or channel).
+
+        This method can be used as a user and as a bot. However,
+        bots will only be able to use it to leave groups and channels
+        (trying to delete a private conversation will do nothing).
+
+        See also `Dialog.delete() <telethon.tl.custom.dialog.Dialog.delete>`.
+
+        Arguments
+            entity (entities):
+                The entity of the dialog to delete. If it's a chat or
+                channel, you will leave it. Note that the chat itself
+                is not deleted, only the dialog, because you left it.
+
+            revoke (`bool`, optional):
+                On private chats, you may revoke the messages from
+                the other peer too. By default, it's `False`. Set
+                it to `True` to delete the history for both.
+
+                This makes no difference for bot accounts, who can
+                only leave groups and channels.
+
+        Returns
+            The :tl:`Updates` object that the request produces,
+            or nothing for private conversations.
+
+        Example
+            .. code-block:: python
+
+                # Deleting the first dialog
+                dialogs = await client.get_dialogs(5)
+                await client.delete_dialog(dialogs[0])
+
+                # Leaving a channel by username
+                await client.delete_dialog('username')
+        """
+        # If we have enough information (`Dialog.delete` gives it to us),
+        # then we know we don't have to kick ourselves in deactivated chats.
+        if isinstance(entity, types.Chat):
+            deactivated = entity.deactivated
+        else:
+            deactivated = False
+
+        entity = await self.get_input_entity(entity)
+        ty = helpers._entity_type(entity)
+        if ty == helpers._EntityType.CHANNEL:
+            return await self(functions.channels.LeaveChannelRequest(entity))
+
+        if ty == helpers._EntityType.CHAT and not deactivated:
+            try:
+                result = await self(functions.messages.DeleteChatUserRequest(
+                    entity.chat_id, types.InputUserSelf(), revoke_history=revoke
+                ))
+            except errors.PeerIdInvalidError:
+                # Happens if we didn't have the deactivated information
+                result = None
+        else:
+            result = None
+
+        if not await self.is_bot():
+            await self(functions.messages.DeleteHistoryRequest(entity, 0, revoke=revoke))
+
+        return result
+
+    def conversation(
+            self: 'TelegramClient',
+            entity: 'hints.EntityLike',
+            *,
+            timeout: float = 60,
+            total_timeout: float = None,
+            max_messages: int = 100,
+            exclusive: bool = True,
+            replies_are_responses: bool = True) -> custom.Conversation:
+        """
+        Creates a `Conversation <telethon.tl.custom.conversation.Conversation>`
+        with the given entity.
+
+        .. note::
+
+            This Conversation API has certain shortcomings, such as lacking
+            persistence, poor interaction with other event handlers, and
+            overcomplicated usage for anything beyond the simplest case.
+
+            If you plan to interact with a bot without handlers, this works
+            fine, but when running a bot yourself, you may instead prefer
+            to follow the advice from https://stackoverflow.com/a/62246569/.
+
+        This is not the same as just sending a message to create a "dialog"
+        with them, but rather a way to easily send messages and await for
+        responses or other reactions. Refer to its documentation for more.
+
+        Arguments
+            entity (`entity`):
+                The entity with which a new conversation should be opened.
+
+            timeout (`int` | `float`, optional):
+                The default timeout (in seconds) *per action* to be used. You
+                may also override this timeout on a per-method basis. By
+                default each action can take up to 60 seconds (the value of
+                this timeout).
+
+            total_timeout (`int` | `float`, optional):
+                The total timeout (in seconds) to use for the whole
+                conversation. This takes priority over per-action
+                timeouts. After these many seconds pass, subsequent
+                actions will result in ``asyncio.TimeoutError``.
+
+            max_messages (`int`, optional):
+                The maximum amount of messages this conversation will
+                remember. After these many messages arrive in the
+                specified chat, subsequent actions will result in
+                ``ValueError``.
+
+            exclusive (`bool`, optional):
+                By default, conversations are exclusive within a single
+                chat. That means that while a conversation is open in a
+                chat, you can't open another one in the same chat, unless
+                you disable this flag.
+
+                If you try opening an exclusive conversation for
+                a chat where it's already open, it will raise
+                ``AlreadyInConversationError``.
+
+            replies_are_responses (`bool`, optional):
+                Whether replies should be treated as responses or not.
+
+                If the setting is enabled, calls to `conv.get_response
+                <telethon.tl.custom.conversation.Conversation.get_response>`
+                and a subsequent call to `conv.get_reply
+                <telethon.tl.custom.conversation.Conversation.get_reply>`
+                will return different messages, otherwise they may return
+                the same message.
+
+                Consider the following scenario with one outgoing message,
+                1, and two incoming messages, the second one replying::
+
+                                        Hello! <1
+                    2> (reply to 1) Hi!
+                    3> (reply to 1) How are you?
+
+                And the following code:
+
+                .. code-block:: python
+
+                    async with client.conversation(chat) as conv:
+                        msg1 = await conv.send_message('Hello!')
+                        msg2 = await conv.get_response()
+                        msg3 = await conv.get_reply()
+
+                With the setting enabled, ``msg2`` will be ``'Hi!'`` and
+                ``msg3`` be ``'How are you?'`` since replies are also
+                responses, and a response was already returned.
+
+                With the setting disabled, both ``msg2`` and ``msg3`` will
+                be ``'Hi!'`` since one is a response and also a reply.
+
+        Returns
+            A `Conversation <telethon.tl.custom.conversation.Conversation>`.
+
+        Example
+            .. code-block:: python
+
+                # <you> denotes outgoing messages you sent
+                # <usr> denotes incoming response messages
+                with bot.conversation(chat) as conv:
+                    # <you> Hi!
+                    conv.send_message('Hi!')
+
+                    # <usr> Hello!
+                    hello = conv.get_response()
+
+                    # <you> Please tell me your name
+                    conv.send_message('Please tell me your name')
+
+                    # <usr> ?
+                    name = conv.get_response().raw_text
+
+                    while not any(x.isalpha() for x in name):
+                        # <you> Your name didn't have any letters! Try again
+                        conv.send_message("Your name didn't have any letters! Try again")
+
+                        # <usr> Human
+                        name = conv.get_response().raw_text
+
+                    # <you> Thanks Human!
+                    conv.send_message('Thanks {}!'.format(name))
+        """
+        return custom.Conversation(
+            self,
+            entity,
+            timeout=timeout,
+            total_timeout=total_timeout,
+            max_messages=max_messages,
+            exclusive=exclusive,
+            replies_are_responses=replies_are_responses
+
+        )
+
+    # endregion

telethon/client/messageparse.py

@@ -0,0 +1,233 @@
+import itertools
+import re
+import typing
+
+from .. import helpers, utils
+from ..tl import types
+
+if typing.TYPE_CHECKING:
+    from .telegramclient import TelegramClient
+
+
+class MessageParseMethods:
+
+    # region Public properties
+
+    @property
+    def parse_mode(self: 'TelegramClient'):
+        """
+        This property is the default parse mode used when sending messages.
+        Defaults to `telethon.extensions.markdown`. It will always
+        be either `None` or an object with ``parse`` and ``unparse``
+        methods.
+
+        When setting a different value it should be one of:
+
+        * Object with ``parse`` and ``unparse`` methods.
+        * A ``callable`` to act as the parse method.
+        * A `str` indicating the ``parse_mode``. For Markdown ``'md'``
+          or ``'markdown'`` may be used. For HTML, ``'htm'`` or ``'html'``
+          may be used.
+
+        The ``parse`` method should be a function accepting a single
+        parameter, the text to parse, and returning a tuple consisting
+        of ``(parsed message str, [MessageEntity instances])``.
+
+        The ``unparse`` method should be the inverse of ``parse`` such
+        that ``assert text == unparse(*parse(text))``.
+
+        See :tl:`MessageEntity` for allowed message entities.
+
+        Example
+            .. code-block:: python
+
+                # Disabling default formatting
+                client.parse_mode = None
+
+                # Enabling HTML as the default format
+                client.parse_mode = 'html'
+        """
+        return self._parse_mode
+
+    @parse_mode.setter
+    def parse_mode(self: 'TelegramClient', mode: str):
+        self._parse_mode = utils.sanitize_parse_mode(mode)
+
+    # endregion
+
+    # region Private methods
+
+    async def _replace_with_mention(self: 'TelegramClient', entities, i, user):
+        """
+        Helper method to replace ``entities[i]`` to mention ``user``,
+        or do nothing if it can't be found.
+        """
+        try:
+            entities[i] = types.InputMessageEntityMentionName(
+                entities[i].offset, entities[i].length,
+                await self.get_input_entity(user)
+            )
+            return True
+        except (ValueError, TypeError):
+            return False
+
+    async def _parse_message_text(self: 'TelegramClient', message, parse_mode):
+        """
+        Returns a (parsed message, entities) tuple depending on ``parse_mode``.
+        """
+        if parse_mode == ():
+            parse_mode = self._parse_mode
+        else:
+            parse_mode = utils.sanitize_parse_mode(parse_mode)
+
+        if not parse_mode:
+            return message, []
+
+        original_message = message
+        message, msg_entities = parse_mode.parse(message)
+        if original_message and not message and not msg_entities:
+            raise ValueError("Failed to parse message")
+
+        for i in reversed(range(len(msg_entities))):
+            e = msg_entities[i]
+            if not e.length:
+                # 0-length MessageEntity is no longer valid #3884.
+                # Because the user can provide their own parser (with reasonable 0-length
+                # entities), strip them here rather than fixing the built-in parsers.
+                del msg_entities[i]
+            elif isinstance(e, types.MessageEntityTextUrl):
+                m = re.match(r'^@|\+|tg://user\?id=(\d+)', e.url)
+                if m:
+                    user = int(m.group(1)) if m.group(1) else e.url
+                    is_mention = await self._replace_with_mention(msg_entities, i, user)
+                    if not is_mention:
+                        del msg_entities[i]
+            elif isinstance(e, (types.MessageEntityMentionName,
+                                types.InputMessageEntityMentionName)):
+                is_mention = await self._replace_with_mention(msg_entities, i, e.user_id)
+                if not is_mention:
+                    del msg_entities[i]
+
+        return message, msg_entities
+
+    def _get_response_message(self: 'TelegramClient', request, result, input_chat):
+        """
+        Extracts the response message known a request and Update result.
+        The request may also be the ID of the message to match.
+
+        If ``request is None`` this method returns ``{id: message}``.
+
+        If ``request.random_id`` is a list, this method returns a list too.
+        """
+        if isinstance(result, types.UpdateShort):
+            updates = [result.update]
+            entities = {}
+        elif isinstance(result, (types.Updates, types.UpdatesCombined)):
+            updates = result.updates
+            entities = {utils.get_peer_id(x): x
+                        for x in
+                        itertools.chain(result.users, result.chats)}
+        else:
+            return None
+
+        random_to_id = {}
+        id_to_message = {}
+        for update in updates:
+            if isinstance(update, types.UpdateMessageID):
+                random_to_id[update.random_id] = update.id
+
+            elif isinstance(update, (
+                    types.UpdateNewChannelMessage, types.UpdateNewMessage)):
+                update.message._finish_init(self, entities, input_chat)
+
+                # Pinning a message with `updatePinnedMessage` seems to
+                # always produce a service message we can't map so return
+                # it directly. The same happens for kicking users.
+                #
+                # It could also be a list (e.g. when sending albums).
+                #
+                # TODO this method is getting messier and messier as time goes on
+                if hasattr(request, 'random_id') or utils.is_list_like(request):
+                    id_to_message[update.message.id] = update.message
+                else:
+                    return update.message
+
+            elif (isinstance(update, types.UpdateEditMessage)
+                  and helpers._entity_type(request.peer) != helpers._EntityType.CHANNEL):
+                update.message._finish_init(self, entities, input_chat)
+
+                # Live locations use `sendMedia` but Telegram responds with
+                # `updateEditMessage`, which means we won't have `id` field.
+                if hasattr(request, 'random_id'):
+                    id_to_message[update.message.id] = update.message
+                elif request.id == update.message.id:
+                    return update.message
+
+            elif (isinstance(update, types.UpdateEditChannelMessage)
+                  and utils.get_peer_id(request.peer) ==
+                  utils.get_peer_id(update.message.peer_id)):
+                if request.id == update.message.id:
+                    update.message._finish_init(self, entities, input_chat)
+                    return update.message
+
+            elif isinstance(update, types.UpdateNewScheduledMessage):
+                update.message._finish_init(self, entities, input_chat)
+                # Scheduled IDs may collide with normal IDs. However, for a
+                # single request there *shouldn't* be a mix between "some
+                # scheduled and some not".
+                id_to_message[update.message.id] = update.message
+
+            elif isinstance(update, types.UpdateMessagePoll):
+                if request.media.poll.id == update.poll_id:
+                    m = types.Message(
+                        id=request.id,
+                        peer_id=utils.get_peer(request.peer),
+                        media=types.MessageMediaPoll(
+                            poll=update.poll,
+                            results=update.results
+                        )
+                    )
+                    m._finish_init(self, entities, input_chat)
+                    return m
+
+        if request is None:
+            return id_to_message
+
+        random_id = request if isinstance(request, (int, list)) else getattr(request, 'random_id', None)
+        if random_id is None:
+            # Can happen when pinning a message does not actually produce a service message.
+            self._log[__name__].warning(
+                'No random_id in %s to map to, returning None message for %s', request, result)
+            return None
+
+        if not utils.is_list_like(random_id):
+            msg = id_to_message.get(random_to_id.get(random_id))
+
+            if not msg:
+                self._log[__name__].warning(
+                    'Request %s had missing message mapping %s', request, result)
+
+            return msg
+
+        try:
+            return [id_to_message[random_to_id[rnd]] for rnd in random_id]
+        except KeyError:
+            # Sometimes forwards fail (`MESSAGE_ID_INVALID` if a message gets
+            # deleted or `WORKER_BUSY_TOO_LONG_RETRY` if there are issues at
+            # Telegram), in which case we get some "missing" message mappings.
+            # Log them with the hope that we can better work around them.
+            #
+            # This also happens when trying to forward messages that can't
+            # be forwarded because they don't exist (0, service, deleted)
+            # among others which could be (like deleted or existing).
+            self._log[__name__].warning(
+                'Request %s had missing message mappings %s', request, result)
+
+        return [
+            id_to_message.get(random_to_id[rnd])
+            if rnd in random_to_id
+            else None
+            for rnd in random_id
+        ]
+
+    # endregion

telethon/client/telegrambaseclient.py

@@ -0,0 +1,971 @@
+import abc
+import inspect
+import re
+import asyncio
+import collections
+import logging
+import platform
+import time
+import typing
+import datetime
+import pathlib
+
+from .. import utils, version, helpers, __name__ as __base_name__
+from ..crypto import rsa
+from ..extensions import markdown
+from ..network import MTProtoSender, Connection, ConnectionTcpFull, TcpMTProxy
+from ..sessions import Session, SQLiteSession, MemorySession
+from ..tl import functions, types
+from ..tl.alltlobjects import LAYER
+from .._updates import MessageBox, EntityCache as MbEntityCache, SessionState, ChannelState, Entity, EntityType
+
+DEFAULT_DC_ID = 2
+DEFAULT_IPV4_IP = '149.154.167.51'
+DEFAULT_IPV6_IP = '2001:67c:4e8:f002::a'
+DEFAULT_PORT = 443
+
+if typing.TYPE_CHECKING:
+    from .telegramclient import TelegramClient
+
+_base_log = logging.getLogger(__base_name__)
+
+
+# In seconds, how long to wait before disconnecting a exported sender.
+_DISCONNECT_EXPORTED_AFTER = 60
+
+
+class _ExportState:
+    def __init__(self):
+        # ``n`` is the amount of borrows a given sender has;
+        # once ``n`` reaches ``0``, disconnect the sender after a while.
+        self._n = 0
+        self._zero_ts = 0
+        self._connected = False
+
+    def add_borrow(self):
+        self._n += 1
+        self._connected = True
+
+    def add_return(self):
+        self._n -= 1
+        assert self._n >= 0, 'returned sender more than it was borrowed'
+        if self._n == 0:
+            self._zero_ts = time.time()
+
+    def should_disconnect(self):
+        return (self._n == 0
+                and self._connected
+                and (time.time() - self._zero_ts) > _DISCONNECT_EXPORTED_AFTER)
+
+    def need_connect(self):
+        return not self._connected
+
+    def mark_disconnected(self):
+        assert self.should_disconnect(), 'marked as disconnected when it was borrowed'
+        self._connected = False
+
+
+# TODO How hard would it be to support both `trio` and `asyncio`?
+class TelegramBaseClient(abc.ABC):
+    """
+    This is the abstract base class for the client. It defines some
+    basic stuff like connecting, switching data center, etc, and
+    leaves the `__call__` unimplemented.
+
+    Arguments
+        session (`str` | `telethon.sessions.abstract.Session`, `None`):
+            The file name of the session file to be used if a string is
+            given (it may be a full path), or the Session instance to be
+            used otherwise. If it's `None`, the session will not be saved,
+            and you should call :meth:`.log_out()` when you're done.
+
+            Note that if you pass a string it will be a file in the current
+            working directory, although you can also pass absolute paths.
+
+            The session file contains enough information for you to login
+            without re-sending the code, so if you have to enter the code
+            more than once, maybe you're changing the working directory,
+            renaming or removing the file, or using random names.
+
+        api_id (`int` | `str`):
+            The API ID you obtained from https://my.telegram.org.
+
+        api_hash (`str`):
+            The API hash you obtained from https://my.telegram.org.
+
+        connection (`telethon.network.connection.common.Connection`, optional):
+            The connection instance to be used when creating a new connection
+            to the servers. It **must** be a type.
+
+            Defaults to `telethon.network.connection.tcpfull.ConnectionTcpFull`.
+
+        use_ipv6 (`bool`, optional):
+            Whether to connect to the servers through IPv6 or not.
+            By default this is `False` as IPv6 support is not
+            too widespread yet.
+
+        proxy (`tuple` | `list` | `dict`, optional):
+            An iterable consisting of the proxy info. If `connection` is
+            one of `MTProxy`, then it should contain MTProxy credentials:
+            ``('hostname', port, 'secret')``. Otherwise, it's meant to store
+            function parameters for PySocks, like ``(type, 'hostname', port)``.
+            See https://github.com/Anorov/PySocks#usage-1 for more.
+
+        local_addr (`str` | `tuple`, optional):
+            Local host address (and port, optionally) used to bind the socket to locally.
+            You only need to use this if you have multiple network cards and
+            want to use a specific one.
+
+        timeout (`int` | `float`, optional):
+            The timeout in seconds to be used when connecting.
+            This is **not** the timeout to be used when ``await``'ing for
+            invoked requests, and you should use ``asyncio.wait`` or
+            ``asyncio.wait_for`` for that.
+
+        request_retries (`int` | `None`, optional):
+            How many times a request should be retried. Request are retried
+            when Telegram is having internal issues (due to either
+            ``errors.ServerError`` or ``errors.RpcCallFailError``),
+            when there is a ``errors.FloodWaitError`` less than
+            `flood_sleep_threshold`, or when there's a migrate error.
+
+            May take a negative or `None` value for infinite retries, but
+            this is not recommended, since some requests can always trigger
+            a call fail (such as searching for messages).
+
+        connection_retries (`int` | `None`, optional):
+            How many times the reconnection should retry, either on the
+            initial connection or when Telegram disconnects us. May be
+            set to a negative or `None` value for infinite retries, but
+            this is not recommended, since the program can get stuck in an
+            infinite loop.
+
+        retry_delay (`int` | `float`, optional):
+            The delay in seconds to sleep between automatic reconnections.
+
+        auto_reconnect (`bool`, optional):
+            Whether reconnection should be retried `connection_retries`
+            times automatically if Telegram disconnects us or not.
+
+        sequential_updates (`bool`, optional):
+            By default every incoming update will create a new task, so
+            you can handle several updates in parallel. Some scripts need
+            the order in which updates are processed to be sequential, and
+            this setting allows them to do so.
+
+            If set to `True`, incoming updates will be put in a queue
+            and processed sequentially. This means your event handlers
+            should *not* perform long-running operations since new
+            updates are put inside of an unbounded queue.
+
+        flood_sleep_threshold (`int` | `float`, optional):
+            The threshold below which the library should automatically
+            sleep on flood wait and slow mode wait errors (inclusive). For instance, if a
+            ``FloodWaitError`` for 17s occurs and `flood_sleep_threshold`
+            is 20s, the library will ``sleep`` automatically. If the error
+            was for 21s, it would ``raise FloodWaitError`` instead. Values
+            larger than a day (like ``float('inf')``) will be changed to a day.
+
+        raise_last_call_error (`bool`, optional):
+            When API calls fail in a way that causes Telethon to retry
+            automatically, should the RPC error of the last attempt be raised
+            instead of a generic ValueError. This is mostly useful for
+            detecting when Telegram has internal issues.
+
+        device_model (`str`, optional):
+            "Device model" to be sent when creating the initial connection.
+            Defaults to 'PC (n)bit' derived from ``platform.uname().machine``, or its direct value if unknown.
+
+        system_version (`str`, optional):
+            "System version" to be sent when creating the initial connection.
+            Defaults to ``platform.uname().release`` stripped of everything ahead of -.
+
+        app_version (`str`, optional):
+            "App version" to be sent when creating the initial connection.
+            Defaults to `telethon.version.__version__`.
+
+        lang_code (`str`, optional):
+            "Language code" to be sent when creating the initial connection.
+            Defaults to ``'en'``.
+
+        system_lang_code (`str`, optional):
+            "System lang code"  to be sent when creating the initial connection.
+            Defaults to `lang_code`.
+
+        loop (`asyncio.AbstractEventLoop`, optional):
+            Asyncio event loop to use. Defaults to `asyncio.get_running_loop()`.
+            This argument is ignored.
+
+        base_logger (`str` | `logging.Logger`, optional):
+            Base logger name or instance to use.
+            If a `str` is given, it'll be passed to `logging.getLogger()`. If a
+            `logging.Logger` is given, it'll be used directly. If something
+            else or nothing is given, the default logger will be used.
+
+        receive_updates (`bool`, optional):
+            Whether the client will receive updates or not. By default, updates
+            will be received from Telegram as they occur.
+
+            Turning this off means that Telegram will not send updates at all
+            so event handlers, conversations, and QR login will not work.
+            However, certain scripts don't need updates, so this will reduce
+            the amount of bandwidth used.
+
+        entity_cache_limit (`int`, optional):
+            How many users, chats and channels to keep in the in-memory cache
+            at most. This limit is checked against when processing updates.
+
+            When this limit is reached or exceeded, all entities that are not
+            required for update handling will be flushed to the session file.
+
+            Note that this implies that there is a lower bound to the amount
+            of entities that must be kept in memory.
+
+            Setting this limit too low will cause the library to attempt to
+            flush entities to the session file even if no entities can be
+            removed from the in-memory cache, which will degrade performance.
+    """
+
+    # Current TelegramClient version
+    __version__ = version.__version__
+
+    # Cached server configuration (with .dc_options), can be "global"
+    _config = None
+    _cdn_config = None
+
+    # region Initialization
+
+    def __init__(
+            self: 'TelegramClient',
+            session: 'typing.Union[str, pathlib.Path, Session]',
+            api_id: int,
+            api_hash: str,
+            *,
+            connection: 'typing.Type[Connection]' = ConnectionTcpFull,
+            use_ipv6: bool = False,
+            proxy: typing.Union[tuple, dict] = None,
+            local_addr: typing.Union[str, tuple] = None,
+            timeout: int = 10,
+            request_retries: int = 5,
+            connection_retries: int = 5,
+            retry_delay: int = 1,
+            auto_reconnect: bool = True,
+            sequential_updates: bool = False,
+            flood_sleep_threshold: int = 60,
+            raise_last_call_error: bool = False,
+            device_model: str = None,
+            system_version: str = None,
+            app_version: str = None,
+            lang_code: str = 'en',
+            system_lang_code: str = 'en',
+            loop: asyncio.AbstractEventLoop = None,
+            base_logger: typing.Union[str, logging.Logger] = None,
+            receive_updates: bool = True,
+            catch_up: bool = False,
+            entity_cache_limit: int = 5000
+    ):
+        if not api_id or not api_hash:
+            raise ValueError(
+                "Your API ID or Hash cannot be empty or None. "
+                "Refer to telethon.rtfd.io for more information.")
+
+        self._use_ipv6 = use_ipv6
+
+        if isinstance(base_logger, str):
+            base_logger = logging.getLogger(base_logger)
+        elif not isinstance(base_logger, logging.Logger):
+            base_logger = _base_log
+
+        class _Loggers(dict):
+            def __missing__(self, key):
+                if key.startswith("telethon."):
+                    key = key.split('.', maxsplit=1)[1]
+
+                return base_logger.getChild(key)
+
+        self._log = _Loggers()
+
+        # Determine what session object we have
+        if isinstance(session, (str, pathlib.Path)):
+            try:
+                session = SQLiteSession(str(session))
+            except ImportError:
+                import warnings
+                warnings.warn(
+                    'The sqlite3 module is not available under this '
+                    'Python installation and no custom session '
+                    'instance was given; using MemorySession.\n'
+                    'You will need to re-login every time unless '
+                    'you use another session storage'
+                )
+                session = MemorySession()
+        elif session is None:
+            session = MemorySession()
+        elif not isinstance(session, Session):
+            raise TypeError(
+                'The given session must be a str or a Session instance.'
+            )
+
+        self.flood_sleep_threshold = flood_sleep_threshold
+
+        # TODO Use AsyncClassWrapper(session)
+        # ChatGetter and SenderGetter can use the in-memory _mb_entity_cache
+        # to avoid network access and the need for await in session files.
+        #
+        # The session files only wants the entities to persist
+        # them to disk, and to save additional useful information.
+        # TODO Session should probably return all cached
+        #      info of entities, not just the input versions
+        self.session = session
+        self.api_id = int(api_id)
+        self.api_hash = api_hash
+
+        # Current proxy implementation requires `sock_connect`, and some
+        # event loops lack this method. If the current loop is missing it,
+        # bail out early and suggest an alternative.
+        #
+        # TODO A better fix is obviously avoiding the use of `sock_connect`
+        #
+        # See https://github.com/LonamiWebs/Telethon/issues/1337 for details.
+        if not callable(getattr(self.loop, 'sock_connect', None)):
+            raise TypeError(
+                'Event loop of type {} lacks `sock_connect`, which is needed to use proxies.\n\n'
+                'Change the event loop in use to use proxies:\n'
+                '# https://github.com/LonamiWebs/Telethon/issues/1337\n'
+                'import asyncio\n'
+                'asyncio.set_event_loop(asyncio.SelectorEventLoop())'.format(
+                    self.loop.__class__.__name__
+                )
+            )
+
+        if local_addr is not None:
+            if use_ipv6 is False and ':' in local_addr:
+                raise TypeError(
+                    'A local IPv6 address must only be used with `use_ipv6=True`.'
+                )
+            elif use_ipv6 is True and ':' not in local_addr:
+                raise TypeError(
+                    '`use_ipv6=True` must only be used with a local IPv6 address.'
+                )
+
+        self._raise_last_call_error = raise_last_call_error
+
+        self._request_retries = request_retries
+        self._connection_retries = connection_retries
+        self._retry_delay = retry_delay or 0
+        self._proxy = proxy
+        self._local_addr = local_addr
+        self._timeout = timeout
+        self._auto_reconnect = auto_reconnect
+
+        assert isinstance(connection, type)
+        self._connection = connection
+        init_proxy = None if not issubclass(connection, TcpMTProxy) else \
+            types.InputClientProxy(*connection.address_info(proxy))
+
+        # Used on connection. Capture the variables in a lambda since
+        # exporting clients need to create this InvokeWithLayerRequest.
+        system = platform.uname()
+
+        if system.machine in ('x86_64', 'AMD64'):
+            default_device_model = 'PC 64bit'
+        elif system.machine in ('i386','i686','x86'):
+            default_device_model = 'PC 32bit'
+        else:
+            default_device_model = system.machine
+        default_system_version = re.sub(r'-.+','',system.release)
+
+        self._init_request = functions.InitConnectionRequest(
+            api_id=self.api_id,
+            device_model=device_model or default_device_model or 'Unknown',
+            system_version=system_version or default_system_version or '1.0',
+            app_version=app_version or self.__version__,
+            lang_code=lang_code,
+            system_lang_code=system_lang_code,
+            lang_pack='',  # "langPacks are for official apps only"
+            query=None,
+            proxy=init_proxy
+        )
+
+        # Remember flood-waited requests to avoid making them again
+        self._flood_waited_requests = {}
+
+        # Cache ``{dc_id: (_ExportState, MTProtoSender)}`` for all borrowed senders
+        self._borrowed_senders = {}
+        self._borrow_sender_lock = asyncio.Lock()
+        self._exported_sessions = {}
+
+        self._loop = None  # only used as a sanity check
+        self._updates_error = None
+        self._updates_handle = None
+        self._keepalive_handle = None
+        self._last_request = time.time()
+        self._no_updates = not receive_updates
+
+        # Used for non-sequential updates, in order to terminate all pending tasks on disconnect.
+        self._sequential_updates = sequential_updates
+        self._event_handler_tasks = set()
+
+        self._authorized = None  # None = unknown, False = no, True = yes
+
+        # Some further state for subclasses
+        self._event_builders = []
+
+        # {chat_id: {Conversation}}
+        self._conversations = collections.defaultdict(set)
+
+        # Hack to workaround the fact Telegram may send album updates as
+        # different Updates when being sent from a different data center.
+        # {grouped_id: AlbumHack}
+        #
+        # FIXME: We don't bother cleaning this up because it's not really
+        #        worth it, albums are pretty rare and this only holds them
+        #        for a second at most.
+        self._albums = {}
+
+        # Default parse mode
+        self._parse_mode = markdown
+
+        # Some fields to easy signing in. Let {phone: hash} be
+        # a dictionary because the user may change their mind.
+        self._phone_code_hash = {}
+        self._phone = None
+        self._tos = None
+
+        # A place to store if channels are a megagroup or not (see `edit_admin`)
+        self._megagroup_cache = {}
+
+        # This is backported from v2 in a very ad-hoc way just to get proper update handling
+        self._catch_up = catch_up
+        self._updates_queue = asyncio.Queue()
+        self._message_box = MessageBox(self._log['messagebox'])
+        self._mb_entity_cache = MbEntityCache()  # required for proper update handling (to know when to getDifference)
+        self._entity_cache_limit = entity_cache_limit
+
+        self._sender = MTProtoSender(
+            self.session.auth_key,
+            loggers=self._log,
+            retries=self._connection_retries,
+            delay=self._retry_delay,
+            auto_reconnect=self._auto_reconnect,
+            connect_timeout=self._timeout,
+            auth_key_callback=self._auth_key_callback,
+            updates_queue=self._updates_queue,
+            auto_reconnect_callback=self._handle_auto_reconnect
+        )
+
+
+    # endregion
+
+    # region Properties
+
+    @property
+    def loop(self: 'TelegramClient') -> asyncio.AbstractEventLoop:
+        """
+        Property with the ``asyncio`` event loop used by this client.
+
+        Example
+            .. code-block:: python
+
+                # Download media in the background
+                task = client.loop.create_task(message.download_media())
+
+                # Do some work
+                ...
+
+                # Join the task (wait for it to complete)
+                await task
+        """
+        return helpers.get_running_loop()
+
+    @property
+    def disconnected(self: 'TelegramClient') -> asyncio.Future:
+        """
+        Property with a ``Future`` that resolves upon disconnection.
+
+        Example
+            .. code-block:: python
+
+                # Wait for a disconnection to occur
+                try:
+                    await client.disconnected
+                except OSError:
+                    print('Error on disconnect')
+        """
+        return self._sender.disconnected
+
+    @property
+    def flood_sleep_threshold(self):
+        return self._flood_sleep_threshold
+
+    @flood_sleep_threshold.setter
+    def flood_sleep_threshold(self, value):
+        # None -> 0, negative values don't really matter
+        self._flood_sleep_threshold = min(value or 0, 24 * 60 * 60)
+
+    # endregion
+
+    # region Connecting
+
+    async def connect(self: 'TelegramClient') -> None:
+        """
+        Connects to Telegram.
+
+        .. note::
+
+            Connect means connect and nothing else, and only one low-level
+            request is made to notify Telegram about which layer we will be
+            using.
+
+            Before Telegram sends you updates, you need to make a high-level
+            request, like `client.get_me() <telethon.client.users.UserMethods.get_me>`,
+            as described in https://core.telegram.org/api/updates.
+
+        Example
+            .. code-block:: python
+
+                try:
+                    await client.connect()
+                except OSError:
+                    print('Failed to connect')
+        """
+        if self.session is None:
+            raise ValueError('TelegramClient instance cannot be reused after logging out')
+
+        if self._loop is None:
+            self._loop = helpers.get_running_loop()
+        elif self._loop != helpers.get_running_loop():
+            raise RuntimeError('The asyncio event loop must not change after connection (see the FAQ for details)')
+
+        # ':' in session.server_address is True if it's an IPv6 address
+        if (not self.session.server_address or
+                (':' in self.session.server_address) != self._use_ipv6):
+            await utils.maybe_async(
+                self.session.set_dc(
+                    DEFAULT_DC_ID,
+                    DEFAULT_IPV6_IP if self._use_ipv6 else DEFAULT_IPV4_IP,
+                    DEFAULT_PORT
+                )
+            )
+            await utils.maybe_async(self.session.save())
+
+        if not await self._sender.connect(self._connection(
+            self.session.server_address,
+            self.session.port,
+            self.session.dc_id,
+            loggers=self._log,
+            proxy=self._proxy,
+            local_addr=self._local_addr
+        )):
+            # We don't want to init or modify anything if we were already connected
+            return
+
+        self.session.auth_key = self._sender.auth_key
+        await utils.maybe_async(self.session.save())
+
+        try:
+            # See comment when saving entities to understand this hack
+            self_entity = await utils.maybe_async(self.session.get_input_entity(0))
+            self_id = self_entity.access_hash
+            self_user = await utils.maybe_async(self.session.get_input_entity(self_id))
+            self._mb_entity_cache.set_self_user(self_id, None, self_user.access_hash)
+        except ValueError:
+            pass
+
+        if self._catch_up:
+            ss = SessionState(0, 0, False, 0, 0, 0, 0, None)
+            cs = []
+
+            update_states = await utils.maybe_async(self.session.get_update_states())
+            for entity_id, state in update_states:
+                if entity_id == 0:
+                    # TODO current session doesn't store self-user info but adding that is breaking on downstream session impls
+                    ss = SessionState(0, 0, False, state.pts, state.qts, int(state.date.timestamp()), state.seq, None)
+                else:
+                    cs.append(ChannelState(entity_id, state.pts))
+
+            self._message_box.load(ss, cs)
+            for state in cs:
+                try:
+                    entity = await utils.maybe_async(self.session.get_input_entity(state.channel_id))
+                except ValueError:
+                    self._log[__name__].warning(
+                        'No access_hash in cache for channel %s, will not catch up', state.channel_id)
+                else:
+                    self._mb_entity_cache.put(Entity(EntityType.CHANNEL, entity.channel_id, entity.access_hash))
+
+        self._init_request.query = functions.help.GetConfigRequest()
+
+        req = self._init_request
+        if self._no_updates:
+            req = functions.InvokeWithoutUpdatesRequest(req)
+
+        await self._sender.send(functions.InvokeWithLayerRequest(LAYER, req))
+
+        if self._message_box.is_empty():
+            me = await self.get_me()
+            if me:
+                await self._on_login(me)  # also calls GetState to initialize the MessageBox
+
+        self._updates_handle = self.loop.create_task(self._update_loop())
+        self._keepalive_handle = self.loop.create_task(self._keepalive_loop())
+
+    def is_connected(self: 'TelegramClient') -> bool:
+        """
+        Returns `True` if the user has connected.
+
+        This method is **not** asynchronous (don't use ``await`` on it).
+
+        Example
+            .. code-block:: python
+
+                while client.is_connected():
+                    await asyncio.sleep(1)
+        """
+        sender = getattr(self, '_sender', None)
+        return sender and sender.is_connected()
+
+    def disconnect(self: 'TelegramClient'):
+        """
+        Disconnects from Telegram.
+
+        If the event loop is already running, this method returns a
+        coroutine that you should await on your own code; otherwise
+        the loop is ran until said coroutine completes.
+
+        Event handlers which are currently running will be cancelled before
+        this function returns (in order to properly clean-up their tasks).
+        In particular, this means that using ``disconnect`` in a handler
+        will cause code after the ``disconnect`` to never run. If this is
+        needed, consider spawning a separate task to do the remaining work.
+
+        Example
+            .. code-block:: python
+
+                # You don't need to use this if you used "with client"
+                await client.disconnect()
+        """
+        if self.loop.is_running():
+            # Disconnect may be called from an event handler, which would
+            # cancel itself during itself and never actually complete the
+            # disconnection. Shield the task to prevent disconnect itself
+            # from being cancelled. See issue #3942 for more details.
+            return asyncio.shield(self.loop.create_task(self._disconnect_coro()))
+        else:
+            try:
+                self.loop.run_until_complete(self._disconnect_coro())
+            except RuntimeError:
+                # Python 3.5.x complains when called from
+                # `__aexit__` and there were pending updates with:
+                #   "Event loop stopped before Future completed."
+                #
+                # However, it doesn't really make a lot of sense.
+                pass
+
+    def set_proxy(self: 'TelegramClient', proxy: typing.Union[tuple, dict]):
+        """
+        Changes the proxy which will be used on next (re)connection.
+
+        Method has no immediate effects if the client is currently connected.
+
+        The new proxy will take it's effect on the next reconnection attempt:
+            - on a call `await client.connect()` (after complete disconnect)
+            - on auto-reconnect attempt (e.g, after previous connection was lost)
+        """
+        init_proxy = None if not issubclass(self._connection, TcpMTProxy) else \
+            types.InputClientProxy(*self._connection.address_info(proxy))
+
+        self._init_request.proxy = init_proxy
+        self._proxy = proxy
+
+        # While `await client.connect()` passes new proxy on each new call,
+        # auto-reconnect attempts use already set up `_connection` inside
+        # the `_sender`, so the only way to change proxy between those
+        # is to directly inject parameters.
+
+        connection = getattr(self._sender, "_connection", None)
+        if connection:
+            if isinstance(connection, TcpMTProxy):
+                connection._ip = proxy[0]
+                connection._port = proxy[1]
+            else:
+                connection._proxy = proxy
+
+    async def _save_states_and_entities(self: 'TelegramClient'):
+        # As a hack to not need to change the session files, save ourselves with ``id=0`` and ``access_hash`` of our ``id``.
+        # This way it is possible to determine our own ID by querying for 0. However, whether we're a bot is not saved.
+        # Piggy-back on an arbitrary TL type with users and chats so the session can understand to read the entities.
+        # It doesn't matter if we put users in the list of chats.
+        if self._mb_entity_cache.self_id:
+            await utils.maybe_async(
+                self.session.process_entities(
+                    types.contacts.ResolvedPeer(None, [types.InputPeerUser(0, self._mb_entity_cache.self_id)], [])
+                )
+            )
+
+        ss, cs = self._message_box.session_state()
+        await utils.maybe_async(self.session.set_update_state(0, types.updates.State(**ss, unread_count=0)))
+        now = datetime.datetime.now()  # any datetime works; channels don't need it
+        for channel_id, pts in cs.items():
+            await utils.maybe_async(
+                self.session.set_update_state(
+                    channel_id, types.updates.State(pts, 0, now, 0, unread_count=0)
+                )
+            )
+
+    async def _disconnect_coro(self: 'TelegramClient'):
+        if self.session is None:
+            return  # already logged out and disconnected
+
+        await self._disconnect()
+
+        # Also clean-up all exported senders because we're done with them
+        async with self._borrow_sender_lock:
+            for state, sender in self._borrowed_senders.values():
+                # Note that we're not checking for `state.should_disconnect()`.
+                # If the user wants to disconnect the client, ALL connections
+                # to Telegram (including exported senders) should be closed.
+                #
+                # Disconnect should never raise, so there's no try/except.
+                await sender.disconnect()
+                # Can't use `mark_disconnected` because it may be borrowed.
+                state._connected = False
+
+            # If any was borrowed
+            self._borrowed_senders.clear()
+
+        # trio's nurseries would handle this for us, but this is asyncio.
+        # All tasks spawned in the background should properly be terminated.
+        if self._event_handler_tasks:
+            for task in self._event_handler_tasks:
+                task.cancel()
+
+            await asyncio.wait(self._event_handler_tasks)
+            self._event_handler_tasks.clear()
+
+        await self._save_states_and_entities()
+
+        await utils.maybe_async(self.session.close())
+
+    async def _disconnect(self: 'TelegramClient'):
+        """
+        Disconnect only, without closing the session. Used in reconnections
+        to different data centers, where we don't want to close the session
+        file; user disconnects however should close it since it means that
+        their job with the client is complete and we should clean it up all.
+        """
+        await self._sender.disconnect()
+        await helpers._cancel(self._log[__name__],
+                              updates_handle=self._updates_handle,
+                              keepalive_handle=self._keepalive_handle)
+
+    async def _switch_dc(self: 'TelegramClient', new_dc):
+        """
+        Permanently switches the current connection to the new data center.
+        """
+        self._log[__name__].info('Reconnecting to new data center %s', new_dc)
+        dc = await self._get_dc(new_dc)
+
+        await utils.maybe_async(self.session.set_dc(dc.id, dc.ip_address, dc.port))
+        # auth_key's are associated with a server, which has now changed
+        # so it's not valid anymore. Set to None to force recreating it.
+        self._sender.auth_key.key = None
+        self.session.auth_key = None
+        await utils.maybe_async(self.session.save())
+        await self._disconnect()
+        return await self.connect()
+
+    async def _auth_key_callback(self: 'TelegramClient', auth_key):
+        """
+        Callback from the sender whenever it needed to generate a
+        new authorization key. This means we are not authorized.
+        """
+        self.session.auth_key = auth_key
+        await utils.maybe_async(self.session.save())
+
+    # endregion
+
+    # region Working with different connections/Data Centers
+
+    async def _get_dc(self: 'TelegramClient', dc_id, cdn=False):
+        """Gets the Data Center (DC) associated to 'dc_id'"""
+        cls = self.__class__
+        if not cls._config:
+            cls._config = await self(functions.help.GetConfigRequest())
+
+        if cdn and not self._cdn_config:
+            cls._cdn_config = await self(functions.help.GetCdnConfigRequest())
+            for pk in cls._cdn_config.public_keys:
+                if pk.dc_id == dc_id:
+                    rsa.add_key(pk.public_key, old=False)
+
+        try:
+            return next(
+                dc for dc in cls._config.dc_options
+                if dc.id == dc_id
+                and bool(dc.ipv6) == self._use_ipv6 and bool(dc.cdn) == cdn
+            )
+        except StopIteration:
+            self._log[__name__].warning(
+                'Failed to get DC %s (cdn = %s) with use_ipv6 = %s; retrying ignoring IPv6 check',
+                dc_id, cdn, self._use_ipv6
+            )
+            try:
+                return next(
+                    dc for dc in cls._config.dc_options
+                    if dc.id == dc_id and bool(dc.cdn) == cdn
+                )
+            except StopIteration:
+                raise ValueError(f'Failed to get DC {dc_id} (cdn = {cdn})')
+
+    async def _create_exported_sender(self: 'TelegramClient', dc_id):
+        """
+        Creates a new exported `MTProtoSender` for the given `dc_id` and
+        returns it. This method should be used by `_borrow_exported_sender`.
+        """
+        # Thanks badoualy/kotlogram on /telegram/api/DefaultTelegramClient.kt
+        # for clearly showing how to export the authorization
+        dc = await self._get_dc(dc_id)
+        # Can't reuse self._sender._connection as it has its own seqno.
+        #
+        # If one were to do that, Telegram would reset the connection
+        # with no further clues.
+        sender = MTProtoSender(None, loggers=self._log)
+        await sender.connect(self._connection(
+            dc.ip_address,
+            dc.port,
+            dc.id,
+            loggers=self._log,
+            proxy=self._proxy,
+            local_addr=self._local_addr
+        ))
+        self._log[__name__].info('Exporting auth for new borrowed sender in %s', dc)
+        auth = await self(functions.auth.ExportAuthorizationRequest(dc_id))
+        self._init_request.query = functions.auth.ImportAuthorizationRequest(id=auth.id, bytes=auth.bytes)
+        req = functions.InvokeWithLayerRequest(LAYER, self._init_request)
+        await sender.send(req)
+        return sender
+
+    async def _borrow_exported_sender(self: 'TelegramClient', dc_id):
+        """
+        Borrows a connected `MTProtoSender` for the given `dc_id`.
+        If it's not cached, creates a new one if it doesn't exist yet,
+        and imports a freshly exported authorization key for it to be usable.
+
+        Once its job is over it should be `_return_exported_sender`.
+        """
+        async with self._borrow_sender_lock:
+            self._log[__name__].debug('Borrowing sender for dc_id %d', dc_id)
+            state, sender = self._borrowed_senders.get(dc_id, (None, None))
+
+            if state is None:
+                state = _ExportState()
+                sender = await self._create_exported_sender(dc_id)
+                sender.dc_id = dc_id
+                self._borrowed_senders[dc_id] = (state, sender)
+
+            elif state.need_connect():
+                dc = await self._get_dc(dc_id)
+                await sender.connect(self._connection(
+                    dc.ip_address,
+                    dc.port,
+                    dc.id,
+                    loggers=self._log,
+                    proxy=self._proxy,
+                    local_addr=self._local_addr
+                ))
+
+            state.add_borrow()
+            return sender
+
+    async def _return_exported_sender(self: 'TelegramClient', sender):
+        """
+        Returns a borrowed exported sender. If all borrows have
+        been returned, the sender is cleanly disconnected.
+        """
+        async with self._borrow_sender_lock:
+            self._log[__name__].debug('Returning borrowed sender for dc_id %d', sender.dc_id)
+            state, _ = self._borrowed_senders[sender.dc_id]
+            state.add_return()
+
+    async def _clean_exported_senders(self: 'TelegramClient'):
+        """
+        Cleans-up all unused exported senders by disconnecting them.
+        """
+        async with self._borrow_sender_lock:
+            for dc_id, (state, sender) in self._borrowed_senders.items():
+                if state.should_disconnect():
+                    self._log[__name__].info(
+                        'Disconnecting borrowed sender for DC %d', dc_id)
+
+                    # Disconnect should never raise
+                    await sender.disconnect()
+                    state.mark_disconnected()
+
+    async def _get_cdn_client(self: 'TelegramClient', cdn_redirect):
+        """Similar to ._borrow_exported_client, but for CDNs"""
+        session = self._exported_sessions.get(cdn_redirect.dc_id)
+        if not session:
+            dc = await self._get_dc(cdn_redirect.dc_id, cdn=True)
+            session = await utils.maybe_async(self.session.clone())
+            await utils.maybe_async(session.set_dc(dc.id, dc.ip_address, dc.port))
+            self._exported_sessions[cdn_redirect.dc_id] = session
+
+        self._log[__name__].info('Creating new CDN client')
+        client = self.__class__(
+            session, self.api_id, self.api_hash,
+            proxy=self._proxy,
+            timeout=self._timeout,
+            loop=self.loop
+        )
+
+        session.auth_key = self._sender.auth_key
+        await client._sender.connect(self._connection(
+            session.server_address,
+            session.port,
+            session.dc_id,
+            loggers=self._log,
+            proxy=self._proxy,
+            local_addr=self._local_addr
+        ))
+        return client
+
+    # endregion
+
+    # region Invoking Telegram requests
+
+    @abc.abstractmethod
+    def __call__(self: 'TelegramClient', request, ordered=False):
+        """
+        Invokes (sends) one or more MTProtoRequests and returns (receives)
+        their result.
+
+        Args:
+            request (`TLObject` | `list`):
+                The request or requests to be invoked.
+
+            ordered (`bool`, optional):
+                Whether the requests (if more than one was given) should be
+                executed sequentially on the server. They run in arbitrary
+                order by default.
+
+            flood_sleep_threshold (`int` | `None`, optional):
+                The flood sleep threshold to use for this request. This overrides
+                the default value stored in
+                `client.flood_sleep_threshold <telethon.client.telegrambaseclient.TelegramBaseClient.flood_sleep_threshold>`
+
+        Returns:
+            The result of the request (often a `TLObject`) or a list of
+            results if more than one request was given.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def _update_loop(self: 'TelegramClient'):
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def _handle_auto_reconnect(self: 'TelegramClient'):
+        raise NotImplementedError
+
+    # endregion

telethon/client/telegramclient.py

@@ -0,0 +1,13 @@
+from . import (
+    AccountMethods, AuthMethods, DownloadMethods, DialogMethods, ChatMethods,
+    BotMethods, MessageMethods, UploadMethods, ButtonMethods, UpdateMethods,
+    MessageParseMethods, UserMethods, TelegramBaseClient
+)
+
+
+class TelegramClient(
+    AccountMethods, AuthMethods, DownloadMethods, DialogMethods, ChatMethods,
+    BotMethods, MessageMethods, UploadMethods, ButtonMethods, UpdateMethods,
+    MessageParseMethods, UserMethods, TelegramBaseClient
+):
+    pass

telethon/client/updates.py

@@ -0,0 +1,702 @@
+import asyncio
+import inspect
+import itertools
+import random
+import sys
+import time
+import traceback
+import typing
+import logging
+import warnings
+from collections import deque
+import sqlite3
+
+from .. import events, utils, errors
+from ..events.common import EventBuilder, EventCommon
+from ..tl import types, functions
+from .._updates import GapError, PrematureEndReason
+from ..helpers import get_running_loop
+from ..version import __version__
+
+
+if typing.TYPE_CHECKING:
+    from .telegramclient import TelegramClient
+
+
+Callback = typing.Callable[[typing.Any], typing.Any]
+
+class UpdateMethods:
+
+    # region Public methods
+
+    async def _run_until_disconnected(self: 'TelegramClient'):
+        try:
+            # Make a high-level request to notify that we want updates
+            await self(functions.updates.GetStateRequest())
+            result = await self.disconnected
+            if self._updates_error is not None:
+                raise self._updates_error
+            return result
+        except KeyboardInterrupt:
+            pass
+        finally:
+            await self.disconnect()
+
+    async def set_receive_updates(self: 'TelegramClient', receive_updates):
+        """
+        Change the value of `receive_updates`.
+
+        This is an `async` method, because in order for Telegram to start
+        sending updates again, a request must be made.
+        """
+        self._no_updates = not receive_updates
+        if receive_updates:
+            await self(functions.updates.GetStateRequest())
+
+    def run_until_disconnected(self: 'TelegramClient'):
+        """
+        Runs the event loop until the library is disconnected.
+
+        It also notifies Telegram that we want to receive updates
+        as described in https://core.telegram.org/api/updates.
+        If an unexpected error occurs during update handling,
+        the client will disconnect and said error will be raised.
+
+        Manual disconnections can be made by calling `disconnect()
+        <telethon.client.telegrambaseclient.TelegramBaseClient.disconnect>`
+        or sending a ``KeyboardInterrupt`` (e.g. by pressing ``Ctrl+C`` on
+        the console window running the script).
+
+        If a disconnection error occurs (i.e. the library fails to reconnect
+        automatically), said error will be raised through here, so you have a
+        chance to ``except`` it on your own code.
+
+        If the loop is already running, this method returns a coroutine
+        that you should await on your own code.
+
+        .. note::
+
+            If you want to handle ``KeyboardInterrupt`` in your code,
+            simply run the event loop in your code too in any way, such as
+            ``loop.run_forever()`` or ``await client.disconnected`` (e.g.
+            ``loop.run_until_complete(client.disconnected)``).
+
+        Example
+            .. code-block:: python
+
+                # Blocks the current task here until a disconnection occurs.
+                #
+                # You will still receive updates, since this prevents the
+                # script from exiting.
+                await client.run_until_disconnected()
+        """
+        if self.loop.is_running():
+            return self._run_until_disconnected()
+        try:
+            return self.loop.run_until_complete(self._run_until_disconnected())
+        except KeyboardInterrupt:
+            pass
+        finally:
+            # No loop.run_until_complete; it's already syncified
+            self.disconnect()
+
+    def on(self: 'TelegramClient', event: EventBuilder):
+        """
+        Decorator used to `add_event_handler` more conveniently.
+
+
+        Arguments
+            event (`_EventBuilder` | `type`):
+                The event builder class or instance to be used,
+                for instance ``events.NewMessage``.
+
+        Example
+            .. code-block:: python
+
+                from telethon import TelegramClient, events
+                client = TelegramClient(...)
+
+                # Here we use client.on
+                @client.on(events.NewMessage)
+                async def handler(event):
+                    ...
+        """
+        def decorator(f):
+            self.add_event_handler(f, event)
+            return f
+
+        return decorator
+
+    def add_event_handler(
+            self: 'TelegramClient',
+            callback: Callback,
+            event: EventBuilder = None):
+        """
+        Registers a new event handler callback.
+
+        The callback will be called when the specified event occurs.
+
+        Arguments
+            callback (`callable`):
+                The callable function accepting one parameter to be used.
+
+                Note that if you have used `telethon.events.register` in
+                the callback, ``event`` will be ignored, and instead the
+                events you previously registered will be used.
+
+            event (`_EventBuilder` | `type`, optional):
+                The event builder class or instance to be used,
+                for instance ``events.NewMessage``.
+
+                If left unspecified, `telethon.events.raw.Raw` (the
+                :tl:`Update` objects with no further processing) will
+                be passed instead.
+
+        Example
+            .. code-block:: python
+
+                from telethon import TelegramClient, events
+                client = TelegramClient(...)
+
+                async def handler(event):
+                    ...
+
+                client.add_event_handler(handler, events.NewMessage)
+        """
+        builders = events._get_handlers(callback)
+        if builders is not None:
+            for event in builders:
+                self._event_builders.append((event, callback))
+            return
+
+        if isinstance(event, type):
+            event = event()
+        elif not event:
+            event = events.Raw()
+
+        self._event_builders.append((event, callback))
+
+    def remove_event_handler(
+            self: 'TelegramClient',
+            callback: Callback,
+            event: EventBuilder = None) -> int:
+        """
+        Inverse operation of `add_event_handler()`.
+
+        If no event is given, all events for this callback are removed.
+        Returns how many callbacks were removed.
+
+        Example
+            .. code-block:: python
+
+                @client.on(events.Raw)
+                @client.on(events.NewMessage)
+                async def handler(event):
+                    ...
+
+                # Removes only the "Raw" handling
+                # "handler" will still receive "events.NewMessage"
+                client.remove_event_handler(handler, events.Raw)
+
+                # "handler" will stop receiving anything
+                client.remove_event_handler(handler)
+        """
+        found = 0
+        if event and not isinstance(event, type):
+            event = type(event)
+
+        i = len(self._event_builders)
+        while i:
+            i -= 1
+            ev, cb = self._event_builders[i]
+            if cb == callback and (not event or isinstance(ev, event)):
+                del self._event_builders[i]
+                found += 1
+
+        return found
+
+    def list_event_handlers(self: 'TelegramClient')\
+            -> 'typing.Sequence[typing.Tuple[Callback, EventBuilder]]':
+        """
+        Lists all registered event handlers.
+
+        Returns
+            A list of pairs consisting of ``(callback, event)``.
+
+        Example
+            .. code-block:: python
+
+                @client.on(events.NewMessage(pattern='hello'))
+                async def on_greeting(event):
+                    '''Greets someone'''
+                    await event.reply('Hi')
+
+                for callback, event in client.list_event_handlers():
+                    print(id(callback), type(event))
+        """
+        return [(callback, event) for event, callback in self._event_builders]
+
+    async def catch_up(self: 'TelegramClient'):
+        """
+        "Catches up" on the missed updates while the client was offline.
+        You should call this method after registering the event handlers
+        so that the updates it loads can by processed by your script.
+
+        This can also be used to forcibly fetch new updates if there are any.
+
+        Example
+            .. code-block:: python
+
+                await client.catch_up()
+        """
+        await self._updates_queue.put(types.UpdatesTooLong())
+
+    # endregion
+
+    # region Private methods
+
+    async def _update_loop(self: 'TelegramClient'):
+        # If the MessageBox is not empty, the account had to be logged-in to fill in its state.
+        # This flag is used to propagate the "you got logged-out" error up (but getting logged-out
+        # can only happen if it was once logged-in).
+        was_once_logged_in = self._authorized is True or not self._message_box.is_empty()
+
+        self._updates_error = None
+        try:
+            if self._catch_up:
+                # User wants to catch up as soon as the client is up and running,
+                # so this is the best place to do it.
+                await self.catch_up()
+
+            updates_to_dispatch = deque()
+
+            while self.is_connected():
+                if updates_to_dispatch:
+                    if self._sequential_updates:
+                        await self._dispatch_update(updates_to_dispatch.popleft())
+                    else:
+                        while updates_to_dispatch:
+                            # TODO if _dispatch_update fails for whatever reason, it's not logged! this should be fixed
+                            task = self.loop.create_task(self._dispatch_update(updates_to_dispatch.popleft()))
+                            self._event_handler_tasks.add(task)
+                            task.add_done_callback(self._event_handler_tasks.discard)
+
+                    continue
+
+                if len(self._mb_entity_cache) >= self._entity_cache_limit:
+                    self._log[__name__].info(
+                        'In-memory entity cache limit reached (%s/%s), flushing to session',
+                        len(self._mb_entity_cache),
+                        self._entity_cache_limit
+                    )
+                    await self._save_states_and_entities()
+                    self._mb_entity_cache.retain(lambda id: id == self._mb_entity_cache.self_id or id in self._message_box.map)
+                    if len(self._mb_entity_cache) >= self._entity_cache_limit:
+                        warnings.warn('in-memory entities exceed entity_cache_limit after flushing; consider setting a larger limit')
+
+                    self._log[__name__].info(
+                        'In-memory entity cache at %s/%s after flushing to session',
+                        len(self._mb_entity_cache),
+                        self._entity_cache_limit
+                    )
+
+
+                get_diff = self._message_box.get_difference()
+                if get_diff:
+                    self._log[__name__].debug('Getting difference for account updates')
+                    try:
+                        diff = await self(get_diff)
+                    except (
+                        errors.ServerError,
+                        errors.TimedOutError,
+                        errors.FloodWaitError,
+                        ValueError
+                    ) as e:
+                        # Telegram is having issues
+                        self._log[__name__].info('Cannot get difference since Telegram is having issues: %s', type(e).__name__)
+                        self._message_box.end_difference()
+                        continue
+                    except (errors.UnauthorizedError, errors.AuthKeyError) as e:
+                        # Not logged in or broken authorization key, can't get difference
+                        self._log[__name__].info('Cannot get difference since the account is not logged in: %s', type(e).__name__)
+                        self._message_box.end_difference()
+                        if was_once_logged_in:
+                            self._updates_error = e
+                            await self.disconnect()
+                            break
+                        continue
+                    except (errors.TypeNotFoundError, sqlite3.OperationalError) as e:
+                        # User is likely doing weird things with their account or session and Telegram gets confused as to what layer they use
+                        self._log[__name__].warning('Cannot get difference since the account is likely misusing the session: %s', e)
+                        self._message_box.end_difference()
+                        self._updates_error = e
+                        await self.disconnect()
+                        break
+                    except OSError as e:
+                        # Network is likely down, but it's unclear for how long.
+                        # If disconnect is called this task will be cancelled along with the sleep.
+                        # If disconnect is not called, getting difference should be retried after a few seconds.
+                        self._log[__name__].info('Cannot get difference since the network is down: %s: %s', type(e).__name__, e)
+                        await asyncio.sleep(5)
+                        continue
+                    updates, users, chats = self._message_box.apply_difference(diff, self._mb_entity_cache)
+                    if updates:
+                        self._log[__name__].info('Got difference for account updates')
+
+                    _preprocess_updates = await utils.maybe_async(self._preprocess_updates(updates, users, chats))
+                    updates_to_dispatch.extend(_preprocess_updates)
+                    continue
+
+                get_diff = self._message_box.get_channel_difference(self._mb_entity_cache)
+                if get_diff:
+                    self._log[__name__].debug('Getting difference for channel %s updates', get_diff.channel.channel_id)
+                    try:
+                        diff = await self(get_diff)
+                    except (errors.UnauthorizedError, errors.AuthKeyError) as e:
+                        # Not logged in or broken authorization key, can't get difference
+                        self._log[__name__].warning(
+                            'Cannot get difference for channel %s since the account is not logged in: %s',
+                            get_diff.channel.channel_id, type(e).__name__
+                        )
+                        self._message_box.end_channel_difference(
+                            get_diff,
+                            PrematureEndReason.TEMPORARY_SERVER_ISSUES,
+                            self._mb_entity_cache
+                        )
+                        if was_once_logged_in:
+                            self._updates_error = e
+                            await self.disconnect()
+                            break
+                        continue
+                    except (errors.TypeNotFoundError, sqlite3.OperationalError) as e:
+                        self._log[__name__].warning(
+                            'Cannot get difference for channel %s since the account is likely misusing the session: %s',
+                            get_diff.channel.channel_id, e
+                        )
+                        self._message_box.end_channel_difference(
+                            get_diff,
+                            PrematureEndReason.TEMPORARY_SERVER_ISSUES,
+                            self._mb_entity_cache
+                        )
+                        self._updates_error = e
+                        await self.disconnect()
+                        break
+                    except (
+                        errors.PersistentTimestampOutdatedError,
+                        errors.PersistentTimestampInvalidError,
+                        errors.ServerError,
+                        errors.TimedOutError,
+                        errors.FloodWaitError,
+                        ValueError
+                    ) as e:
+                        # According to Telegram's docs:
+                        # "Channel internal replication issues, try again later (treat this like an RPC_CALL_FAIL)."
+                        # We can treat this as "empty difference" and not update the local pts.
+                        # Then this same call will be retried when another gap is detected or timeout expires.
+                        #
+                        # Another option would be to literally treat this like an RPC_CALL_FAIL and retry after a few
+                        # seconds, but if Telegram is having issues it's probably best to wait for it to send another
+                        # update (hinting it may be okay now) and retry then.
+                        #
+                        # This is a bit hacky because MessageBox doesn't really have a way to "not update" the pts.
+                        # Instead we manually extract the previously-known pts and use that.
+                        #
+                        # For PersistentTimestampInvalidError:
+                        # Somehow our pts is either too new or the server does not know about this.
+                        # We treat this as PersistentTimestampOutdatedError for now.
+                        # TODO investigate why/when this happens and if this is the proper solution
+                        self._log[__name__].warning(
+                            'Getting difference for channel updates %s caused %s;'
+                            ' ending getting difference prematurely until server issues are resolved',
+                            get_diff.channel.channel_id, type(e).__name__
+                        )
+                        self._message_box.end_channel_difference(
+                            get_diff,
+                            PrematureEndReason.TEMPORARY_SERVER_ISSUES,
+                            self._mb_entity_cache
+                        )
+                        continue
+                    except (errors.ChannelPrivateError, errors.ChannelInvalidError):
+                        # Timeout triggered a get difference, but we have been banned in the channel since then.
+                        # Because we can no longer fetch updates from this channel, we should stop keeping track
+                        # of it entirely.
+                        self._log[__name__].info(
+                            'Account is now banned in %d so we can no longer fetch updates from it',
+                            get_diff.channel.channel_id
+                        )
+                        self._message_box.end_channel_difference(
+                            get_diff,
+                            PrematureEndReason.BANNED,
+                            self._mb_entity_cache
+                        )
+                        continue
+                    except OSError as e:
+                        self._log[__name__].info(
+                            'Cannot get difference for channel %d since the network is down: %s: %s',
+                            get_diff.channel.channel_id, type(e).__name__, e
+                        )
+                        await asyncio.sleep(5)
+                        continue
+
+                    updates, users, chats = self._message_box.apply_channel_difference(get_diff, diff, self._mb_entity_cache)
+                    if updates:
+                        self._log[__name__].info('Got difference for channel %d updates', get_diff.channel.channel_id)
+
+                    _preprocess_updates = await utils.maybe_async(self._preprocess_updates(updates, users, chats))
+                    updates_to_dispatch.extend(_preprocess_updates)
+                    continue
+
+                deadline = self._message_box.check_deadlines()
+                deadline_delay = deadline - get_running_loop().time()
+                if deadline_delay > 0:
+                    # Don't bother sleeping and timing out if the delay is already 0 (pollutes the logs).
+                    try:
+                        updates = await asyncio.wait_for(self._updates_queue.get(), deadline_delay)
+                    except asyncio.TimeoutError:
+                        self._log[__name__].debug('Timeout waiting for updates expired')
+                        continue
+                else:
+                    continue
+
+                processed = []
+                try:
+                    users, chats = self._message_box.process_updates(updates, self._mb_entity_cache, processed)
+                except GapError:
+                    continue  # get(_channel)_difference will start returning requests
+
+                _preprocess_updates = await utils.maybe_async(self._preprocess_updates(processed, users, chats))
+                updates_to_dispatch.extend(_preprocess_updates)
+        except asyncio.CancelledError:
+            pass
+        except Exception as e:
+            self._log[__name__].exception(f'Fatal error handling updates (this is a bug in Telethon v{__version__}, please report it)')
+            self._updates_error = e
+            await self.disconnect()
+
+    async def _preprocess_updates(self, updates, users, chats):
+        self._mb_entity_cache.extend(users, chats)
+        await utils.maybe_async(self.session.process_entities(types.contacts.ResolvedPeer(None, users, chats)))
+        entities = {utils.get_peer_id(x): x
+                    for x in itertools.chain(users, chats)}
+        for u in updates:
+            u._entities = entities
+        return updates
+
+    async def _keepalive_loop(self: 'TelegramClient'):
+        # Pings' ID don't really need to be secure, just "random"
+        rnd = lambda: random.randrange(-2**63, 2**63)
+        while self.is_connected():
+            try:
+                await asyncio.wait_for(
+                    self.disconnected, timeout=60
+                )
+                continue  # We actually just want to act upon timeout
+            except asyncio.TimeoutError:
+                pass
+            except asyncio.CancelledError:
+                return
+            except Exception:
+                continue  # Any disconnected exception should be ignored
+
+            # Check if we have any exported senders to clean-up periodically
+            await self._clean_exported_senders()
+
+            # Don't bother sending pings until the low-level connection is
+            # ready, otherwise a lot of pings will be batched to be sent upon
+            # reconnect, when we really don't care about that.
+            if not self._sender._transport_connected():
+                continue
+
+            # We also don't really care about their result.
+            # Just send them periodically.
+            try:
+                self._sender._keepalive_ping(rnd())
+            except (ConnectionError, asyncio.CancelledError):
+                return
+
+            # Entities and cached files are not saved when they are
+            # inserted because this is a rather expensive operation
+            # (default's sqlite3 takes ~0.1s to commit changes). Do
+            # it every minute instead. No-op if there's nothing new.
+            await self._save_states_and_entities()
+
+            await utils.maybe_async(self.session.save())
+
+    async def _dispatch_update(self: 'TelegramClient', update):
+        # TODO only used for AlbumHack, and MessageBox is not really designed for this
+        others = None
+
+        if not self._mb_entity_cache.self_id:
+            # Some updates require our own ID, so we must make sure
+            # that the event builder has offline access to it. Calling
+            # `get_me()` will cache it under `self._mb_entity_cache`.
+            #
+            # It will return `None` if we haven't logged in yet which is
+            # fine, we will just retry next time anyway.
+            try:
+                await self.get_me(input_peer=True)
+            except OSError:
+                pass  # might not have connection
+
+        built = EventBuilderDict(self, update, others)
+        for conv_set in self._conversations.values():
+            for conv in conv_set:
+                ev = built[events.NewMessage]
+                if ev:
+                    conv._on_new_message(ev)
+
+                ev = built[events.MessageEdited]
+                if ev:
+                    conv._on_edit(ev)
+
+                ev = built[events.MessageRead]
+                if ev:
+                    conv._on_read(ev)
+
+                if conv._custom:
+                    await conv._check_custom(built)
+
+        for builder, callback in self._event_builders:
+            event = built[type(builder)]
+            if not event:
+                continue
+
+            if not builder.resolved:
+                await builder.resolve(self)
+
+            filter = builder.filter(event)
+            if inspect.isawaitable(filter):
+                filter = await filter
+            if not filter:
+                continue
+
+            try:
+                await callback(event)
+            except errors.AlreadyInConversationError:
+                name = getattr(callback, '__name__', repr(callback))
+                self._log[__name__].debug(
+                    'Event handler "%s" already has an open conversation, '
+                    'ignoring new one', name)
+            except events.StopPropagation:
+                name = getattr(callback, '__name__', repr(callback))
+                self._log[__name__].debug(
+                    'Event handler "%s" stopped chain of propagation '
+                    'for event %s.', name, type(event).__name__
+                )
+                break
+            except Exception as e:
+                if not isinstance(e, asyncio.CancelledError) or self.is_connected():
+                    name = getattr(callback, '__name__', repr(callback))
+                    self._log[__name__].exception('Unhandled exception on %s', name)
+
+    async def _dispatch_event(self: 'TelegramClient', event):
+        """
+        Dispatches a single, out-of-order event. Used by `AlbumHack`.
+        """
+        # We're duplicating a most logic from `_dispatch_update`, but all in
+        # the name of speed; we don't want to make it worse for all updates
+        # just because albums may need it.
+        for builder, callback in self._event_builders:
+            if isinstance(builder, events.Raw):
+                continue
+            if not isinstance(event, builder.Event):
+                continue
+
+            if not builder.resolved:
+                await builder.resolve(self)
+
+            filter = builder.filter(event)
+            if inspect.isawaitable(filter):
+                filter = await filter
+            if not filter:
+                continue
+
+            try:
+                await callback(event)
+            except errors.AlreadyInConversationError:
+                name = getattr(callback, '__name__', repr(callback))
+                self._log[__name__].debug(
+                    'Event handler "%s" already has an open conversation, '
+                    'ignoring new one', name)
+            except events.StopPropagation:
+                name = getattr(callback, '__name__', repr(callback))
+                self._log[__name__].debug(
+                    'Event handler "%s" stopped chain of propagation '
+                    'for event %s.', name, type(event).__name__
+                )
+                break
+            except Exception as e:
+                if not isinstance(e, asyncio.CancelledError) or self.is_connected():
+                    name = getattr(callback, '__name__', repr(callback))
+                    self._log[__name__].exception('Unhandled exception on %s', name)
+
+    async def _handle_auto_reconnect(self: 'TelegramClient'):
+        # TODO Catch-up
+        # For now we make a high-level request to let Telegram
+        # know we are still interested in receiving more updates.
+        try:
+            await self.get_me()
+        except Exception as e:
+            self._log[__name__].warning('Error executing high-level request '
+                                        'after reconnect: %s: %s', type(e), e)
+
+        return
+        try:
+            self._log[__name__].info(
+                'Asking for the current state after reconnect...')
+
+            # TODO consider:
+            # If there aren't many updates while the client is disconnected
+            # (I tried with up to 20), Telegram seems to send them without
+            # asking for them (via updates.getDifference).
+            #
+            # On disconnection, the library should probably set a "need
+            # difference" or "catching up" flag so that any new updates are
+            # ignored, and then the library should call updates.getDifference
+            # itself to fetch them.
+            #
+            # In any case (either there are too many updates and Telegram
+            # didn't send them, or there isn't a lot and Telegram sent them
+            # but we dropped them), we fetch the new difference to get all
+            # missed updates. I feel like this would be the best solution.
+
+            # If a disconnection occurs, the old known state will be
+            # the latest one we were aware of, so we can catch up since
+            # the most recent state we were aware of.
+            await self.catch_up()
+
+            self._log[__name__].info('Successfully fetched missed updates')
+        except errors.RPCError as e:
+            self._log[__name__].warning('Failed to get missed updates after '
+                                        'reconnect: %r', e)
+        except Exception:
+            self._log[__name__].exception(
+                'Unhandled exception while getting update difference after reconnect')
+
+    # endregion
+
+
+class EventBuilderDict:
+    """
+    Helper "dictionary" to return events from types and cache them.
+    """
+    def __init__(self, client: 'TelegramClient', update, others):
+        self.client = client
+        self.update = update
+        self.others = others
+
+    def __getitem__(self, builder):
+        try:
+            return self.__dict__[builder]
+        except KeyError:
+            event = self.__dict__[builder] = builder.build(
+                self.update, self.others, self.client._self_id)
+
+            if isinstance(event, EventCommon):
+                event.original_update = self.update
+                event._entities = self.update._entities
+                event._set_client(self.client)
+            elif event:
+                event._client = self.client
+
+            return event

telethon/client/uploads.py

@@ -0,0 +1,870 @@
+import hashlib
+import io
+import itertools
+import os
+import pathlib
+import re
+import typing
+from io import BytesIO
+
+from ..crypto import AES
+
+from .. import utils, helpers, hints
+from ..tl import types, functions, custom
+
+try:
+    import PIL
+    import PIL.Image
+except ImportError:
+    PIL = None
+
+if typing.TYPE_CHECKING:
+    from .telegramclient import TelegramClient
+
+
+class _CacheType:
+    """Like functools.partial but pretends to be the wrapped class."""
+    def __init__(self, cls):
+        self._cls = cls
+
+    def __call__(self, *args, **kwargs):
+        return self._cls(*args, file_reference=b'', **kwargs)
+
+    def __eq__(self, other):
+        return self._cls == other
+
+
+def _resize_photo_if_needed(
+        file, is_image, width=2560, height=2560, background=(255, 255, 255)):
+
+    # https://github.com/telegramdesktop/tdesktop/blob/12905f0dcb9d513378e7db11989455a1b764ef75/Telegram/SourceFiles/boxes/photo_crop_box.cpp#L254
+    if (not is_image
+            or PIL is None
+            or (isinstance(file, io.IOBase) and not file.seekable())):
+        return file
+
+    if isinstance(file, bytes):
+        file = io.BytesIO(file)
+
+    if isinstance(file, io.IOBase):
+        # Pillow seeks to 0 unconditionally later anyway
+        old_pos = file.tell()
+        file.seek(0, io.SEEK_END)
+        before = file.tell()
+    elif isinstance(file, str) and os.path.exists(file):
+        # Check if file exists as a path and if so, get its size on disk
+        before = os.path.getsize(file)
+    else:
+        # Would be weird...
+        before = None
+
+    try:
+        # Don't use a `with` block for `image`, or `file` would be closed.
+        # See https://github.com/LonamiWebs/Telethon/issues/1121 for more.
+        image = PIL.Image.open(file)
+        try:
+            kwargs = {'exif': image.info['exif']}
+        except KeyError:
+            kwargs = {}
+
+        if image.mode == 'RGB':
+            # Check if image is within acceptable bounds, if so, check if the image is at or below 10 MB, or assume it isn't if size is None or 0
+            if image.width <= width and image.height <= height and (before <= 10000000 if before else False):
+                return file
+
+            # If the image is already RGB, don't convert it
+            # certain modes such as 'P' have no alpha index but can't be saved as JPEG directly
+            image.thumbnail((width, height), PIL.Image.LANCZOS)
+            result = image
+        else:
+            # We could save the resized image with the original format, but
+            # JPEG often compresses better -> smaller size -> faster upload
+            # We need to mask away the alpha channel ([3]), since otherwise
+            # IOError is raised when trying to save alpha channels in JPEG.
+            image.thumbnail((width, height), PIL.Image.LANCZOS)
+            result = PIL.Image.new('RGB', image.size, background)
+            mask = None
+
+            if image.has_transparency_data:
+                if image.mode == 'RGBA':
+                    mask = image.getchannel('A')
+                else:
+                    mask = image.convert('RGBA').getchannel('A')
+
+            result.paste(image, mask=mask)
+
+        buffer = io.BytesIO()
+        result.save(buffer, 'JPEG', progressive=True, **kwargs)
+        buffer.seek(0)
+        buffer.name = 'a.jpg'
+        return buffer
+    except IOError:
+        return file
+    finally:
+        # The original position might matter
+        if isinstance(file, io.IOBase):
+            file.seek(old_pos)
+
+
+class UploadMethods:
+
+    # region Public methods
+
+    async def send_file(
+            self: 'TelegramClient',
+            entity: 'hints.EntityLike',
+            file: 'typing.Union[hints.FileLike, typing.Sequence[hints.FileLike]]',
+            *,
+            caption: typing.Union[str, typing.Sequence[str]] = None,
+            force_document: bool = False,
+            mime_type: str = None,
+            file_size: int = None,
+            clear_draft: bool = False,
+            progress_callback: 'hints.ProgressCallback' = None,
+            reply_to: 'hints.MessageIDLike' = None,
+            attributes: 'typing.Sequence[types.TypeDocumentAttribute]' = None,
+            thumb: 'hints.FileLike' = None,
+            allow_cache: bool = True,
+            parse_mode: str = (),
+            formatting_entities: typing.Optional[
+                typing.Union[
+                    typing.List[types.TypeMessageEntity], typing.List[typing.List[types.TypeMessageEntity]]
+                ]
+            ] = None,
+            voice_note: bool = False,
+            video_note: bool = False,
+            buttons: typing.Optional['hints.MarkupLike'] = None,
+            silent: bool = None,
+            background: bool = None,
+            supports_streaming: bool = False,
+            schedule: 'hints.DateLike' = None,
+            comment_to: 'typing.Union[int, types.Message]' = None,
+            ttl: int = None,
+            nosound_video: bool = None,
+            send_as: typing.Optional['hints.EntityLike'] = None,
+            message_effect_id: typing.Optional[int] = None,
+            **kwargs) -> typing.Union[typing.List[typing.Any], typing.Any]:
+        """
+        Sends message with the given file to the specified entity.
+
+        .. note::
+
+            If the ``hachoir3`` package (``hachoir`` module) is installed,
+            it will be used to determine metadata from audio and video files.
+
+            If the ``pillow`` package is installed and you are sending a photo,
+            it will be resized to fit within the maximum dimensions allowed
+            by Telegram to avoid ``errors.PhotoInvalidDimensionsError``. This
+            cannot be done if you are sending :tl:`InputFile`, however.
+
+        Arguments
+            entity (`entity`):
+                Who will receive the file.
+
+            file (`str` | `bytes` | `file` | `media`):
+                The file to send, which can be one of:
+
+                * A local file path to an in-disk file. The file name
+                  will be the path's base name.
+
+                * A `bytes` byte array with the file's data to send
+                  (for example, by using ``text.encode('utf-8')``).
+                  A default file name will be used.
+
+                * A bytes `io.IOBase` stream over the file to send
+                  (for example, by using ``open(file, 'rb')``).
+                  Its ``.name`` property will be used for the file name,
+                  or a default if it doesn't have one.
+
+                * An external URL to a file over the internet. This will
+                  send the file as "external" media, and Telegram is the
+                  one that will fetch the media and send it.
+
+                * A Bot API-like ``file_id``. You can convert previously
+                  sent media to file IDs for later reusing with
+                  `telethon.utils.pack_bot_file_id`.
+
+                * A handle to an existing file (for example, if you sent a
+                  message with media before, you can use its ``message.media``
+                  as a file here).
+
+                * A handle to an uploaded file (from `upload_file`).
+
+                * A :tl:`InputMedia` instance. For example, if you want to
+                  send a dice use :tl:`InputMediaDice`, or if you want to
+                  send a contact use :tl:`InputMediaContact`.
+
+                To send an album, you should provide a list in this parameter.
+
+                If a list or similar is provided, the files in it will be
+                sent as an album in the order in which they appear, sliced
+                in chunks of 10 if more than 10 are given.
+
+            caption (`str`, optional):
+                Optional caption for the sent media message. When sending an
+                album, the caption may be a list of strings, which will be
+                assigned to the files pairwise.
+
+            force_document (`bool`, optional):
+                If left to `False` and the file is a path that ends with
+                the extension of an image file or a video file, it will be
+                sent as such. Otherwise always as a document.
+
+            mime_type (`str`, optional):
+                Custom mime type to use for the file to be sent (for example,
+                ``audio/mpeg``, ``audio/x-vorbis+ogg``, etc.).
+                It can change the type of files displayed.
+                If not set to any value, the mime type will be determined
+                automatically based on the file's extension.
+
+            file_size (`int`, optional):
+                The size of the file to be uploaded if it needs to be uploaded,
+                which will be determined automatically if not specified.
+
+                If the file size can't be determined beforehand, the entire
+                file will be read in-memory to find out how large it is.
+
+            clear_draft (`bool`, optional):
+                Whether the existing draft should be cleared or not.
+
+            progress_callback (`callable`, optional):
+                A callback function accepting two parameters:
+                ``(sent bytes, total)``.
+
+            reply_to (`int` | `Message <telethon.tl.custom.message.Message>`):
+                Same as `reply_to` from `send_message`.
+
+            attributes (`list`, optional):
+                Optional attributes that override the inferred ones, like
+                :tl:`DocumentAttributeFilename` and so on.
+
+            thumb (`str` | `bytes` | `file`, optional):
+                Optional JPEG thumbnail (for documents). **Telegram will
+                ignore this parameter** unless you pass a ``.jpg`` file!
+
+                The file must also be small in dimensions and in disk size.
+                Successful thumbnails were files below 20kB and 320x320px.
+                Width/height and dimensions/size ratios may be important.
+                For Telegram to accept a thumbnail, you must provide the
+                dimensions of the underlying media through ``attributes=``
+                with :tl:`DocumentAttributesVideo` or by installing the
+                optional ``hachoir`` dependency.
+
+
+            allow_cache (`bool`, optional):
+                This parameter currently does nothing, but is kept for
+                backward-compatibility (and it may get its use back in
+                the future).
+
+            parse_mode (`object`, optional):
+                See the `TelegramClient.parse_mode
+                <telethon.client.messageparse.MessageParseMethods.parse_mode>`
+                property for allowed values. Markdown parsing will be used by
+                default.
+
+            formatting_entities (`list`, optional):
+                Optional formatting entities for the sent media message. When sending an album,
+                `formatting_entities` can be a list of lists, where each inner list contains
+                `types.TypeMessageEntity`. Each inner list will be assigned to the corresponding
+                file in a pairwise manner with the caption. If provided, the ``parse_mode``
+                parameter will be ignored.
+
+            voice_note (`bool`, optional):
+                If `True` the audio will be sent as a voice note.
+
+            video_note (`bool`, optional):
+                If `True` the video will be sent as a video note,
+                also known as a round video message.
+
+            buttons (`list`, `custom.Button <telethon.tl.custom.button.Button>`, :tl:`KeyboardButton`):
+                The matrix (list of lists), row list or button to be shown
+                after sending the message. This parameter will only work if
+                you have signed in as a bot. You can also pass your own
+                :tl:`ReplyMarkup` here.
+
+            silent (`bool`, optional):
+                Whether the message should notify people with sound or not.
+                Defaults to `False` (send with a notification sound unless
+                the person has the chat muted). Set it to `True` to alter
+                this behaviour.
+
+            background (`bool`, optional):
+                Whether the message should be send in background.
+
+            supports_streaming (`bool`, optional):
+                Whether the sent video supports streaming or not. Note that
+                Telegram only recognizes as streamable some formats like MP4,
+                and others like AVI or MKV will not work. You should convert
+                these to MP4 before sending if you want them to be streamable.
+                Unsupported formats will result in ``VideoContentTypeError``.
+
+            schedule (`hints.DateLike`, optional):
+                If set, the file won't send immediately, and instead
+                it will be scheduled to be automatically sent at a later
+                time.
+
+            comment_to (`int` | `Message <telethon.tl.custom.message.Message>`, optional):
+                Similar to ``reply_to``, but replies in the linked group of a
+                broadcast channel instead (effectively leaving a "comment to"
+                the specified message).
+
+                This parameter takes precedence over ``reply_to``. If there is
+                no linked chat, `telethon.errors.sgIdInvalidError` is raised.
+
+            ttl (`int`. optional):
+                The Time-To-Live of the file (also known as "self-destruct timer"
+                or "self-destructing media"). If set, files can only be viewed for
+                a short period of time before they disappear from the message
+                history automatically.
+
+                The value must be at least 1 second, and at most 60 seconds,
+                otherwise Telegram will ignore this parameter.
+
+                Not all types of media can be used with this parameter, such
+                as text documents, which will fail with ``TtlMediaInvalidError``.
+
+            nosound_video (`bool`, optional):
+                Only applicable when sending a video file without an audio
+                track. If set to ``True``, the video will be displayed in
+                Telegram as a video. If set to ``False``, Telegram will attempt
+                to display the video as an animated gif. (It may still display
+                as a video due to other factors.) The value is ignored if set
+                on non-video files. This is set to ``True`` for albums, as gifs
+                cannot be sent in albums.
+
+            send_as (`entity`):
+                Unique identifier (int) or username (str) of the chat or channel to send the message as.
+                You can use this to send the message on behalf of a chat or channel where you have appropriate permissions.
+                Use the GetSendAs to return the list of message sender identifiers, which can be used to send messages in the chat,
+                This setting applies to the current message and will remain effective for future messages unless explicitly changed.
+                To set this behavior permanently for all messages, use SaveDefaultSendAs.
+
+            message_effect_id (`int`, optional):
+                Unique identifier of the message effect to be added to the message; for private chats only
+
+        Returns
+            The `Message <telethon.tl.custom.message.Message>` (or messages)
+            containing the sent file, or messages if a list of them was passed.
+
+        Example
+            .. code-block:: python
+
+                # Normal files like photos
+                await client.send_file(chat, '/my/photos/me.jpg', caption="It's me!")
+                # or
+                await client.send_message(chat, "It's me!", file='/my/photos/me.jpg')
+
+                # Voice notes or round videos
+                await client.send_file(chat, '/my/songs/song.mp3', voice_note=True)
+                await client.send_file(chat, '/my/videos/video.mp4', video_note=True)
+
+                # Custom thumbnails
+                await client.send_file(chat, '/my/documents/doc.txt', thumb='photo.jpg')
+
+                # Only documents
+                await client.send_file(chat, '/my/photos/photo.png', force_document=True)
+
+                # Albums
+                await client.send_file(chat, [
+                    '/my/photos/holiday1.jpg',
+                    '/my/photos/holiday2.jpg',
+                    '/my/drawings/portrait.png'
+                ])
+
+                # Printing upload progress
+                def callback(current, total):
+                    print('Uploaded', current, 'out of', total,
+                          'bytes: {:.2%}'.format(current / total))
+
+                await client.send_file(chat, file, progress_callback=callback)
+
+                # Dices, including dart and other future emoji
+                from telethon.tl import types
+                await client.send_file(chat, types.InputMediaDice(''))
+                await client.send_file(chat, types.InputMediaDice('🎯'))
+
+                # Contacts
+                await client.send_file(chat, types.InputMediaContact(
+                    phone_number='+34 123 456 789',
+                    first_name='Example',
+                    last_name='',
+                    vcard=''
+                ))
+        """
+        # TODO Properly implement allow_cache to reuse the sha256 of the file
+        # i.e. `None` was used
+        if not file:
+            raise TypeError('Cannot use {!r} as file'.format(file))
+
+        if not caption:
+            caption = ''
+
+        if not formatting_entities:
+            formatting_entities = []
+
+        entity = await self.get_input_entity(entity)
+        if comment_to is not None:
+            entity, reply_to = await self._get_comment_data(entity, comment_to)
+        else:
+            reply_to = utils.get_message_id(reply_to)
+
+        # First check if the user passed an iterable, in which case
+        # we may want to send grouped.
+        if utils.is_list_like(file):
+            sent_count = 0
+            used_callback = None if not progress_callback else (
+                lambda s, t: progress_callback(sent_count + s, len(file))
+            )
+
+            if utils.is_list_like(caption):
+                captions = caption
+            else:
+                captions = [caption]
+
+            # Check that formatting_entities list is valid
+            if all(utils.is_list_like(obj) for obj in formatting_entities):
+                formatting_entities = formatting_entities
+            elif utils.is_list_like(formatting_entities):
+                formatting_entities = [formatting_entities]
+            else:
+                raise TypeError('The formatting_entities argument must be a list or a sequence of lists')
+
+            # Check that all entities in all lists are of the correct type
+            if not all(isinstance(ent, types.TypeMessageEntity) for sublist in formatting_entities for ent in sublist):
+                raise TypeError('All entities must be instances of <types.TypeMessageEntity>')
+
+            result = []
+            while file:
+                result += await self._send_album(
+                    entity, file[:10], caption=captions[:10], formatting_entities=formatting_entities[:10],
+                    progress_callback=used_callback, reply_to=reply_to,
+                    parse_mode=parse_mode, silent=silent, schedule=schedule,
+                    supports_streaming=supports_streaming, clear_draft=clear_draft,
+                    force_document=force_document, background=background,
+                    send_as=send_as, message_effect_id=message_effect_id
+                )
+                file = file[10:]
+                captions = captions[10:]
+                formatting_entities = formatting_entities[10:]
+                sent_count += 10
+
+            return result
+
+        if formatting_entities:
+            msg_entities = formatting_entities
+        else:
+            caption, msg_entities =\
+                await self._parse_message_text(caption, parse_mode)
+
+        file_handle, media, image = await self._file_to_media(
+            file, force_document=force_document,
+            mime_type=mime_type,
+            file_size=file_size,
+            progress_callback=progress_callback,
+            attributes=attributes, allow_cache=allow_cache, thumb=thumb,
+            voice_note=voice_note, video_note=video_note,
+            supports_streaming=supports_streaming, ttl=ttl,
+            nosound_video=nosound_video,
+        )
+
+        # e.g. invalid cast from :tl:`MessageMediaWebPage`
+        if not media:
+            raise TypeError('Cannot use {!r} as file'.format(file))
+
+        markup = self.build_reply_markup(buttons)
+        reply_to = None if reply_to is None else types.InputReplyToMessage(reply_to)
+        request = functions.messages.SendMediaRequest(
+            entity, media, reply_to=reply_to, message=caption,
+            entities=msg_entities, reply_markup=markup, silent=silent,
+            schedule_date=schedule, clear_draft=clear_draft,
+            background=background,
+            send_as=await self.get_input_entity(send_as) if send_as else None,
+            effect=message_effect_id
+        )
+        return self._get_response_message(request, await self(request), entity)
+
+    async def _send_album(self: 'TelegramClient', entity, files, caption='',
+                          formatting_entities=None,
+                          progress_callback=None, reply_to=None,
+                          parse_mode=(), silent=None, schedule=None,
+                          supports_streaming=None, clear_draft=None,
+                          force_document=False, background=None, ttl=None,
+                          send_as: typing.Optional['hints.EntityLike'] = None,
+                          message_effect_id: typing.Optional[int] = None):
+        """Specialized version of .send_file for albums"""
+        # We don't care if the user wants to avoid cache, we will use it
+        # anyway. Why? The cached version will be exactly the same thing
+        # we need to produce right now to send albums (uploadMedia), and
+        # cache only makes a difference for documents where the user may
+        # want the attributes used on them to change.
+        #
+        # In theory documents can be sent inside the albums, but they appear
+        # as different messages (not inside the album), and the logic to set
+        # the attributes/avoid cache is already written in .send_file().
+        entity = await self.get_input_entity(entity)
+        if not utils.is_list_like(caption):
+            caption = (caption,)
+        if not all(isinstance(obj, list) for obj in formatting_entities):
+            formatting_entities = (formatting_entities,)
+
+        captions = []
+        # If the formatting_entities argument is provided, we don't use parse_mode
+        if formatting_entities:
+            # Pop from the end (so reverse)
+            capt_with_ent = itertools.zip_longest(reversed(caption), reversed(formatting_entities), fillvalue=None)
+            for msg_caption, msg_entities in capt_with_ent:
+                captions.append((msg_caption, msg_entities))
+        else:
+            for c in reversed(caption):  # Pop from the end (so reverse)
+                captions.append(await self._parse_message_text(c or '', parse_mode))
+
+        reply_to = utils.get_message_id(reply_to)
+
+        used_callback = None if not progress_callback else (
+            # use an integer when sent matches total, to easily determine a file has been fully sent
+            lambda s, t: progress_callback(sent_count + 1 if s == t else sent_count + s / t, len(files))
+        )
+
+        # Need to upload the media first, but only if they're not cached yet
+        media = []
+        for sent_count, file in enumerate(files):
+            # Albums want :tl:`InputMedia` which, in theory, includes
+            # :tl:`InputMediaUploadedPhoto`. However, using that will
+            # make it `raise MediaInvalidError`, so we need to upload
+            # it as media and then convert that to :tl:`InputMediaPhoto`.
+            fh, fm, _ = await self._file_to_media(
+                file, supports_streaming=supports_streaming,
+                force_document=force_document, ttl=ttl,
+                progress_callback=used_callback, nosound_video=True)
+            if isinstance(fm, (types.InputMediaUploadedPhoto, types.InputMediaPhotoExternal)):
+                r = await self(functions.messages.UploadMediaRequest(
+                    entity, media=fm
+                ))
+
+                fm = utils.get_input_media(r.photo)
+            elif isinstance(fm, (types.InputMediaUploadedDocument, types.InputMediaDocumentExternal)):
+                r = await self(functions.messages.UploadMediaRequest(
+                    entity, media=fm
+                ))
+
+                fm = utils.get_input_media(
+                    r.document, supports_streaming=supports_streaming)
+
+            if captions:
+                caption, msg_entities = captions.pop()
+            else:
+                caption, msg_entities = '', None
+            media.append(types.InputSingleMedia(
+                fm,
+                message=caption,
+                entities=msg_entities
+                # random_id is autogenerated
+            ))
+
+        # Now we can construct the multi-media request
+        request = functions.messages.SendMultiMediaRequest(
+            entity, reply_to=None if reply_to is None else types.InputReplyToMessage(reply_to), multi_media=media,
+            silent=silent, schedule_date=schedule, clear_draft=clear_draft,
+            background=background,
+            send_as=await self.get_input_entity(send_as) if send_as else None,
+            effect=message_effect_id
+        )
+        result = await self(request)
+
+        random_ids = [m.random_id for m in media]
+        return self._get_response_message(random_ids, result, entity)
+
+    async def upload_file(
+            self: 'TelegramClient',
+            file: 'hints.FileLike',
+            *,
+            part_size_kb: float = None,
+            file_size: int = None,
+            file_name: str = None,
+            use_cache: type = None,
+            key: bytes = None,
+            iv: bytes = None,
+            progress_callback: 'hints.ProgressCallback' = None) -> 'types.TypeInputFile':
+        """
+        Uploads a file to Telegram's servers, without sending it.
+
+        .. note::
+
+            Generally, you want to use `send_file` instead.
+
+        This method returns a handle (an instance of :tl:`InputFile` or
+        :tl:`InputFileBig`, as required) which can be later used before
+        it expires (they are usable during less than a day).
+
+        Uploading a file will simply return a "handle" to the file stored
+        remotely in the Telegram servers, which can be later used on. This
+        will **not** upload the file to your own chat or any chat at all.
+
+        Arguments
+            file (`str` | `bytes` | `file`):
+                The path of the file, byte array, or stream that will be sent.
+                Note that if a byte array or a stream is given, a filename
+                or its type won't be inferred, and it will be sent as an
+                "unnamed application/octet-stream".
+
+            part_size_kb (`int`, optional):
+                Chunk size when uploading files. The larger, the less
+                requests will be made (up to 512KB maximum).
+
+            file_size (`int`, optional):
+                The size of the file to be uploaded, which will be determined
+                automatically if not specified.
+
+                If the file size can't be determined beforehand, the entire
+                file will be read in-memory to find out how large it is.
+
+            file_name (`str`, optional):
+                The file name which will be used on the resulting InputFile.
+                If not specified, the name will be taken from the ``file``
+                and if this is not a `str`, it will be ``"unnamed"``.
+
+            use_cache (`type`, optional):
+                This parameter currently does nothing, but is kept for
+                backward-compatibility (and it may get its use back in
+                the future).
+
+            key ('bytes', optional):
+                In case of an encrypted upload (secret chats) a key is supplied
+
+            iv ('bytes', optional):
+                In case of an encrypted upload (secret chats) an iv is supplied
+
+            progress_callback (`callable`, optional):
+                A callback function accepting two parameters:
+                ``(sent bytes, total)``.
+
+                When sending an album, the callback will receive a number
+                between 0 and the amount of files as the "sent" parameter,
+                and the amount of files as the "total". Note that the first
+                parameter will be a floating point number to indicate progress
+                within a file (e.g. ``2.5`` means it has sent 50% of the third
+                file, because it's between 2 and 3).
+
+        Returns
+            :tl:`InputFileBig` if the file size is larger than 10MB,
+            `InputSizedFile <telethon.tl.custom.inputsizedfile.InputSizedFile>`
+            (subclass of :tl:`InputFile`) otherwise.
+
+        Example
+            .. code-block:: python
+
+                # Photos as photo and document
+                file = await client.upload_file('photo.jpg')
+                await client.send_file(chat, file)                       # sends as photo
+                await client.send_file(chat, file, force_document=True)  # sends as document
+
+                file.name = 'not a photo.jpg'
+                await client.send_file(chat, file, force_document=True)  # document, new name
+
+                # As song or as voice note
+                file = await client.upload_file('song.ogg')
+                await client.send_file(chat, file)                   # sends as song
+                await client.send_file(chat, file, voice_note=True)  # sends as voice note
+        """
+        if isinstance(file, (types.InputFile, types.InputFileBig)):
+            return file  # Already uploaded
+
+        pos = 0
+        async with helpers._FileStream(file, file_size=file_size) as stream:
+            # Opening the stream will determine the correct file size
+            file_size = stream.file_size
+
+            if not part_size_kb:
+                part_size_kb = utils.get_appropriated_part_size(file_size)
+
+            if part_size_kb > 512:
+                raise ValueError('The part size must be less or equal to 512KB')
+
+            part_size = int(part_size_kb * 1024)
+            if part_size % 1024 != 0:
+                raise ValueError(
+                    'The part size must be evenly divisible by 1024')
+
+            # Set a default file name if None was specified
+            file_id = helpers.generate_random_long()
+            if not file_name:
+                file_name = stream.name or str(file_id)
+
+            # If the file name lacks extension, add it if possible.
+            # Else Telegram complains with `PHOTO_EXT_INVALID_ERROR`
+            # even if the uploaded image is indeed a photo.
+            if not os.path.splitext(file_name)[-1]:
+                file_name += utils._get_extension(stream)
+
+            # Determine whether the file is too big (over 10MB) or not
+            # Telegram does make a distinction between smaller or larger files
+            is_big = file_size > 10 * 1024 * 1024
+            hash_md5 = hashlib.md5()
+
+            part_count = (file_size + part_size - 1) // part_size
+            self._log[__name__].info('Uploading file of %d bytes in %d chunks of %d',
+                                     file_size, part_count, part_size)
+
+            pos = 0
+            for part_index in range(part_count):
+                # Read the file by in chunks of size part_size
+                part = await helpers._maybe_await(stream.read(part_size))
+
+                if not isinstance(part, bytes):
+                    raise TypeError(
+                        'file descriptor returned {}, not bytes (you must '
+                        'open the file in bytes mode)'.format(type(part)))
+
+                # `file_size` could be wrong in which case `part` may not be
+                # `part_size` before reaching the end.
+                if len(part) != part_size and part_index < part_count - 1:
+                    raise ValueError(
+                        'read less than {} before reaching the end; either '
+                        '`file_size` or `read` are wrong'.format(part_size))
+
+                pos += len(part)
+
+                # Encryption part if needed
+                if key and iv:
+                    part = AES.encrypt_ige(part, key, iv)
+
+                if not is_big:
+                    # Bit odd that MD5 is only needed for small files and not
+                    # big ones with more chance for corruption, but that's
+                    # what Telegram wants.
+                    hash_md5.update(part)
+
+                # The SavePartRequest is different depending on whether
+                # the file is too large or not (over or less than 10MB)
+                if is_big:
+                    request = functions.upload.SaveBigFilePartRequest(
+                        file_id, part_index, part_count, part)
+                else:
+                    request = functions.upload.SaveFilePartRequest(
+                        file_id, part_index, part)
+
+                result = await self(request)
+                if result:
+                    self._log[__name__].debug('Uploaded %d/%d',
+                                              part_index + 1, part_count)
+                    if progress_callback:
+                        await helpers._maybe_await(progress_callback(pos, file_size))
+                else:
+                    raise RuntimeError(
+                        'Failed to upload file part {}.'.format(part_index))
+
+        if is_big:
+            return types.InputFileBig(file_id, part_count, file_name)
+        else:
+            return custom.InputSizedFile(
+                file_id, part_count, file_name, md5=hash_md5, size=file_size
+            )
+
+    # endregion
+
+    async def _file_to_media(
+            self, file, force_document=False, file_size=None,
+            progress_callback=None, attributes=None, thumb=None,
+            allow_cache=True, voice_note=False, video_note=False,
+            supports_streaming=False, mime_type=None, as_image=None,
+            ttl=None, nosound_video=None):
+        if not file:
+            return None, None, None
+
+        if isinstance(file, pathlib.Path):
+            file = str(file.absolute())
+
+        is_image = utils.is_image(file)
+        if as_image is None:
+            as_image = is_image and not force_document
+
+        # `aiofiles` do not base `io.IOBase` but do have `read`, so we
+        # just check for the read attribute to see if it's file-like.
+        if not isinstance(file, (str, bytes, types.InputFile, types.InputFileBig)) \
+                and not hasattr(file, 'read'):
+            # The user may pass a Message containing media (or the media,
+            # or anything similar) that should be treated as a file. Try
+            # getting the input media for whatever they passed and send it.
+            #
+            # We pass all attributes since these will be used if the user
+            # passed :tl:`InputFile`, and all information may be relevant.
+            try:
+                return (None, utils.get_input_media(
+                    file,
+                    is_photo=as_image,
+                    attributes=attributes,
+                    force_document=force_document,
+                    voice_note=voice_note,
+                    video_note=video_note,
+                    supports_streaming=supports_streaming,
+                    ttl=ttl
+                ), as_image)
+            except TypeError:
+                # Can't turn whatever was given into media
+                return None, None, as_image
+
+        media = None
+        file_handle = None
+
+        if isinstance(file, (types.InputFile, types.InputFileBig)):
+            file_handle = file
+        elif not isinstance(file, str) or os.path.isfile(file):
+            file_handle = await self.upload_file(
+                _resize_photo_if_needed(file, as_image),
+                file_size=file_size,
+                progress_callback=progress_callback
+            )
+        elif re.match('https?://', file):
+            if as_image:
+                media = types.InputMediaPhotoExternal(file, ttl_seconds=ttl)
+            else:
+                media = types.InputMediaDocumentExternal(file, ttl_seconds=ttl)
+        else:
+            bot_file = utils.resolve_bot_file_id(file)
+            if bot_file:
+                media = utils.get_input_media(bot_file, ttl=ttl)
+
+        if media:
+            pass  # Already have media, don't check the rest
+        elif not file_handle:
+            raise ValueError(
+                'Failed to convert {} to media. Not an existing file, '
+                'an HTTP URL or a valid bot-API-like file ID'.format(file)
+            )
+        elif as_image:
+            media = types.InputMediaUploadedPhoto(file_handle, ttl_seconds=ttl)
+        else:
+            attributes, mime_type = utils.get_attributes(
+                file,
+                mime_type=mime_type,
+                attributes=attributes,
+                force_document=force_document and not is_image,
+                voice_note=voice_note,
+                video_note=video_note,
+                supports_streaming=supports_streaming,
+                thumb=thumb
+            )
+
+            if not thumb:
+                thumb = None
+            else:
+                if isinstance(thumb, pathlib.Path):
+                    thumb = str(thumb.absolute())
+                thumb = await self.upload_file(thumb, file_size=file_size)
+
+            # setting `nosound_video` to `True` doesn't affect videos with sound
+            # instead it prevents sending silent videos as GIFs
+            nosound_video = nosound_video if mime_type.split("/")[0] == 'video' else None
+
+            media = types.InputMediaUploadedDocument(
+                file=file_handle,
+                mime_type=mime_type,
+                attributes=attributes,
+                thumb=thumb,
+                force_file=force_document and not is_image,
+                ttl_seconds=ttl,
+                nosound_video=nosound_video
+            )
+        return file_handle, media, as_image
+
+    # endregion

telethon/client/users.py

@@ -0,0 +1,620 @@
+import asyncio
+import datetime
+import itertools
+import time
+import typing
+
+from .. import errors, helpers, utils, hints
+from ..errors import MultiError, RPCError
+from ..helpers import retry_range
+from ..tl import TLRequest, types, functions
+
+_NOT_A_REQUEST = lambda: TypeError('You can only invoke requests, not types!')
+
+if typing.TYPE_CHECKING:
+    from .telegramclient import TelegramClient
+
+
+def _fmt_flood(delay, request, *, early=False, td=datetime.timedelta):
+    return (
+        'Sleeping%s for %ds (%s) on %s flood wait',
+        ' early' if early else '',
+        delay,
+        td(seconds=delay),
+        request.__class__.__name__
+    )
+
+
+class UserMethods:
+    async def __call__(self: 'TelegramClient', request, ordered=False, flood_sleep_threshold=None):
+        return await self._call(self._sender, request, ordered=ordered)
+
+    async def _call(self: 'TelegramClient', sender, request, ordered=False, flood_sleep_threshold=None):
+        if self._loop is not None and self._loop != helpers.get_running_loop():
+            raise RuntimeError('The asyncio event loop must not change after connection (see the FAQ for details)')
+        # if the loop is None it will fail with a connection error later on
+
+        if flood_sleep_threshold is None:
+            flood_sleep_threshold = self.flood_sleep_threshold
+        requests = list(request) if utils.is_list_like(request) else [request]
+        request = list(request) if utils.is_list_like(request) else request
+        for i, r in enumerate(requests):
+            if not isinstance(r, TLRequest):
+                raise _NOT_A_REQUEST()
+            await r.resolve(self, utils)
+
+            # Avoid making the request if it's already in a flood wait
+            if r.CONSTRUCTOR_ID in self._flood_waited_requests:
+                due = self._flood_waited_requests[r.CONSTRUCTOR_ID]
+                diff = round(due - time.time())
+                if diff <= 3:  # Flood waits below 3 seconds are "ignored"
+                    self._flood_waited_requests.pop(r.CONSTRUCTOR_ID, None)
+                elif diff <= flood_sleep_threshold:
+                    self._log[__name__].info(*_fmt_flood(diff, r, early=True))
+                    await asyncio.sleep(diff)
+                    self._flood_waited_requests.pop(r.CONSTRUCTOR_ID, None)
+                else:
+                    raise errors.FloodWaitError(request=r, capture=diff)
+
+            if self._no_updates:
+                if utils.is_list_like(request):
+                    request[i] = functions.InvokeWithoutUpdatesRequest(r)
+                else:
+                    # This should only run once as requests should be a list of 1 item
+                    request = functions.InvokeWithoutUpdatesRequest(r)
+
+        request_index = 0
+        last_error = None
+        self._last_request = time.time()
+
+        for attempt in retry_range(self._request_retries):
+            try:
+                future = sender.send(request, ordered=ordered)
+                if isinstance(future, list):
+                    results = []
+                    exceptions = []
+                    for f in future:
+                        try:
+                            result = await f
+                        except RPCError as e:
+                            exceptions.append(e)
+                            results.append(None)
+                            continue
+                        await utils.maybe_async(self.session.process_entities(result))
+                        exceptions.append(None)
+                        results.append(result)
+                        request_index += 1
+                    if any(x is not None for x in exceptions):
+                        raise MultiError(exceptions, results, requests)
+                    else:
+                        return results
+                else:
+                    result = await future
+                    await utils.maybe_async(self.session.process_entities(result))
+                    return result
+            except (errors.ServerError, errors.RpcCallFailError,
+                    errors.RpcMcgetFailError, errors.InterdcCallErrorError,
+                    errors.TimedOutError,
+                    errors.InterdcCallRichErrorError) as e:
+                last_error = e
+                self._log[__name__].warning(
+                    'Telegram is having internal issues %s: %s',
+                    e.__class__.__name__, e)
+
+                await asyncio.sleep(2)
+            except (errors.FloodWaitError, errors.FloodPremiumWaitError,
+                    errors.SlowModeWaitError, errors.FloodTestPhoneWaitError) as e:
+                last_error = e
+                if utils.is_list_like(request):
+                    request = request[request_index]
+
+                # SLOW_MODE_WAIT is chat-specific, not request-specific
+                if not isinstance(e, errors.SlowModeWaitError):
+                    self._flood_waited_requests\
+                        [request.CONSTRUCTOR_ID] = time.time() + e.seconds
+
+                # In test servers, FLOOD_WAIT_0 has been observed, and sleeping for
+                # such a short amount will cause retries very fast leading to issues.
+                if e.seconds == 0:
+                    e.seconds = 1
+
+                if e.seconds <= self.flood_sleep_threshold:
+                    self._log[__name__].info(*_fmt_flood(e.seconds, request))
+                    await asyncio.sleep(e.seconds)
+                else:
+                    raise
+            except (errors.PhoneMigrateError, errors.NetworkMigrateError,
+                    errors.UserMigrateError) as e:
+                last_error = e
+                self._log[__name__].info('Phone migrated to %d', e.new_dc)
+                should_raise = isinstance(e, (
+                    errors.PhoneMigrateError, errors.NetworkMigrateError
+                ))
+                if should_raise and await self.is_user_authorized():
+                    raise
+                await self._switch_dc(e.new_dc)
+
+        if self._raise_last_call_error and last_error is not None:
+            raise last_error
+        raise ValueError('Request was unsuccessful {} time(s)'
+                         .format(attempt))
+
+    # region Public methods
+
+    async def get_me(self: 'TelegramClient', input_peer: bool = False) \
+            -> 'typing.Union[types.User, types.InputPeerUser]':
+        """
+        Gets "me", the current :tl:`User` who is logged in.
+
+        If the user has not logged in yet, this method returns `None`.
+
+        Arguments
+            input_peer (`bool`, optional):
+                Whether to return the :tl:`InputPeerUser` version or the normal
+                :tl:`User`. This can be useful if you just need to know the ID
+                of yourself.
+
+        Returns
+            Your own :tl:`User`.
+
+        Example
+            .. code-block:: python
+
+                me = await client.get_me()
+                print(me.username)
+        """
+        if input_peer and self._mb_entity_cache.self_id:
+            return self._mb_entity_cache.get(self._mb_entity_cache.self_id)._as_input_peer()
+
+        try:
+            me = (await self(
+                functions.users.GetUsersRequest([types.InputUserSelf()])))[0]
+
+            if not self._mb_entity_cache.self_id:
+                self._mb_entity_cache.set_self_user(me.id, me.bot, me.access_hash)
+
+            return utils.get_input_peer(me, allow_self=False) if input_peer else me
+        except errors.UnauthorizedError:
+            return None
+
+    @property
+    def _self_id(self: 'TelegramClient') -> typing.Optional[int]:
+        """
+        Returns the ID of the logged-in user, if known.
+
+        This property is used in every update, and some like `updateLoginToken`
+        occur prior to login, so it gracefully handles when no ID is known yet.
+        """
+        return self._mb_entity_cache.self_id
+
+    async def is_bot(self: 'TelegramClient') -> bool:
+        """
+        Return `True` if the signed-in user is a bot, `False` otherwise.
+
+        Example
+            .. code-block:: python
+
+                if await client.is_bot():
+                    print('Beep')
+                else:
+                    print('Hello')
+        """
+        if self._mb_entity_cache.self_bot is None:
+            await self.get_me(input_peer=True)
+
+        return self._mb_entity_cache.self_bot
+
+    async def is_user_authorized(self: 'TelegramClient') -> bool:
+        """
+        Returns `True` if the user is authorized (logged in).
+
+        Example
+            .. code-block:: python
+
+                if not await client.is_user_authorized():
+                    await client.send_code_request(phone)
+                    code = input('enter code: ')
+                    await client.sign_in(phone, code)
+        """
+        if self._authorized is None:
+            try:
+                # Any request that requires authorization will work
+                await self(functions.updates.GetStateRequest())
+                self._authorized = True
+            except errors.RPCError:
+                self._authorized = False
+
+        return self._authorized
+
+    async def get_entity(
+            self: 'TelegramClient',
+            entity: 'hints.EntitiesLike') -> typing.Union['hints.Entity', typing.List['hints.Entity']]:
+        """
+        Turns the given entity into a valid Telegram :tl:`User`, :tl:`Chat`
+        or :tl:`Channel`. You can also pass a list or iterable of entities,
+        and they will be efficiently fetched from the network.
+
+        Arguments
+            entity (`str` | `int` | :tl:`Peer` | :tl:`InputPeer`):
+                If a username is given, **the username will be resolved** making
+                an API call every time. Resolving usernames is an expensive
+                operation and will start hitting flood waits around 50 usernames
+                in a short period of time.
+
+                If you want to get the entity for a *cached* username, you should
+                first `get_input_entity(username) <get_input_entity>` which will
+                use the cache), and then use `get_entity` with the result of the
+                previous call.
+
+                Similar limits apply to invite links, and you should use their
+                ID instead.
+
+                Using phone numbers (from people in your contact list), exact
+                names, integer IDs or :tl:`Peer` rely on a `get_input_entity`
+                first, which in turn needs the entity to be in cache, unless
+                a :tl:`InputPeer` was passed.
+
+                Unsupported types will raise ``TypeError``.
+
+                If the entity can't be found, ``ValueError`` will be raised.
+
+        Returns
+            :tl:`User`, :tl:`Chat` or :tl:`Channel` corresponding to the
+            input entity. A list will be returned if more than one was given.
+
+        Example
+            .. code-block:: python
+
+                from telethon import utils
+
+                me = await client.get_entity('me')
+                print(utils.get_display_name(me))
+
+                chat = await client.get_input_entity('username')
+                async for message in client.iter_messages(chat):
+                    ...
+
+                # Note that you could have used the username directly, but it's
+                # good to use get_input_entity if you will reuse it a lot.
+                async for message in client.iter_messages('username'):
+                    ...
+
+                # Note that for this to work the phone number must be in your contacts
+                some_id = await client.get_peer_id('+34123456789')
+        """
+        single = not utils.is_list_like(entity)
+        if single:
+            entity = (entity,)
+
+        # Group input entities by string (resolve username),
+        # input users (get users), input chat (get chats) and
+        # input channels (get channels) to get the most entities
+        # in the less amount of calls possible.
+        inputs = []
+        for x in entity:
+            if isinstance(x, str):
+                inputs.append(x)
+            else:
+                inputs.append(await self.get_input_entity(x))
+
+        lists = {
+            helpers._EntityType.USER: [],
+            helpers._EntityType.CHAT: [],
+            helpers._EntityType.CHANNEL: [],
+        }
+        for x in inputs:
+            try:
+                lists[helpers._entity_type(x)].append(x)
+            except TypeError:
+                pass
+
+        users = lists[helpers._EntityType.USER]
+        chats = lists[helpers._EntityType.CHAT]
+        channels = lists[helpers._EntityType.CHANNEL]
+        if users:
+            # GetUsersRequest has a limit of 200 per call
+            tmp = []
+            while users:
+                curr, users = users[:200], users[200:]
+                tmp.extend(await self(functions.users.GetUsersRequest(curr)))
+            users = tmp
+        if chats:  # TODO Handle chats slice?
+            chats = (await self(
+                functions.messages.GetChatsRequest([x.chat_id for x in chats]))).chats
+        if channels:
+            channels = (await self(
+                functions.channels.GetChannelsRequest(channels))).chats
+
+        # Merge users, chats and channels into a single dictionary
+        id_entity = {
+            # `get_input_entity` might've guessed the type from a non-marked ID,
+            # so the only way to match that with the input is by not using marks here.
+            utils.get_peer_id(x, add_mark=False): x
+            for x in itertools.chain(users, chats, channels)
+        }
+
+        # We could check saved usernames and put them into the users,
+        # chats and channels list from before. While this would reduce
+        # the amount of ResolveUsername calls, it would fail to catch
+        # username changes.
+        result = []
+        for x in inputs:
+            if isinstance(x, str):
+                result.append(await self._get_entity_from_string(x))
+            elif not isinstance(x, types.InputPeerSelf):
+                result.append(id_entity[utils.get_peer_id(x, add_mark=False)])
+            else:
+                result.append(next(
+                    u for u in id_entity.values()
+                    if isinstance(u, types.User) and u.is_self
+                ))
+
+        return result[0] if single else result
+
+    async def get_input_entity(
+            self: 'TelegramClient',
+            peer: 'hints.EntityLike') -> 'types.TypeInputPeer':
+        """
+        Turns the given entity into its input entity version.
+
+        Most requests use this kind of :tl:`InputPeer`, so this is the most
+        suitable call to make for those cases. **Generally you should let the
+        library do its job** and don't worry about getting the input entity
+        first, but if you're going to use an entity often, consider making the
+        call:
+
+        Arguments
+            entity (`str` | `int` | :tl:`Peer` | :tl:`InputPeer`):
+                If a username or invite link is given, **the library will
+                use the cache**. This means that it's possible to be using
+                a username that *changed* or an old invite link (this only
+                happens if an invite link for a small group chat is used
+                after it was upgraded to a mega-group).
+
+                If the username or ID from the invite link is not found in
+                the cache, it will be fetched. The same rules apply to phone
+                numbers (``'+34 123456789'``) from people in your contact list.
+
+                If an exact name is given, it must be in the cache too. This
+                is not reliable as different people can share the same name
+                and which entity is returned is arbitrary, and should be used
+                only for quick tests.
+
+                If a positive integer ID is given, the entity will be searched
+                in cached users, chats or channels, without making any call.
+
+                If a negative integer ID is given, the entity will be searched
+                exactly as either a chat (prefixed with ``-``) or as a channel
+                (prefixed with ``-100``).
+
+                If a :tl:`Peer` is given, it will be searched exactly in the
+                cache as either a user, chat or channel.
+
+                If the given object can be turned into an input entity directly,
+                said operation will be done.
+
+                Unsupported types will raise ``TypeError``.
+
+                If the entity can't be found, ``ValueError`` will be raised.
+
+        Returns
+            :tl:`InputPeerUser`, :tl:`InputPeerChat` or :tl:`InputPeerChannel`
+            or :tl:`InputPeerSelf` if the parameter is ``'me'`` or ``'self'``.
+
+            If you need to get the ID of yourself, you should use
+            `get_me` with ``input_peer=True``) instead.
+
+        Example
+            .. code-block:: python
+
+                # If you're going to use "username" often in your code
+                # (make a lot of calls), consider getting its input entity
+                # once, and then using the "user" everywhere instead.
+                user = await client.get_input_entity('username')
+
+                # The same applies to IDs, chats or channels.
+                chat = await client.get_input_entity(-123456789)
+        """
+        # Short-circuit if the input parameter directly maps to an InputPeer
+        try:
+            return utils.get_input_peer(peer)
+        except TypeError:
+            pass
+
+        # Next in priority is having a peer (or its ID) cached in-memory
+        try:
+            # 0x2d45687 == crc32(b'Peer')
+            if isinstance(peer, int) or peer.SUBCLASS_OF_ID == 0x2d45687:
+                return self._mb_entity_cache.get(utils.get_peer_id(peer, add_mark=False))._as_input_peer()
+        except AttributeError:
+            pass
+
+        # Then come known strings that take precedence
+        if peer in ('me', 'self'):
+            return types.InputPeerSelf()
+
+        # No InputPeer, cached peer, or known string. Fetch from disk cache
+        try:
+            input_entity = await utils.maybe_async(self.session.get_input_entity(peer))
+            return input_entity
+        except ValueError:
+            pass
+
+        # Only network left to try
+        if isinstance(peer, str):
+            return utils.get_input_peer(
+                await self._get_entity_from_string(peer))
+
+        # If we're a bot and the user has messaged us privately users.getUsers
+        # will work with access_hash = 0. Similar for channels.getChannels.
+        # If we're not a bot but the user is in our contacts, it seems to work
+        # regardless. These are the only two special-cased requests.
+        peer = utils.get_peer(peer)
+        if isinstance(peer, types.PeerUser):
+            users = await self(functions.users.GetUsersRequest([
+                types.InputUser(peer.user_id, access_hash=0)]))
+            if users and not isinstance(users[0], types.UserEmpty):
+                # If the user passed a valid ID they expect to work for
+                # channels but would be valid for users, we get UserEmpty.
+                # Avoid returning the invalid empty input peer for that.
+                #
+                # We *could* try to guess if it's a channel first, and if
+                # it's not, work as a chat and try to validate it through
+                # another request, but that becomes too much work.
+                return utils.get_input_peer(users[0])
+        elif isinstance(peer, types.PeerChat):
+            return types.InputPeerChat(peer.chat_id)
+        elif isinstance(peer, types.PeerChannel):
+            try:
+                channels = await self(functions.channels.GetChannelsRequest([
+                    types.InputChannel(peer.channel_id, access_hash=0)]))
+                return utils.get_input_peer(channels.chats[0])
+            except errors.ChannelInvalidError:
+                pass
+
+        raise ValueError(
+            'Could not find the input entity for {} ({}). Please read https://'
+            'docs.telethon.dev/en/stable/concepts/entities.html to'
+            ' find out more details.'
+            .format(peer, type(peer).__name__)
+        )
+
+    async def _get_peer(self: 'TelegramClient', peer: 'hints.EntityLike'):
+        i, cls = utils.resolve_id(await self.get_peer_id(peer))
+        return cls(i)
+
+    async def get_peer_id(
+            self: 'TelegramClient',
+            peer: 'hints.EntityLike',
+            add_mark: bool = True) -> int:
+        """
+        Gets the ID for the given entity.
+
+        This method needs to be ``async`` because `peer` supports usernames,
+        invite-links, phone numbers (from people in your contact list), etc.
+
+        If ``add_mark is False``, then a positive ID will be returned
+        instead. By default, bot-API style IDs (signed) are returned.
+
+        Example
+            .. code-block:: python
+
+                print(await client.get_peer_id('me'))
+        """
+        if isinstance(peer, int):
+            return utils.get_peer_id(peer, add_mark=add_mark)
+
+        try:
+            if peer.SUBCLASS_OF_ID not in (0x2d45687, 0xc91c90b6):
+                # 0x2d45687, 0xc91c90b6 == crc32(b'Peer') and b'InputPeer'
+                peer = await self.get_input_entity(peer)
+        except AttributeError:
+            peer = await self.get_input_entity(peer)
+
+        if isinstance(peer, types.InputPeerSelf):
+            peer = await self.get_me(input_peer=True)
+
+        return utils.get_peer_id(peer, add_mark=add_mark)
+
+    # endregion
+
+    # region Private methods
+
+    async def _get_entity_from_string(self: 'TelegramClient', string):
+        """
+        Gets a full entity from the given string, which may be a phone or
+        a username, and processes all the found entities on the session.
+        The string may also be a user link, or a channel/chat invite link.
+
+        This method has the side effect of adding the found users to the
+        session database, so it can be queried later without API calls,
+        if this option is enabled on the session.
+
+        Returns the found entity, or raises TypeError if not found.
+        """
+        phone = utils.parse_phone(string)
+        if phone:
+            try:
+                for user in (await self(
+                        functions.contacts.GetContactsRequest(0))).users:
+                    if user.phone == phone:
+                        return user
+            except errors.BotMethodInvalidError:
+                raise ValueError('Cannot get entity by phone number as a '
+                                 'bot (try using integer IDs, not strings)')
+        elif string.lower() in ('me', 'self'):
+            return await self.get_me()
+        else:
+            username, is_join_chat = utils.parse_username(string)
+            if is_join_chat:
+                invite = await self(
+                    functions.messages.CheckChatInviteRequest(username))
+
+                if isinstance(invite, types.ChatInvite):
+                    raise ValueError(
+                        'Cannot get entity from a channel (or group) '
+                        'that you are not part of. Join the group and retry'
+                    )
+                elif isinstance(invite, types.ChatInviteAlready):
+                    return invite.chat
+            elif username:
+                try:
+                    result = await self(
+                        functions.contacts.ResolveUsernameRequest(username))
+                except errors.UsernameNotOccupiedError as e:
+                    raise ValueError('No user has "{}" as username'
+                                     .format(username)) from e
+
+                try:
+                    pid = utils.get_peer_id(result.peer, add_mark=False)
+                    if isinstance(result.peer, types.PeerUser):
+                        return next(x for x in result.users if x.id == pid)
+                    else:
+                        return next(x for x in result.chats if x.id == pid)
+                except StopIteration:
+                    pass
+            try:
+                # Nobody with this username, maybe it's an exact name/title
+                input_entity = await utils.maybe_async(self.session.get_input_entity(string))
+                return await self.get_entity(input_entity)
+            except ValueError:
+                pass
+
+        raise ValueError(
+            'Cannot find any entity corresponding to "{}"'.format(string)
+        )
+
+    async def _get_input_dialog(self: 'TelegramClient', dialog):
+        """
+        Returns a :tl:`InputDialogPeer`. This is a bit tricky because
+        it may or not need access to the client to convert what's given
+        into an input entity.
+        """
+        try:
+            if dialog.SUBCLASS_OF_ID == 0xa21c9795:  # crc32(b'InputDialogPeer')
+                dialog.peer = await self.get_input_entity(dialog.peer)
+                return dialog
+            elif dialog.SUBCLASS_OF_ID == 0xc91c90b6:  # crc32(b'InputPeer')
+                return types.InputDialogPeer(dialog)
+        except AttributeError:
+            pass
+
+        return types.InputDialogPeer(await self.get_input_entity(dialog))
+
+    async def _get_input_notify(self: 'TelegramClient', notify):
+        """
+        Returns a :tl:`InputNotifyPeer`. This is a bit tricky because
+        it may or not need access to the client to convert what's given
+        into an input entity.
+        """
+        try:
+            if notify.SUBCLASS_OF_ID == 0x58981615:
+                if isinstance(notify, types.InputNotifyPeer):
+                    notify.peer = await self.get_input_entity(notify.peer)
+                return notify
+        except AttributeError:
+            pass
+
+        return types.InputNotifyPeer(await self.get_input_entity(notify))
+
+    # endregion

telethon/crypto/__init__.py

@@ -1,5 +1,10 @@
+"""
+This module contains several utilities regarding cryptographic purposes,
+such as the AES IGE mode used by Telegram, the authorization key bound with
+their data centers, and so on.
+"""
 from .aes import AES
-from .aes_ctr import AESModeCTR
-from .auth_key import AuthKey
+from .aesctr import AESModeCTR
+from .authkey import AuthKey
 from .factorization import Factorization
-from .cdn_decrypter import CdnDecrypter
+from .cdndecrypter import CdnDecrypter

telethon/crypto/aes.py

@@ -1,79 +1,111 @@
+"""
+AES IGE implementation in Python.
+
+If available, cryptg will be used instead, otherwise
+if available, libssl will be used instead, otherwise
+the Python implementation will be used.
+"""
 import os
 import pyaes
+import logging
 from . import libssl
 
 
-if libssl.AES is not None:
-    # Use libssl if available, since it will be faster
-    AES = libssl.AES
-else:
-    # Fallback to a pure Python implementation
-    class AES:
-        @staticmethod
-        def decrypt_ige(cipher_text, key, iv):
-            """Decrypts the given text in 16-bytes blocks by using the
-               given key and 32-bytes initialization vector
-            """
-            iv1 = iv[:len(iv) // 2]
-            iv2 = iv[len(iv) // 2:]
+__log__ = logging.getLogger(__name__)
 
-            aes = pyaes.AES(key)
 
-            plain_text = []
-            blocks_count = len(cipher_text) // 16
+try:
+    import cryptg
+    __log__.info('cryptg detected, it will be used for encryption')
+except ImportError:
+    cryptg = None
+    if libssl.encrypt_ige and libssl.decrypt_ige:
+        __log__.info('libssl detected, it will be used for encryption')
+    else:
+        __log__.info('cryptg module not installed and libssl not found, '
+                     'falling back to (slower) Python encryption')
 
-            cipher_text_block = [0] * 16
-            for block_index in range(blocks_count):
-                for i in range(16):
-                    cipher_text_block[i] = \
-                        cipher_text[block_index * 16 + i] ^ iv2[i]
 
-                plain_text_block = aes.decrypt(cipher_text_block)
+class AES:
+    """
+    Class that servers as an interface to encrypt and decrypt
+    text through the AES IGE mode.
+    """
+    @staticmethod
+    def decrypt_ige(cipher_text, key, iv):
+        """
+        Decrypts the given text in 16-bytes blocks by using the
+        given key and 32-bytes initialization vector.
+        """
+        if cryptg:
+            return cryptg.decrypt_ige(cipher_text, key, iv)
+        if libssl.decrypt_ige:
+            return libssl.decrypt_ige(cipher_text, key, iv)
 
-                for i in range(16):
-                    plain_text_block[i] ^= iv1[i]
+        iv1 = iv[:len(iv) // 2]
+        iv2 = iv[len(iv) // 2:]
 
-                iv1 = cipher_text[block_index * 16:block_index * 16 + 16]
-                iv2 = plain_text_block
+        aes = pyaes.AES(key)
 
-                plain_text.extend(plain_text_block)
+        plain_text = []
+        blocks_count = len(cipher_text) // 16
 
-            return bytes(plain_text)
+        cipher_text_block = [0] * 16
+        for block_index in range(blocks_count):
+            for i in range(16):
+                cipher_text_block[i] = \
+                    cipher_text[block_index * 16 + i] ^ iv2[i]
 
-        @staticmethod
-        def encrypt_ige(plain_text, key, iv):
-            """Encrypts the given text in 16-bytes blocks by using the
-               given key and 32-bytes initialization vector
-            """
+            plain_text_block = aes.decrypt(cipher_text_block)
 
-            # Add random padding iff it's not evenly divisible by 16 already
-            if len(plain_text) % 16 != 0:
-                padding_count = 16 - len(plain_text) % 16
-                plain_text += os.urandom(padding_count)
+            for i in range(16):
+                plain_text_block[i] ^= iv1[i]
 
-            iv1 = iv[:len(iv) // 2]
-            iv2 = iv[len(iv) // 2:]
+            iv1 = cipher_text[block_index * 16:block_index * 16 + 16]
+            iv2 = plain_text_block
 
-            aes = pyaes.AES(key)
+            plain_text.extend(plain_text_block)
 
-            cipher_text = []
-            blocks_count = len(plain_text) // 16
+        return bytes(plain_text)
 
-            for block_index in range(blocks_count):
-                plain_text_block = list(
-                    plain_text[block_index * 16:block_index * 16 + 16]
-                )
-                for i in range(16):
-                    plain_text_block[i] ^= iv1[i]
+    @staticmethod
+    def encrypt_ige(plain_text, key, iv):
+        """
+        Encrypts the given text in 16-bytes blocks by using the
+        given key and 32-bytes initialization vector.
+        """
+        padding = len(plain_text) % 16
+        if padding:
+            plain_text += os.urandom(16 - padding)
 
-                cipher_text_block = aes.encrypt(plain_text_block)
+        if cryptg:
+            return cryptg.encrypt_ige(plain_text, key, iv)
+        if libssl.encrypt_ige:
+            return libssl.encrypt_ige(plain_text, key, iv)
 
-                for i in range(16):
-                    cipher_text_block[i] ^= iv2[i]
+        iv1 = iv[:len(iv) // 2]
+        iv2 = iv[len(iv) // 2:]
 
-                iv1 = cipher_text_block
-                iv2 = plain_text[block_index * 16:block_index * 16 + 16]
+        aes = pyaes.AES(key)
 
-                cipher_text.extend(cipher_text_block)
+        cipher_text = []
+        blocks_count = len(plain_text) // 16
 
-            return bytes(cipher_text)
+        for block_index in range(blocks_count):
+            plain_text_block = list(
+                plain_text[block_index * 16:block_index * 16 + 16]
+            )
+            for i in range(16):
+                plain_text_block[i] ^= iv1[i]
+
+            cipher_text_block = aes.encrypt(plain_text_block)
+
+            for i in range(16):
+                cipher_text_block[i] ^= iv2[i]
+
+            iv1 = cipher_text_block
+            iv2 = plain_text[block_index * 16:block_index * 16 + 16]
+
+            cipher_text.extend(cipher_text_block)
+
+        return bytes(cipher_text)

telethon/crypto/aes_ctr.py

@@ -1,21 +0,0 @@
-import pyaes
-
-
-class AESModeCTR:
-    """Wrapper around pyaes.AESModeOfOperationCTR mode with custom IV"""
-    # TODO Maybe make a pull request to pyaes to support iv on CTR
-
-    def __init__(self, key, iv):
-        # TODO Use libssl if available
-        assert isinstance(key, bytes)
-        self._aes = pyaes.AESModeOfOperationCTR(key)
-
-        assert isinstance(iv, bytes)
-        assert len(iv) == 16
-        self._aes._counter._counter = list(iv)
-
-    def encrypt(self, data):
-        return self._aes.encrypt(data)
-
-    def decrypt(self, data):
-        return self._aes.decrypt(data)

telethon/crypto/aesctr.py

@@ -0,0 +1,42 @@
+"""
+This module holds the AESModeCTR wrapper class.
+"""
+import pyaes
+
+
+class AESModeCTR:
+    """Wrapper around pyaes.AESModeOfOperationCTR mode with custom IV"""
+    # TODO Maybe make a pull request to pyaes to support iv on CTR
+
+    def __init__(self, key, iv):
+        """
+        Initializes the AES CTR mode with the given key/iv pair.
+
+        :param key: the key to be used as bytes.
+        :param iv: the bytes initialization vector. Must have a length of 16.
+        """
+        # TODO Use libssl if available
+        assert isinstance(key, bytes)
+        self._aes = pyaes.AESModeOfOperationCTR(key)
+
+        assert isinstance(iv, bytes)
+        assert len(iv) == 16
+        self._aes._counter._counter = list(iv)
+
+    def encrypt(self, data):
+        """
+        Encrypts the given plain text through AES CTR.
+
+        :param data: the plain text to be encrypted.
+        :return: the encrypted cipher text.
+        """
+        return self._aes.encrypt(data)
+
+    def decrypt(self, data):
+        """
+        Decrypts the given cipher text through AES CTR
+
+        :param data: the cipher text to be decrypted.
+        :return: the decrypted plain text.
+        """
+        return self._aes.decrypt(data)

telethon/crypto/auth_key.py

@@ -1,23 +0,0 @@
-import struct
-from hashlib import sha1
-
-from .. import helpers as utils
-from ..extensions import BinaryReader
-
-
-class AuthKey:
-    def __init__(self, data):
-        self.key = data
-
-        with BinaryReader(sha1(self.key).digest()) as reader:
-            self.aux_hash = reader.read_long(signed=False)
-            reader.read(4)
-            self.key_id = reader.read_long(signed=False)
-
-    def calc_new_nonce_hash(self, new_nonce, number):
-        """Calculates the new nonce hash based on
-           the current class fields' values
-        """
-        new_nonce = new_nonce.to_bytes(32, 'little', signed=True)
-        data = new_nonce + struct.pack('<BQ', number, self.aux_hash)
-        return utils.calc_msg_key(data)

telethon/crypto/authkey.py

@@ -0,0 +1,63 @@
+"""
+This module holds the AuthKey class.
+"""
+import struct
+from hashlib import sha1
+
+from ..extensions import BinaryReader
+
+
+class AuthKey:
+    """
+    Represents an authorization key, used to encrypt and decrypt
+    messages sent to Telegram's data centers.
+    """
+    def __init__(self, data):
+        """
+        Initializes a new authorization key.
+
+        :param data: the data in bytes that represent this auth key.
+        """
+        self.key = data
+
+    @property
+    def key(self):
+        return self._key
+
+    @key.setter
+    def key(self, value):
+        if not value:
+            self._key = self.aux_hash = self.key_id = None
+            return
+
+        if isinstance(value, type(self)):
+            self._key, self.aux_hash, self.key_id = \
+                value._key, value.aux_hash, value.key_id
+            return
+
+        self._key = value
+        with BinaryReader(sha1(self._key).digest()) as reader:
+            self.aux_hash = reader.read_long(signed=False)
+            reader.read(4)
+            self.key_id = reader.read_long(signed=False)
+
+    # TODO This doesn't really fit here, it's only used in authentication
+    def calc_new_nonce_hash(self, new_nonce, number):
+        """
+        Calculates the new nonce hash based on the current attributes.
+
+        :param new_nonce: the new nonce to be hashed.
+        :param number: number to prepend before the hash.
+        :return: the hash for the given new nonce.
+        """
+        new_nonce = new_nonce.to_bytes(32, 'little', signed=True)
+        data = new_nonce + struct.pack('<BQ', number, self.aux_hash)
+
+        # Calculates the message key from the given data
+        return int.from_bytes(sha1(data).digest()[4:20], 'little', signed=True)
+
+    def __bool__(self):
+        return bool(self._key)
+
+    def __eq__(self, other):
+        return isinstance(other, type(self)) and other.key == self._key

telethon/crypto/cdndecrypter.py

@@ -1,6 +1,8 @@
+"""
+This module holds the CdnDecrypter utility class.
+"""
 from hashlib import sha256
 
-from ..tl import Session
 from ..tl.functions.upload import GetCdnFileRequest, ReuploadCdnFileRequest
 from ..tl.types.upload import CdnFileReuploadNeeded, CdnFile
 from ..crypto import AESModeCTR
@@ -8,22 +10,34 @@ from ..errors import CdnFileTamperedError
 
 
 class CdnDecrypter:
-    """Used when downloading a file results in a 'FileCdnRedirect' to
-       both prepare the redirect, decrypt the file as it downloads, and
-       ensure the file hasn't been tampered. https://core.telegram.org/cdn
+    """
+    Used when downloading a file results in a 'FileCdnRedirect' to
+    both prepare the redirect, decrypt the file as it downloads, and
+    ensure the file hasn't been tampered. https://core.telegram.org/cdn
     """
     def __init__(self, cdn_client, file_token, cdn_aes, cdn_file_hashes):
+        """
+        Initializes the CDN decrypter.
+
+        :param cdn_client: a client connected to a CDN.
+        :param file_token: the token of the file to be used.
+        :param cdn_aes: the AES CTR used to decrypt the file.
+        :param cdn_file_hashes: the hashes the decrypted file must match.
+        """
         self.client = cdn_client
         self.file_token = file_token
         self.cdn_aes = cdn_aes
         self.cdn_file_hashes = cdn_file_hashes
 
     @staticmethod
-    def prepare_decrypter(client, cdn_client, cdn_redirect):
-        """Prepares a CDN decrypter, returning (decrypter, file data).
-           'client' should be an existing client not connected to a CDN.
-           'cdn_client' should be an already-connected TelegramBareClient
-           with the auth key already created.
+    async def prepare_decrypter(client, cdn_client, cdn_redirect):
+        """
+        Prepares a new CDN decrypter.
+
+        :param client: a TelegramClient connected to the main servers.
+        :param cdn_client: a new client connected to the CDN.
+        :param cdn_redirect: the redirect file object that caused this call.
+        :return: (CdnDecrypter, first chunk file data)
         """
         cdn_aes = AESModeCTR(
             key=cdn_redirect.encryption_key,
@@ -38,14 +52,14 @@ class CdnDecrypter:
             cdn_aes, cdn_redirect.cdn_file_hashes
         )
 
-        cdn_file = cdn_client(GetCdnFileRequest(
+        cdn_file = await cdn_client(GetCdnFileRequest(
             file_token=cdn_redirect.file_token,
             offset=cdn_redirect.cdn_file_hashes[0].offset,
             limit=cdn_redirect.cdn_file_hashes[0].limit
         ))
         if isinstance(cdn_file, CdnFileReuploadNeeded):
             # We need to use the original client here
-            client(ReuploadCdnFileRequest(
+            await client(ReuploadCdnFileRequest(
                 file_token=cdn_redirect.file_token,
                 request_token=cdn_file.request_token
             ))
@@ -60,8 +74,11 @@ class CdnDecrypter:
         return decrypter, cdn_file
 
     def get_file(self):
-        """Calls GetCdnFileRequest and decrypts its bytes.
-           Also ensures that the file hasn't been tampered.
+        """
+        Calls GetCdnFileRequest and decrypts its bytes.
+        Also ensures that the file hasn't been tampered.
+
+        :return: the CdnFile result.
         """
         if self.cdn_file_hashes:
             cdn_hash = self.cdn_file_hashes.pop(0)
@@ -77,6 +94,12 @@ class CdnDecrypter:
 
     @staticmethod
     def check(data, cdn_hash):
-        """Checks the integrity of the given data"""
+        """
+        Checks the integrity of the given data.
+        Raises CdnFileTamperedError if the integrity check fails.
+
+        :param data: the data to be hashed.
+        :param cdn_hash: the expected hash.
+        """
         if sha256(data).digest() != cdn_hash.hash:
             raise CdnFileTamperedError()

telethon/crypto/factorization.py

@@ -1,71 +1,67 @@
+"""
+This module holds a fast Factorization class.
+"""
 from random import randint
-try:
-    import sympy.ntheory
-except ImportError:
-    sympy = None
 
 
 class Factorization:
-    @staticmethod
-    def find_small_multiplier_lopatin(what):
-        """Finds the small multiplier by using Lopatin's method"""
-        g = 0
-        for i in range(3):
-            q = (randint(0, 127) & 15) + 17
-            x = randint(0, 1000000000) + 1
-            y = x
-            lim = 1 << (i + 18)
-            for j in range(1, lim):
-                a, b, c = x, x, q
-                while b != 0:
-                    if (b & 1) != 0:
-                        c += a
-                        if c >= what:
-                            c -= what
-                    a += a
-                    if a >= what:
-                        a -= what
-                    b >>= 1
+    """
+    Simple module to factorize large numbers really quickly.
+    """
+    @classmethod
+    def factorize(cls, pq):
+        """
+        Factorizes the given large integer.
 
-                x = c
-                z = y - x if x < y else x - y
-                g = Factorization.gcd(z, what)
-                if g != 1:
+        Implementation from https://comeoncodeon.wordpress.com/2010/09/18/pollard-rho-brent-integer-factorization/.
+
+        :param pq: the prime pair pq.
+        :return: a tuple containing the two factors p and q.
+        """
+        if pq % 2 == 0:
+            return 2, pq // 2
+
+        y, c, m = randint(1, pq - 1), randint(1, pq - 1), randint(1, pq - 1)
+        g = r = q = 1
+        x = ys = 0
+
+        while g == 1:
+            x = y
+            for i in range(r):
+                y = (pow(y, 2, pq) + c) % pq
+
+            k = 0
+            while k < r and g == 1:
+                ys = y
+                for i in range(min(m, r - k)):
+                    y = (pow(y, 2, pq) + c) % pq
+                    q = q * (abs(x - y)) % pq
+
+                g = cls.gcd(q, pq)
+                k += m
+
+            r *= 2
+
+        if g == pq:
+            while True:
+                ys = (pow(ys, 2, pq) + c) % pq
+                g = cls.gcd(abs(x - ys), pq)
+                if g > 1:
                     break
 
-                if (j & (j - 1)) == 0:
-                    y = x
-
-            if g > 1:
-                break
-
-        p = what // g
-        return min(p, g)
+        p, q = g, pq // g
+        return (p, q) if p < q else (q, p)
 
     @staticmethod
     def gcd(a, b):
-        """Calculates the greatest common divisor"""
-        while a != 0 and b != 0:
-            while b & 1 == 0:
-                b >>= 1
-
-            while a & 1 == 0:
-                a >>= 1
-
-            if a > b:
-                a -= b
-            else:
-                b -= a
-
-        return a if b == 0 else b
-
-    @staticmethod
-    def factorize(pq):
-        """Factorizes the given number and returns both
-           the divisor and the number divided by the divisor
         """
-        if sympy:
-            return tuple(sympy.ntheory.factorint(pq).keys())
-        else:
-            divisor = Factorization.find_small_multiplier_lopatin(pq)
-            return divisor, pq // divisor
+        Calculates the Greatest Common Divisor.
+
+        :param a: the first number.
+        :param b: the second number.
+        :return: GCD(a, b)
+        """
+        while b:
+            a, b = b, a % b
+
+        return a

telethon/crypto/libssl.py

@@ -1,91 +1,140 @@
-import os
+"""
+Helper module around the system's libssl library if available for IGE mode.
+"""
 import ctypes
-from ctypes.util import find_library
+import ctypes.util
+import platform
+import sys
+try:
+    import ctypes.macholib.dyld
+except ImportError:
+    pass
+import logging
+import os
 
-lib = find_library('ssl')
-if not lib:
-    AES = None
+__log__ = logging.getLogger(__name__)
+
+
+def _find_ssl_lib():
+    lib = ctypes.util.find_library('ssl')
+    # macOS 10.15 segfaults on  unversioned crypto libraries.
+    # We therefore pin the current stable version here
+    # Credit for fix goes to Sarah Harvey (@worldwise001)
+    # https://www.shh.sh/2020/01/04/python-abort-trap-6.html
+    if sys.platform == 'darwin':
+        release, _version_info, _machine = platform.mac_ver()
+        ver, major, *_ = release.split('.')
+        # macOS 10.14 "mojave" is the last known major release
+        # to support unversioned libssl.dylib. Anything above
+        # needs specific versions
+        if int(ver) > 10 or int(ver) == 10 and int(major) > 14:
+            lib = (
+                ctypes.util.find_library('libssl.46') or
+                ctypes.util.find_library('libssl.44') or
+                ctypes.util.find_library('libssl.42')
+            )
+    if not lib:
+        raise OSError('no library called "ssl" found')
+
+    # First, let ctypes try to handle it itself.
+    try:
+        libssl = ctypes.cdll.LoadLibrary(lib)
+    except OSError:
+        pass
+    else:
+        return libssl
+
+    # This is a best-effort attempt at finding the full real path of lib.
+    #
+    # Unfortunately ctypes doesn't tell us *where* it finds the library,
+    # so we have to do that ourselves.
+    try:
+        # This is not documented, so it could fail. Be on the safe side.
+        paths = ctypes.macholib.dyld.DEFAULT_LIBRARY_FALLBACK
+    except AttributeError:
+        paths = [
+            os.path.expanduser("~/lib"),
+            "/usr/local/lib",
+            "/lib",
+            "/usr/lib",
+        ]
+
+    for path in paths:
+        if os.path.isdir(path):
+            for root, _, files in os.walk(path):
+                if lib in files:
+                    # Manually follow symbolic links on *nix systems.
+                    # Fix for https://github.com/LonamiWebs/Telethon/issues/1167
+                    lib = os.path.realpath(os.path.join(root, lib))
+                    return ctypes.cdll.LoadLibrary(lib)
+    else:
+        raise OSError('no absolute path for "%s" and cannot load by name' % lib)
+
+
+try:
+    _libssl = _find_ssl_lib()
+except OSError as e:
+    # See https://github.com/LonamiWebs/Telethon/issues/1167
+    # Sometimes `find_library` returns improper filenames.
+    __log__.info('Failed to load SSL library: %s (%s)', type(e), e)
+    _libssl = None
+
+if not _libssl:
+    decrypt_ige = None
+    encrypt_ige = None
 else:
-    """ <aes.h>
-    # define AES_ENCRYPT     1
-    # define AES_DECRYPT     0
-    # define AES_MAXNR 14
-    struct aes_key_st {
-    # ifdef AES_LONG
-        unsigned long rd_key[4 * (AES_MAXNR + 1)];
-    # else
-        unsigned int rd_key[4 * (AES_MAXNR + 1)];
-    # endif
-        int rounds;
-    };
-    typedef struct aes_key_st AES_KEY;
-
-    int AES_set_encrypt_key(const unsigned char *userKey, const int bits,
-                            AES_KEY *key);
-    int AES_set_decrypt_key(const unsigned char *userKey, const int bits,
-                            AES_KEY *key);
-    void AES_ige_encrypt(const unsigned char *in, unsigned char *out,
-                         size_t length, const AES_KEY *key,
-                         unsigned char *ivec, const int enc);
-    """
-    _libssl = ctypes.cdll.LoadLibrary(lib)
-
-    AES_MAXNR = 14
+    # https://github.com/openssl/openssl/blob/master/include/openssl/aes.h
     AES_ENCRYPT = ctypes.c_int(1)
     AES_DECRYPT = ctypes.c_int(0)
+    AES_MAXNR = 14
 
     class AES_KEY(ctypes.Structure):
+        """Helper class representing an AES key"""
         _fields_ = [
-            ('rd_key', ctypes.c_uint32 * (4*(AES_MAXNR + 1))),
+            ('rd_key', ctypes.c_uint32 * (4 * (AES_MAXNR + 1))),
             ('rounds', ctypes.c_uint),
         ]
 
-    class AES:
-        @staticmethod
-        def decrypt_ige(cipher_text, key, iv):
-            aeskey = AES_KEY()
-            ckey = (ctypes.c_ubyte * len(key))(*key)
-            cklen = ctypes.c_int(len(key)*8)
-            cin = (ctypes.c_ubyte * len(cipher_text))(*cipher_text)
-            ctlen = ctypes.c_size_t(len(cipher_text))
-            cout = (ctypes.c_ubyte * len(cipher_text))()
-            civ = (ctypes.c_ubyte * len(iv))(*iv)
+    def decrypt_ige(cipher_text, key, iv):
+        aes_key = AES_KEY()
+        key_len = ctypes.c_int(8 * len(key))
+        key = (ctypes.c_ubyte * len(key))(*key)
+        iv = (ctypes.c_ubyte * len(iv))(*iv)
 
-            _libssl.AES_set_decrypt_key(ckey, cklen, ctypes.byref(aeskey))
-            _libssl.AES_ige_encrypt(
-                ctypes.byref(cin),
-                ctypes.byref(cout),
-                ctlen,
-                ctypes.byref(aeskey),
-                ctypes.byref(civ),
-                AES_DECRYPT
-            )
+        in_len = ctypes.c_size_t(len(cipher_text))
+        in_ptr = (ctypes.c_ubyte * len(cipher_text))(*cipher_text)
+        out_ptr = (ctypes.c_ubyte * len(cipher_text))()
 
-            return bytes(cout)
+        _libssl.AES_set_decrypt_key(key, key_len, ctypes.byref(aes_key))
+        _libssl.AES_ige_encrypt(
+            ctypes.byref(in_ptr),
+            ctypes.byref(out_ptr),
+            in_len,
+            ctypes.byref(aes_key),
+            ctypes.byref(iv),
+            AES_DECRYPT
+        )
 
-        @staticmethod
-        def encrypt_ige(plain_text, key, iv):
-            # Add random padding iff it's not evenly divisible by 16 already
-            if len(plain_text) % 16 != 0:
-                padding_count = 16 - len(plain_text) % 16
-                plain_text += os.urandom(padding_count)
+        return bytes(out_ptr)
 
-            aeskey = AES_KEY()
-            ckey = (ctypes.c_ubyte * len(key))(*key)
-            cklen = ctypes.c_int(len(key)*8)
-            cin = (ctypes.c_ubyte * len(plain_text))(*plain_text)
-            ctlen = ctypes.c_size_t(len(plain_text))
-            cout = (ctypes.c_ubyte * len(plain_text))()
-            civ = (ctypes.c_ubyte * len(iv))(*iv)
+    def encrypt_ige(plain_text, key, iv):
+        aes_key = AES_KEY()
+        key_len = ctypes.c_int(8 * len(key))
+        key = (ctypes.c_ubyte * len(key))(*key)
+        iv = (ctypes.c_ubyte * len(iv))(*iv)
 
-            _libssl.AES_set_encrypt_key(ckey, cklen, ctypes.byref(aeskey))
-            _libssl.AES_ige_encrypt(
-                ctypes.byref(cin),
-                ctypes.byref(cout),
-                ctlen,
-                ctypes.byref(aeskey),
-                ctypes.byref(civ),
-                AES_ENCRYPT
-            )
+        in_len = ctypes.c_size_t(len(plain_text))
+        in_ptr = (ctypes.c_ubyte * len(plain_text))(*plain_text)
+        out_ptr = (ctypes.c_ubyte * len(plain_text))()
 
-            return bytes(cout)
+        _libssl.AES_set_encrypt_key(key, key_len, ctypes.byref(aes_key))
+        _libssl.AES_ige_encrypt(
+            ctypes.byref(in_ptr),
+            ctypes.byref(out_ptr),
+            in_len,
+            ctypes.byref(aes_key),
+            ctypes.byref(iv),
+            AES_ENCRYPT
+        )
+
+        return bytes(out_ptr)

telethon/crypto/rsa.py

@@ -1,3 +1,6 @@
+"""
+This module holds several utilities regarding RSA and server fingerprints.
+"""
 import os
 import struct
 from hashlib import sha1
@@ -11,7 +14,7 @@ except ImportError:
 from ..tl import TLObject
 
 
-# {fingerprint: Crypto.PublicKey.RSA._RSAobj} dictionary
+# {fingerprint: (Crypto.PublicKey.RSA._RSAobj, old)} dictionary
 _server_keys = {}
 
 
@@ -25,15 +28,18 @@ def get_byte_array(integer):
     # Reference: https://core.telegram.org/mtproto/auth_key
     return int.to_bytes(
         integer,
-        length=(integer.bit_length() + 8 - 1) // 8,  # 8 bits per byte,
+        (integer.bit_length() + 8 - 1) // 8,  # 8 bits per byte,
         byteorder='big',
         signed=False
     )
 
 
 def _compute_fingerprint(key):
-    """For a given Crypto.RSA key, computes its 8-bytes-long fingerprint
-       in the same way that Telegram does.
+    """
+    Given a RSA key, computes its fingerprint like Telegram does.
+
+    :param key: the Crypto.RSA key.
+    :return: its 8-bytes-long fingerprint.
     """
     n = TLObject.serialize_bytes(get_byte_array(key.n))
     e = TLObject.serialize_bytes(get_byte_array(key.e))
@@ -41,20 +47,27 @@ def _compute_fingerprint(key):
     return struct.unpack('<q', sha1(n + e).digest()[-8:])[0]
 
 
-def add_key(pub):
+def add_key(pub, *, old):
     """Adds a new public key to be used when encrypting new data is needed"""
     global _server_keys
     key = rsa.PublicKey.load_pkcs1(pub)
-    _server_keys[_compute_fingerprint(key)] = key
+    _server_keys[_compute_fingerprint(key)] = (key, old)
 
 
-def encrypt(fingerprint, data):
-    """Given the fingerprint of a previously added RSA key, encrypt its data
-       in the way Telegram requires us to do so (sha1(data) + data + padding)
+def encrypt(fingerprint, data, *, use_old=False):
+    """
+    Encrypts the given data known the fingerprint to be used
+    in the way Telegram requires us to do so (sha1(data) + data + padding)
+
+    :param fingerprint: the fingerprint of the RSA key.
+    :param data: the data to be encrypted.
+    :param use_old: whether old keys should be used.
+    :return:
+        the cipher text, or None if no key matching this fingerprint is found.
     """
     global _server_keys
-    key = _server_keys.get(fingerprint, None)
-    if not key:
+    key, old = _server_keys.get(fingerprint, [None, None])
+    if (not key) or (old and not use_old):
         return None
 
     # len(sha1.digest) is always 20, so we're left with 255 - 20 - x padding
@@ -70,6 +83,48 @@ def encrypt(fingerprint, data):
 
 
 # Add default keys
+# https://github.com/DrKLO/Telegram/blob/a724d96e9c008b609fe188d122aa2922e40de5fc/TMessagesProj/jni/tgnet/Handshake.cpp#L356-L436
+for pub in (
+        '''-----BEGIN RSA PUBLIC KEY-----
+MIIBCgKCAQEAruw2yP/BCcsJliRoW5eBVBVle9dtjJw+OYED160Wybum9SXtBBLX
+riwt4rROd9csv0t0OHCaTmRqBcQ0J8fxhN6/cpR1GWgOZRUAiQxoMnlt0R93LCX/
+j1dnVa/gVbCjdSxpbrfY2g2L4frzjJvdl84Kd9ORYjDEAyFnEA7dD556OptgLQQ2
+e2iVNq8NZLYTzLp5YpOdO1doK+ttrltggTCy5SrKeLoCPPbOgGsdxJxyz5KKcZnS
+Lj16yE5HvJQn0CNpRdENvRUXe6tBP78O39oJ8BTHp9oIjd6XWXAsp2CvK45Ol8wF
+XGF710w9lwCGNbmNxNYhtIkdqfsEcwR5JwIDAQAB
+-----END RSA PUBLIC KEY-----''',
+
+        '''-----BEGIN RSA PUBLIC KEY-----
+MIIBCgKCAQEAvfLHfYH2r9R70w8prHblWt/nDkh+XkgpflqQVcnAfSuTtO05lNPs
+pQmL8Y2XjVT4t8cT6xAkdgfmmvnvRPOOKPi0OfJXoRVylFzAQG/j83u5K3kRLbae
+7fLccVhKZhY46lvsueI1hQdLgNV9n1cQ3TDS2pQOCtovG4eDl9wacrXOJTG2990V
+jgnIKNA0UMoP+KF03qzryqIt3oTvZq03DyWdGK+AZjgBLaDKSnC6qD2cFY81UryR
+WOab8zKkWAnhw2kFpcqhI0jdV5QaSCExvnsjVaX0Y1N0870931/5Jb9ICe4nweZ9
+kSDF/gip3kWLG0o8XQpChDfyvsqB9OLV/wIDAQAB
+-----END RSA PUBLIC KEY-----''',
+
+        '''-----BEGIN RSA PUBLIC KEY-----
+MIIBCgKCAQEAs/ditzm+mPND6xkhzwFIz6J/968CtkcSE/7Z2qAJiXbmZ3UDJPGr
+zqTDHkO30R8VeRM/Kz2f4nR05GIFiITl4bEjvpy7xqRDspJcCFIOcyXm8abVDhF+
+th6knSU0yLtNKuQVP6voMrnt9MV1X92LGZQLgdHZbPQz0Z5qIpaKhdyA8DEvWWvS
+Uwwc+yi1/gGaybwlzZwqXYoPOhwMebzKUk0xW14htcJrRrq+PXXQbRzTMynseCoP
+Ioke0dtCodbA3qQxQovE16q9zz4Otv2k4j63cz53J+mhkVWAeWxVGI0lltJmWtEY
+K6er8VqqWot3nqmWMXogrgRLggv/NbbooQIDAQAB
+-----END RSA PUBLIC KEY-----''',
+
+        '''-----BEGIN RSA PUBLIC KEY-----
+MIIBCgKCAQEAvmpxVY7ld/8DAjz6F6q05shjg8/4p6047bn6/m8yPy1RBsvIyvuD
+uGnP/RzPEhzXQ9UJ5Ynmh2XJZgHoE9xbnfxL5BXHplJhMtADXKM9bWB11PU1Eioc
+3+AXBB8QiNFBn2XI5UkO5hPhbb9mJpjA9Uhw8EdfqJP8QetVsI/xrCEbwEXe0xvi
+fRLJbY08/Gp66KpQvy7g8w7VB8wlgePexW3pT13Ap6vuC+mQuJPyiHvSxjEKHgqe
+Pji9NP3tJUFQjcECqcm0yV7/2d0t/pbCm+ZH1sadZspQCEPPrtbkQBlvHb4OLiIW
+PGHKSMeRFvp3IWcmdJqXahxLCUS1Eh6MAQIDAQAB
+-----END RSA PUBLIC KEY-----''',
+
+):
+    add_key(pub, old=False)
+
+
 for pub in (
         '''-----BEGIN RSA PUBLIC KEY-----
 MIIBCgKCAQEAwVACPi9w23mF3tBkdZz+zwrzKOaaQdr01vAbU4E1pvkfj4sqDsm6
@@ -105,6 +160,6 @@ qAqBdmI1iBGdQv/OQCBcbXIWCGDY2AsiqLhlGQfPOI7/vvKc188rTriocgUtoTUc
 /n/sIUzkgwTqRyvWYynWARWzQg0I9olLBBC2q5RQJJlnYXZwyTL3y9tdb7zOHkks
 WV9IMQmZmyZh/N7sMbGWQpt4NMchGpPGeJ2e5gHBjDnlIf2p1yZOYeUYrdbwcS0t
 UiggS4UeE8TzIuXFQxw7fzEIlmhIaq3FnwIDAQAB
------END RSA PUBLIC KEY-----'''
+-----END RSA PUBLIC KEY-----''',
 ):
-    add_key(pub)
+    add_key(pub, old=True)