Merge branch 'asyncio' of https://github.com/LonamiWebs/Telethon into asyncio-upstream

* 'asyncio' of https://github.com/LonamiWebs/Telethon:
  Duplicate commit from master to handle empty draft msg

.coveragerc

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

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,10 @@
+<!--
+0. The library is Python >= 3.4, not Python 2.x.
+1. If you have a QUESTION, ask it on @TelethonChat (Telegram) or StackOverflow, not here. It will be closed immediatly with no explanation if you post it here.
+2. If you have an ISSUE or you are experiencing strange behaviour, make sure you're using the latest version (pip install -U telethon), and post as much information as possible here. Enhancement suggestions are welcome too.
+
+If you paste code, please put it between three backticks (`):
+```python
+code here
+```
+-->

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -1,96 +0,0 @@
-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

@@ -1,8 +0,0 @@
-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

@@ -1,22 +0,0 @@
-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

@@ -1,22 +0,0 @@
-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

@@ -1,5 +0,0 @@
-<!--
-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

@@ -1,28 +0,0 @@
-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,23 +1,108 @@
+# Docs
+_build/
+docs/
+
 # Generated code
-/telethon/tl/functions/
-/telethon/tl/types/
-/telethon/tl/alltlobjects.py
-/telethon/errors/rpcerrorlist.py
+telethon/tl/functions/
+telethon/tl/types/
+telethon/tl/all_tlobjects.py
+telethon/errors/rpc_error_list.py
 
 # User session
 *.session
-/usermedia/
+usermedia/
+api/settings
 
-# Builds and testing
+# Quick tests should live in this file
+example.py
+
+# Byte-compiled / optimized / DLL files
 __pycache__/
-/dist/
-/build/
-/*.egg-info/
-/readthedocs/_build/
-/.tox/
+*.py[cod]
+*$py.class
 
-# API reference docs
-/docs/
+# C extensions
+*.so
 
-# File used to manually test new changes, contains sensitive data
-/example.py
+# 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

.readthedocs.yaml

@@ -1,18 +0,0 @@
-# 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-Present LonamiWebs
+Copyright (c) 2016 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

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

README.rst

@@ -2,18 +2,12 @@ Telethon
 ========
 .. epigraph::
 
-  ⭐️ Thanks **everyone** who has starred the project, it means a lot!
+    This is the ``asyncio`` version of the library. If you don't know how
+    to work with it, `see here https://pypi.python.org/pypi/Telethon`__.
 
-|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).
+**Telethon** is Telegram client implementation in **Python 3** which uses
+the latest available API of Telegram.
 
-.. 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?
 -------------
@@ -27,61 +21,60 @@ heavy job for you, so you can focus on developing an application.
 Installing
 ----------
 
-.. code-block:: sh
+.. code:: sh
 
-  pip3 install telethon
+  pip3 install telethon-aio
+
+.. warning::
+
+  Be careful **not** to install ``telethon-asyncio`` or other
+  variants, someone else name-squatted those and are unofficial!
 
 
 Creating a client
 -----------------
 
-.. code-block:: python
+.. code:: python
 
-    from telethon import TelegramClient, events, sync
+  import asyncio
+  from telethon import TelegramClient
 
-    # 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'
+  # 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.start()
+  client = TelegramClient('session_name', api_id, api_hash)
+  async def main():
+      await client.start()
 
+  asyncio.get_event_loop().run_until_complete(main())
 
 Doing stuff
 -----------
 
-.. code-block:: python
+Note that this assumes you're inside an "async def" method. Check out the
+`Python documentation <https://docs.python.org/3/library/asyncio-dev.html>`_
+if you're new with ``asyncio``.
 
-    print(client.get_me().stringify())
+.. code:: python
 
-    client.send_message('username', 'Hello! Talking to you from Telethon')
-    client.send_file('username', '/home/myself/Pictures/holidays.jpg')
+  print((await client.get_me()).stringify())
 
-    client.download_profile_photo('me')
-    messages = client.get_messages('username')
-    messages[0].download_media()
+  await client.send_message('username', 'Hello! Talking to you from Telethon')
+  await client.send_file('username', '/home/myself/Pictures/holidays.jpg')
 
-    @client.on(events.NewMessage(pattern='(?i)hi|hello'))
-    async def handler(event):
-        await event.respond('Hey!')
+  await client.download_profile_photo('me')
+  messages = await client.get_messages('username')
+  await client.download_media(messages[0])
 
 
 Next steps
 ----------
 
-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
+Do you like how Telethon looks? Check out
+`Read The Docs <http://telethon.rtfd.io/>`_
+for a more in-depth explanation, with examples, troubleshooting issues,
+and more useful information. Note that the examples there are written for
+the threaded version, not the one using asyncio. However, you just need to
+await every remote call.

api/settings_example

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

dev-requirements.txt

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

logo.svg

@@ -1,6 +0,0 @@
-<!-- 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

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

pyproject.toml

@@ -1,36 +0,0 @@
-# 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/basic/installation.rst

@@ -1,96 +0,0 @@
-.. _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

@@ -1,46 +0,0 @@
-==========
-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

@@ -1,111 +0,0 @@
-===========
-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

@@ -1,229 +0,0 @@
-.. _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

@@ -1,159 +0,0 @@
-=======
-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

@@ -1,368 +0,0 @@
-.. _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

@@ -1,336 +0,0 @@
-.. _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

@@ -1,169 +0,0 @@
-.. _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

@@ -1,313 +0,0 @@
-.. _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

@@ -1,155 +0,0 @@
-.. _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

@@ -1,420 +0,0 @@
-.. _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

@@ -1,165 +0,0 @@
-.. _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

@@ -1,88 +0,0 @@
-======================
-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

@@ -1,228 +0,0 @@
-================
-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

@@ -20,13 +20,13 @@
 import re
 import os
 import sys
+sys.path.insert(0, os.path.abspath('.'))
 
-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'
+tl_ref_url = 'https://lonamiwebs.github.io/Telethon'
+
 
 # -- General configuration ------------------------------------------------
 
@@ -39,15 +39,9 @@ tl_ref_url = 'https://tl.telethon.dev'
 # 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"
 
@@ -65,7 +59,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = 'Telethon'
-copyright = '2017 - 2019, Lonami'
+copyright = '2017, Lonami'
 author = 'Lonami'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -73,7 +67,7 @@ author = 'Lonami'
 # built documents.
 #
 # The short X.Y version.
-with open(os.path.join(root, 'telethon', 'version.py'), 'r') as f:
+with open(os.path.join(root, 'telethon', 'version.py')) as f:
     version = re.search(r"^__version__\s+=\s+'(.*)'$",
                         f.read(), flags=re.MULTILINE).group(1)
 
@@ -85,7 +79,7 @@ release = version
 #
 # 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'
+language = None
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -93,30 +87,12 @@ language = 'en'
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'friendly'
+pygments_style = 'sphinx'
 
 # 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
@@ -137,7 +113,7 @@ html_theme_options = {
 # 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']
+html_static_path = ['_static']
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
@@ -209,3 +185,5 @@ texinfo_documents = [
      'Miscellaneous'),
 ]
 
+
+

readthedocs/custom_roles.py

@@ -28,7 +28,6 @@ def make_link_node(rawtext, app, name, options):
     return node
 
 
-# noinspection PyUnusedLocal
 def tl_role(name, rawtext, text, lineno, inliner, options=None, content=None):
     """
     Link to the TL reference.
@@ -46,6 +45,8 @@ def tl_role(name, rawtext, text, lineno, inliner, options=None, content=None):
     """
     if options is None:
         options = {}
+    if content is None:
+        content = []
 
     # TODO Report error on type not found?
     # Usage:
@@ -62,6 +63,7 @@ def setup(app):
 
     :param app: Sphinx application context.
     """
+    app.info('Initializing TL reference plugin')
     app.add_role('tl', tl_role)
     app.add_config_value('tl_ref_url', None, 'env')
     return

readthedocs/developing/project-structure.rst

@@ -1,51 +0,0 @@
-=================
-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

@@ -1,13 +0,0 @@
-===============================
-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/testing.rst

@@ -1,87 +0,0 @@
-=====
-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/examples/chats-and-channels.rst

@@ -1,128 +0,0 @@
-===============================
-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

@@ -1,74 +0,0 @@
-=====
-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

@@ -1,17 +0,0 @@
-=================
-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

@@ -1,13 +0,0 @@
-=====================
-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/extra/advanced-usage/accessing-the-full-api.rst

@@ -0,0 +1,147 @@
+.. _accessing-the-full-api:
+
+======================
+Accessing the Full API
+======================
+
+.. important::
+
+    While you have access to this, you should always use the friendly
+    methods listed on :ref:`telethon-package` unless you have a better
+    reason not to, like a method not existing or you wanting more control.
+
+
+The `telethon.telegram_client.TelegramClient` doesn't offer a method for every
+single request the Telegram API supports. However, it's very simple to *call*
+or *invoke* any request. Whenever you need something, don't forget to `check
+the documentation`__ and look for the `method you need`__. There you can go
+through a sorted list of everything you can do.
+
+
+.. note::
+
+    The reason to keep both https://lonamiwebs.github.io/Telethon 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.
+
+
+You should also refer to the documentation to see what the objects
+(constructors) Telegram returns look like. Every constructor inherits
+from a common type, and that's the reason for this distinction.
+
+Say `telethon.telegram_client.TelegramClient.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 `telethon.telegram_client.TelegramClient.get_input_entity()`:
+
+    .. code-block:: python
+
+        peer = await client.get_input_entity('someone')
+
+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
+``.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
+`telethon.telegram_client.TelegramClient.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_user(entity)
+
+
+.. note::
+
+    Since ``v0.16.2`` this is further simplified. The ``Request`` itself
+    will call ``client.get_input_entity()`` for you when required, but
+    it's good to remember what's happening.
+
+
+After this small parenthesis about ``.get_entity`` versus
+``.get_input_entity``, we have everything we need. To ``.invoke()`` our
+request we do:
+
+    .. code-block:: python
+
+        result = await client(SendMessageRequest(peer, 'Hello there!'))
+        # __call__ is an alias for client.invoke(request). Both will work
+
+Message sent! Of course, this is only an example. There are nearly 250
+methods available as of layer 73, and you can use every single of them
+as you wish. Remember to use the right types! To sum up:
+
+    .. code-block:: python
+
+        async def method():
+            result = await client(SendMessageRequest(
+                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.
+
+
+__ https://lonamiwebs.github.io/Telethon
+__ https://lonamiwebs.github.io/Telethon/methods/index.html
+__ https://lonamiwebs.github.io/Telethon/?q=message&redirect=no

readthedocs/extra/advanced-usage/sessions.rst

@@ -0,0 +1,132 @@
+.. _sessions:
+
+==============
+Session Files
+==============
+
+The first parameter you pass to the constructor of the ``TelegramClient`` 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 an 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``.
+
+Custom 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.
+
+To use a custom session storage, simply pass the custom session instance to
+``TelegramClient`` instead of the session name.
+
+Telethon contains two implementations of the abstract ``Session`` class:
+
+* ``MemorySession``: stores session data in Python variables.
+* ``SQLiteSession``, (default): stores sessions in their own SQLite databases.
+
+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.
+
+Creating your own storage
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The easiest way to create your own storage implementation is to use ``MemorySession``
+as the base and check out how ``SQLiteSession`` or one of the community-maintained
+implementations work. You can find the relevant Python files under the ``sessions``
+directory in Telethon.
+
+After you have made your own implementation, you can add it to the community-maintained
+session implementation list above with a pull request.
+
+SQLite Sessions and Heroku
+--------------------------
+
+You probably have a newer version of SQLite installed (>= 3.8.2). Heroku uses
+SQLite 3.7.9 which does not support ``WITHOUT ROWID``. So, if you generated
+your session file on a system with SQLite >= 3.8.2 your session file will not
+work on Heroku's platform and will throw a corrupted schema error.
+
+There are multiple ways to solve this, the easiest of which is generating a
+session file on your Heroku dyno itself. The most complicated is creating
+a custom buildpack to install SQLite >= 3.8.2.
+
+
+Generating a SQLite Session File on a Heroku Dyno
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+    Due to Heroku's ephemeral filesystem all dynamically generated
+    files not part of your applications buildpack or codebase are destroyed
+    upon each restart.
+
+.. warning::
+    Do not restart your application Dyno at any point prior to retrieving your
+    session file. Constantly creating new session files from Telegram's API
+    will result in a 24 hour rate limit ban.
+
+Due to Heroku's ephemeral filesystem all dynamically generated
+files not part of your applications buildpack or codebase are destroyed upon
+each restart.
+
+Using this scaffolded code we can start the authentication process:
+
+    .. code-block:: python
+
+        client = TelegramClient('login.session', api_id, api_hash).start()
+
+At this point your Dyno will crash because you cannot access stdin. Open your
+Dyno's control panel on the Heroku website and "Run console" from the "More"
+dropdown at the top right. Enter ``bash`` and wait for it to load.
+
+You will automatically be placed into your applications working directory.
+So run your application ``python app.py`` and now you can complete the input
+requests such as "what is your phone number" etc.
+
+Once you're successfully authenticated exit your application script with
+CTRL + C and ``ls`` to confirm ``login.session`` exists in your current
+directory. Now you can create a git repo on your account and commit
+``login.session`` to that repo.
+
+You cannot ``ssh`` into your Dyno instance because it has crashed, so unless
+you programatically upload this file to a server host this is the only way to
+get it off of your Dyno.
+
+You now have a session file compatible with SQLite <= 3.8.2. Now you can
+programatically fetch this file from an external host (Firebase, S3 etc.)
+and login to your session using the following scaffolded code:
+
+    .. code-block:: python
+
+        fileName, headers = urllib.request.urlretrieve(file_url, 'login.session')
+        client = TelegramClient(os.path.abspath(fileName), api_id, api_hash).start()
+
+.. note::
+    - ``urlretrieve`` will be depreciated, consider using ``requests``.
+    - ``file_url`` represents the location of your file.

readthedocs/extra/advanced-usage/update-modes.rst

@@ -0,0 +1,50 @@
+.. _update-modes:
+
+============
+Update Modes
+============
+
+Using ``asyncio`` simplifies the way you can work with updates. The library
+will always ensure the future of a loop that will poll updates for you, so
+you can do other things in the mean time.
+
+Once you have your client ready, the next thing you want to do is to add a
+method that will be called when an `Update`__ arrives:
+
+    .. code-block:: python
+
+        import asyncio
+        loop = asyncio.get_event_loop()
+
+        async def callback(update):
+            print('I received', update)
+
+        loop.run_until_complete(client.add_event_handler(callback))
+        loop.run_forever()  # this blocks forever, don't let the script end!
+
+That's it! This is the old way to listen for raw updates, with no further
+processing. If this feels annoying for you, remember that you can always
+use :ref:`working-with-updates` but maybe use this for some other cases.
+
+Now let's do something more interesting. Every time an user talks to us,
+let's reply to them with the same text reversed:
+
+    .. code-block:: python
+
+        from telethon.tl.types import UpdateShortMessage, PeerUser
+
+        async def replier(update):
+            if isinstance(update, UpdateShortMessage) and not update.out:
+                await client.send_message(PeerUser(update.user_id), update.message[::-1])
+
+
+        loop.run_until_complete(client.add_event_handler(replier))
+        loop.run_forever()
+
+We only ask you one thing: don't keep this running for too long, or your
+contacts will go mad.
+
+
+This is the preferred way to use if you're simply going to listen for updates.
+
+__ https://lonamiwebs.github.io/Telethon/types/update.html

readthedocs/extra/basic/creating-a-client.rst

@@ -0,0 +1,215 @@
+.. _creating-a-client:
+
+=================
+Creating a Client
+=================
+
+
+Before working with Telegram's API, you need to get your own API ID and hash:
+
+1. Follow `this link <https://my.telegram.org/>`_ and login with your
+   phone number.
+
+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!
+
+Once that's ready, the next step is to create a ``TelegramClient``.
+This class will be your main interface with Telegram's API, and creating
+one is very simple:
+
+    .. code-block:: python
+
+        from telethon import TelegramClient
+
+        # Use your own values here
+        api_id = 12345
+        api_hash = '0123456789abcdef0123456789abcdef'
+
+        client = TelegramClient('some_name', api_id, api_hash)
+
+
+Note that ``'some_name'`` will be used to save your session (persistent
+information such as access key and others) as ``'some_name.session'`` in
+your disk. This is by default a database file using Python's ``sqlite3``.
+
+.. note::
+
+    It's important that the library always accesses the same session file so
+    that you don't need to re-send the code over and over again. By default it
+    creates the file in your working directory, but absolute paths work too.
+
+
+Before using the client, you must be connected to Telegram.
+Doing so is very easy:
+
+    ``await client.connect()  # Must return True, otherwise, try again``
+
+You may or may not be authorized yet. You must be authorized
+before you're able to send any request:
+
+    ``client.is_user_authorized()  # Returns True if you can send requests``
+
+If you're not authorized, you need to ``.sign_in()``:
+
+    .. code-block:: python
+
+        phone_number = '+34600000000'
+        await client.send_code_request(phone_number)
+        myself = await client.sign_in(phone_number, input('Enter code: '))
+        # If .sign_in raises PhoneNumberUnoccupiedError, use .sign_up instead
+        # If .sign_in raises SessionPasswordNeeded error, call .sign_in(password=...)
+        # You can import both exceptions from telethon.errors.
+
+.. note::
+
+    If you send the code that Telegram sent you over the app through the
+    app itself, it will expire immediately. You can still send the code
+    through the app by "obfuscating" it (maybe add a magic constant, like
+    ``12345``, and then subtract it to get the real code back) or any other
+    technique.
+
+``myself`` is your Telegram user. You can view all the information about
+yourself by doing ``print(myself.stringify())``. You're now ready to use
+the client as you wish! Remember that any object returned by the API has
+mentioned ``.stringify()`` method, and printing these might prove useful.
+
+As a full example:
+
+    .. code-block:: python
+
+        async def main():
+            client = TelegramClient('anon', api_id, api_hash)
+            assert await client.connect()
+            if not client.is_user_authorized():
+                await client.send_code_request(phone_number)
+                me = await client.sign_in(phone_number, input('Enter code: '))
+
+
+All of this, however, can be done through a call to ``.start()``:
+
+    .. code-block:: python
+
+        async def main():
+            client = TelegramClient('anon', api_id, api_hash)
+            await client.start()
+
+
+The code shown is just what ``.start()`` will be doing behind the scenes
+(with a few extra checks), so that you know how to sign in case you want
+to avoid using ``input()`` (the default) for whatever reason. If no phone
+or bot token is provided, you will be asked one through ``input()``. The
+method also accepts a ``phone=`` and ``bot_token`` parameters.
+
+You can use either, as both will work. Determining which
+is just a matter of taste, and how much control you need.
+
+Remember that you can get yourself at any time with ``client.get_me()``.
+
+Assuming you've written all of this in a ``async def main():``, you can
+run it with:
+
+    .. code-block:: python
+
+        import asyncio
+
+        async def main():
+            ...
+
+        asyncio.get_event_loop().run_until_complete(main())
+
+
+.. warning::
+    Please note that if you fail to login around 5 times (or change the first
+    parameter of the ``TelegramClient``, which is the session name) you will
+    receive a ``FloodWaitError`` of around 22 hours, so be careful not to mess
+    this up! This shouldn't happen if you're doing things as explained, though.
+
+.. note::
+    If you want to use a **proxy**, you have to `install PySocks`__
+    (via pip or manual) and then set the appropriated parameters:
+
+        .. code-block:: python
+
+            import socks
+            client = TelegramClient('session_id',
+                api_id=12345, api_hash='0123456789abcdef0123456789abcdef',
+                proxy=(socks.SOCKS5, 'localhost', 4444)
+            )
+
+    The ``proxy=`` argument should be a tuple, a list or a dict,
+    consisting of parameters described `here`__.
+
+
+
+Two Factor Authorization (2FA)
+******************************
+
+If you have Two Factor Authorization (from now on, 2FA) enabled on your
+account, calling :meth:`telethon.TelegramClient.sign_in` will raise a
+``SessionPasswordNeededError``. When this happens, just
+:meth:`telethon.TelegramClient.sign_in` again with a ``password=``:
+
+    .. code-block:: python
+
+        import getpass
+        from telethon.errors import SessionPasswordNeededError
+
+        await client.sign_in(phone)
+        try:
+            await client.sign_in(code=input('Enter code: '))
+        except SessionPasswordNeededError:
+            await client.sign_in(password=getpass.getpass())
+
+
+The mentioned ``.start()`` method will handle this for you as well, but
+you must set the ``password=`` parameter beforehand (it won't be asked).
+
+If you don't have 2FA enabled, but you would like to do so through the library,
+use ``client.edit_2fa()``.
+Be sure to know what you're doing when using this function and
+you won't run into any problems.
+Take note that if you want to set only the email/hint and leave 
+the current password unchanged, you need to "redo" the 2fa.
+
+See the examples below:
+
+    .. code-block:: python
+
+        from telethon.errors import EmailUnconfirmedError
+        
+        # Sets 2FA password for first time:
+        await client.edit_2fa(new_password='supersecurepassword')
+        
+        # Changes password:
+        await client.edit_2fa(current_password='supersecurepassword',
+                              new_password='changedmymind')
+        
+        # Clears current password (i.e. removes 2FA):
+        await client.edit_2fa(current_password='changedmymind', new_password=None)
+        
+        # Sets new password with recovery email:
+        try:
+            await client.edit_2fa(new_password='memes and dreams',
+                                  email='JohnSmith@example.com')
+            # Raises error (you need to check your email to complete 2FA setup.)
+        except EmailUnconfirmedError:
+            # You can put email checking code here if desired.
+            pass
+            
+        # Also take note that unless you remove 2FA or explicitly
+        # give email parameter again it will keep the last used setting
+        
+        # Set hint after already setting password:
+        await client.edit_2fa(current_password='memes and dreams',
+                              new_password='memes and dreams',
+                              hint='It keeps you alive')
+
+__ https://github.com/Anorov/PySocks#installation
+__ https://github.com/Anorov/PySocks#usage-1

readthedocs/extra/basic/entities.rst

@@ -0,0 +1,150 @@
+.. _entities:
+
+=========================
+Users, Chats and Channels
+=========================
+
+
+Introduction
+************
+
+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 contacts.
+
+    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.telegram_client.TelegramClient.get_dialogs>`.
+    If the peer is someone in a group, you would similarly
+    `client.get_participants(group) <telethon.telegram_client.TelegramClient.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.
+
+
+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 (inside an ``async def``):
+
+    .. code-block:: python
+
+        # Dialogs are the "conversations you have open".
+        # This method returns a list of Dialog, which
+        # has the .entity attribute and other information.
+        dialogs = await client.get_dialogs()
+
+        # All of these work and do the same.
+        lonami = await client.get_entity('lonami')
+        lonami = await client.get_entity('t.me/lonami')
+        lonami = await client.get_entity('https://telegram.dog/lonami')
+
+        # 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))
+
+
+All methods in the :ref:`telegram-client` call ``.get_input_entity()`` prior
+to sending the requst to save you from the hassle of doing so manually.
+That way, convenience calls such as ``client.send_message('lonami', 'hi!')``
+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::
+
+    Don't worry if you don't understand this section, just remember some
+    of the details listed here are important. When you're calling a method,
+    don't call ``.get_entity()`` beforehand, just use the username or phone,
+    or the entity retrieved by other means like ``.get_dialogs()``.
+
+
+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**.
+
+This ID/hash pair is unique per user, so if you use the pair given by another
+user **or bot** it will **not** work.
+
+To save *even more* bandwidth, the API also makes use of the :tl:`Peer`
+versions, which just have an ID. This serves to identify them, but
+peers alone are not enough to use them. You need to know their hash
+before you can "use them".
+
+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,
+``.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** ``.get_input_entity()`` **over** ``.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 ``InputPeer``. Only use ``.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
+``.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.

readthedocs/extra/basic/getting-started.rst

@@ -0,0 +1,98 @@
+.. _getting-started:
+
+
+===============
+Getting Started
+===============
+
+
+Simple Installation
+*******************
+
+   ``pip3 install telethon``
+
+   **More details**: :ref:`installation`
+
+
+Creating a client
+*****************
+
+   .. code-block:: python
+
+       import asyncio
+       loop = asyncio.get_event_loop()
+
+       from telethon import TelegramClient
+
+
+       # 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)
+       loop.run_until_complete(client.start())
+
+   **More details**: :ref:`creating-a-client`
+
+
+Basic Usage
+***********
+
+   .. code-block:: python
+
+       # You should write all this inside of an async def.
+       #
+       # Getting information about yourself
+       print((await client.get_me()).stringify())
+
+       # Sending a message (you can use 'me' or 'self' to message yourself)
+       await client.send_message('username', 'Hello World from Telethon!')
+
+       # Sending a file
+       await client.send_file('username', '/home/myself/Pictures/holidays.jpg')
+
+       # Retrieving messages from a chat
+       from telethon import utils
+       async for message in client.iter_messages('username', limit=10):
+           print(utils.get_display_name(message.sender), message.message)
+
+       # Listing all the dialogs (conversations you have open)
+       async for dialog in client.get_dialogs(limit=10):
+           print(utils.get_display_name(dialog.entity), dialog.draft.message)
+
+       # Downloading profile photos (default path is the working directory)
+       await client.download_profile_photo('username')
+
+       # Once you have a message with .media (if message.media)
+       # you can download it using client.download_media():
+       messages = await client.get_messages('username')
+       await client.download_media(messages[0])
+
+   **More details**: :ref:`telegram-client`
+
+   See :ref:`telethon-package` for all available friendly methods.
+
+
+Handling Updates
+****************
+
+   .. code-block:: python
+
+       import asyncio
+       from telethon import events
+
+       @client.on(events.NewMessage(incoming=True, pattern='(?i)hi'))
+       async def handler(event):
+           await event.reply('Hello!')
+
+       # If you want to handle updates you can't let the script end.
+       asyncio.get_event_loop().run_forever()
+
+   **More details**: :ref:`working-with-updates`
+
+
+----------
+
+You can continue by clicking on the "More details" link below each
+snippet of code or the "Next" button at the bottom of the page.

readthedocs/extra/basic/installation.rst

@@ -0,0 +1,78 @@
+.. _installation:
+
+============
+Installation
+============
+
+
+Automatic Installation
+**********************
+
+To install Telethon, simply do:
+
+    ``pip3 install telethon``
+
+Needless to say, you must have Python 3 and PyPi installed in your system.
+See https://python.org and https://pypi.python.org/pypi/pip for more.
+
+If you already have the library installed, upgrade with:
+
+    ``pip3 install --upgrade telethon``
+
+You can also install the library directly from GitHub or a fork:
+
+   .. code-block:: sh
+
+        # pip3 install git+https://github.com/LonamiWebs/Telethon.git
+        or
+        $ git clone https://github.com/LonamiWebs/Telethon.git
+        $ cd Telethon/
+        # pip install -Ue .
+
+If you don't have root access, simply pass the ``--user`` flag to the pip
+command. If you want to install a specific branch, append ``@branch`` to
+the end of the first install command.
+
+By default the library will use a pure Python implementation for encryption,
+which can be really slow when uploading or downloading files. If you don't
+mind using a C extension, install `cryptg <https://github.com/Lonami/cryptg>`__
+via ``pip`` or as an extra:
+
+    ``pip3 install telethon[cryptg]``
+
+
+Manual Installation
+*******************
+
+1. Install the required ``pyaes`` (`GitHub`__ | `PyPi`__) and
+   ``rsa`` (`GitHub`__ | `PyPi`__) modules:
+
+    ``sudo -H pip3 install pyaes rsa``
+
+2. Clone Telethon's GitHub repository:
+   ``git clone https://github.com/LonamiWebs/Telethon.git``
+
+3. Enter the cloned repository: ``cd Telethon``
+
+4. Run the code generator: ``python3 setup.py gen tl errors``
+
+5. Done!
+
+To generate the `method documentation`__, ``python3 setup.py gen docs``.
+
+
+Optional dependencies
+*********************
+
+If the `cryptg`__ is installed, you might notice a speed-up in the download
+and upload speed, since these are the most cryptographic-heavy part of the
+library and said module is a C extension. Otherwise, the ``pyaes`` fallback
+will be used.
+
+
+__ https://github.com/ricmoo/pyaes
+__ https://pypi.python.org/pypi/pyaes
+__ https://github.com/sybrenstuvel/python-rsa
+__ https://pypi.python.org/pypi/rsa/3.4.2
+__ https://lonamiwebs.github.io/Telethon
+__ https://github.com/Lonami/cryptg

readthedocs/extra/basic/telegram-client.rst

@@ -0,0 +1,106 @@
+.. _telegram-client:
+
+==============
+TelegramClient
+==============
+
+
+Introduction
+************
+
+.. note::
+
+    Make sure to use the friendly methods described in :ref:`telethon-package`!
+    This section is just an introduction to using the client, but all the
+    available methods are in the :ref:`telethon-package` reference, including
+    detailed descriptions to what they do.
+
+The ``TelegramClient`` is the central class of the library, the one
+you will be using most of the time. For this reason, it's important
+to know what it offers.
+
+Since we're working with Python, one must not forget that we can do
+``help(client)`` or ``help(TelegramClient)`` at any time for a more
+detailed description and a list of all the available methods. Calling
+``help()`` from an interactive Python session will always list all the
+methods for any object, even yours!
+
+Interacting with the Telegram API is done through sending **requests**,
+this is, any "method" listed on the API. There are a few methods (and
+growing!) on the ``TelegramClient`` class that abstract you from the
+need of manually importing the requests you need.
+
+For instance, retrieving your own user can be done in a single line:
+
+    ``myself = await client.get_me()``
+
+Internally, this method has sent a request to Telegram, who replied with
+the information about your own user, and then the desired information
+was extracted from their response.
+
+If you want to retrieve any other user, chat or channel (channels are a
+special subset of chats), you want to retrieve their "entity". This is
+how the library refers to either of these:
+
+    .. code-block:: python
+
+        # The method will infer that you've passed an username
+        # It also accepts phone numbers, and will get the user
+        # from your contact list.
+        lonami = await client.get_entity('lonami')
+
+The so called "entities" are another important whole concept on its own,
+but for now you don't need to worry about it. Simply know that they are
+a good way to get information about an user, chat or channel.
+
+Many other common methods for quick scripts are also available.
+Note that you should be writing this inside of an ``async def``:
+
+    .. code-block:: python
+
+        # Note that you can use 'me' or 'self' to message yourself
+        await client.send_message('username', 'Hello World from Telethon!')
+
+        # .send_message's parse mode defaults to markdown, so you
+        # can use **bold**, __italics__, [links](https://example.com), `code`,
+        # and even [mentions](@username)/[mentions](tg://user?id=123456789)
+        await client.send_message('username', '**Using** __markdown__ `too`!')
+
+        await client.send_file('username', '/home/myself/Pictures/holidays.jpg')
+
+        # The utils package has some goodies, like .get_display_name()
+        from telethon import utils
+        async for message in client.iter_messages('username', limit=10):
+            print(utils.get_display_name(message.sender), message.message)
+
+        # Dialogs are the conversations you have open
+        async for dialog in client.get_dialogs(limit=10):
+            print(utils.get_display_name(dialog.entity), dialog.draft.message)
+
+        # Default path is the working directory
+        await client.download_profile_photo('username')
+
+        # Call .disconnect() when you're done
+        client.disconnect()
+
+Remember that you can call ``.stringify()`` to any object Telegram returns
+to pretty print it. Calling ``str(result)`` does the same operation, but on
+a single line.
+
+
+Available methods
+*****************
+
+The :ref:`reference <telethon-package>` lists all the "handy" methods
+available for you to use in the ``TelegramClient`` class. These are simply
+wrappers around the "raw" Telegram API, making it much more manageable and
+easier to work with.
+
+Please refer to :ref:`accessing-the-full-api` if these aren't enough,
+and don't be afraid to read the source code of the InteractiveTelegramClient_
+or even the TelegramClient_ itself to learn how it works.
+
+See the mentioned :ref:`telethon-package` to find the available methods.
+
+.. _InteractiveTelegramClient: https://github.com/LonamiWebs/Telethon/blob/master/telethon_examples/interactive_telegram_client.py
+.. _TelegramClient: https://github.com/LonamiWebs/Telethon/blob/master/telethon/telegram_client.py

readthedocs/extra/basic/working-with-updates.rst

@@ -0,0 +1,194 @@
+.. _working-with-updates:
+
+====================
+Working with Updates
+====================
+
+
+The library comes with the :mod:`events` module. *Events* are an abstraction
+over what Telegram calls `updates`__, and are meant to ease simple and common
+usage when dealing with them, since there are many updates. If you're looking
+for the method reference, check :ref:`telethon-events-package`, otherwise,
+let's dive in!
+
+
+.. note::
+
+    The library logs by default no output, and any exception that occurs
+    inside your handlers will be "hidden" from you to prevent the thread
+    from terminating (so it can still deliver events). You should enable
+    logging (``import logging; logging.basicConfig(level=logging.ERROR)``)
+    when working with events, at least the error level, to see if this is
+    happening so you can debug the error.
+
+
+.. contents::
+
+
+Getting Started
+***************
+
+    .. code-block:: python
+
+        import asyncio
+        loop = asyncio.get_event_loop()
+
+        from telethon import TelegramClient, events
+
+        client = TelegramClient(...)
+        loop.run_until_complete(client.start())
+
+        @client.on(events.NewMessage)
+        async def my_event_handler(event):
+            if 'hello' in event.raw_text:
+                await event.reply('hi!')
+
+        loop.run_forever()
+
+
+Not much, but there might be some things unclear. What does this code do?
+
+    .. code-block:: python
+
+        import asyncio
+        loop = asyncio.get_event_loop()
+
+        from telethon import TelegramClient, events
+
+        client = TelegramClient(...)
+        loop.run_until_complete(client.start())
+
+
+This is normal initialization (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`` *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`` event occurs, and ``'hello'`` is in the text of the
+message, we ``reply`` to the event with a ``'hi!'`` message.
+
+    .. code-block:: python
+
+        loop.run_forever()
+
+
+Finally, this tells the script that we're done with our code, and want
+to listen for all these events to occur. Of course, you might want to
+do other things instead idling. For this refer to :ref:`update-modes`.
+
+
+More on events
+**************
+
+The ``NewMessage`` event has much more than what was shown. You can access
+the ``.sender`` of the message through that member, or even see if the message
+had ``.media``, a ``.photo`` or a ``.document`` (which you could download with
+for example ``client.download_media(event.photo)``.
+
+If you don't want to ``.reply`` as a reply, you can use the ``.respond()``
+method instead. Of course, there are more events such as ``ChatAction`` or
+``UserUpdate``, and they're all used in the same way. Simply add the
+``@client.on(events.XYZ)`` decorator on the top of your handler and you're
+done! The event that will be passed always is of type ``XYZ.Event`` (for
+instance, ``NewMessage.Event``), except for the ``Raw`` event which just
+passes the ``Update`` object.
+
+Note that ``.reply()`` and ``.respond()`` are just wrappers around the
+``client.send_message()`` method which supports the ``file=`` parameter.
+This means you can reply with a photo if you do ``client.reply(file=photo)``.
+
+You can put the same event on many handlers, and even different events on
+the same handler. You can also have a handler work on only specific chats,
+for example:
+
+
+    .. code-block:: python
+
+        import ast
+        import random
+
+
+        # Either a single item or a list of them will work for the chats.
+        # You can also use the IDs, Peers, or even User/Chat/Channel objects.
+        @client.on(events.NewMessage(chats=('TelethonChat', 'TelethonOffTopic')))
+        async def normal_handler(event):
+            if 'roll' in event.raw_text:
+                await event.reply(str(random.randint(1, 6)))
+
+
+        # Similarly, you can use incoming=True for messages that you receive
+        @client.on(events.NewMessage(chats='TelethonOffTopic', outgoing=True))
+        async def admin_handler(event):
+            if event.raw_text.startswith('eval'):
+                expression = event.raw_text.replace('eval', '').strip()
+                await event.reply(str(ast.literal_eval(expression)))
+
+
+You can pass one or more chats to the ``chats`` parameter (as a list or tuple),
+and only events from there will be processed. You can also specify whether you
+want to handle incoming or outgoing messages (those you receive or those you
+send). In this example, people can say ``'roll'`` and you will reply with a
+random number, while if you say ``'eval 4+4'``, you will reply with the
+solution. Try it!
+
+
+Events without decorators
+*************************
+
+If for any reason you can't use the ``@client.on`` syntax, don't worry.
+You can call ``client.add_event_handler(callback, event)`` to achieve
+the same effect.
+
+Similar to that method, you also have :meth:`client.remove_event_handler`
+and :meth:`client.list_event_handlers` which do as they names indicate.
+
+The ``event`` type is optional in all methods and defaults to ``events.Raw``
+for adding, and ``None`` when removing (so all callbacks would be removed).
+
+
+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 ``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-package` if you're looking for
+the methods reference.
+
+
+__ https://lonamiwebs.github.io/Telethon/types/update.html

readthedocs/extra/developing/api-status.rst

@@ -0,0 +1,54 @@
+.. _api-status:
+
+==========
+API Status
+==========
+
+
+In an attempt to help everyone who works with the Telegram API, the
+library will by default report all *Remote Procedure Call* errors to
+`RPC PWRTelegram <https://rpc.pwrtelegram.xyz/>`__, a public database
+anyone can query, made by `Daniil <https://github.com/danog>`__. All the
+information sent is a ``GET`` request with the error code, error message
+and method used.
+
+If you still would like to opt out, you can disable this feature by setting
+``client.session.report_errors = False``. However Daniil would really thank
+you if you helped him (and everyone) by keeping it on!
+
+Querying the API status
+***********************
+
+The API is accessed through ``GET`` requests, which can be made for
+instance through ``curl``. A JSON response will be returned.
+
+**All known errors and their description**:
+
+.. code:: bash
+
+    curl https://rpc.pwrtelegram.xyz/?all
+
+**Error codes for a specific request**:
+
+.. code:: bash
+
+    curl https://rpc.pwrtelegram.xyz/?for=messages.sendMessage
+
+**Number of** ``RPC_CALL_FAIL``:
+
+.. code:: bash
+
+    curl https://rpc.pwrtelegram.xyz/?rip  # last hour
+    curl https://rpc.pwrtelegram.xyz/?rip=$(time()-60)  # last minute
+
+**Description of errors**:
+
+.. code:: bash
+
+    curl https://rpc.pwrtelegram.xyz/?description_for=SESSION_REVOKED
+
+**Code of a specific error**:
+
+.. code:: bash
+
+    curl https://rpc.pwrtelegram.xyz/?code_for=STICKERSET_INVALID

readthedocs/extra/developing/project-structure.rst

@@ -0,0 +1,47 @@
+=================
+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 the ``TelegramBareClient``. The later is
+basically a pruned version of the ``TelegramClient``, which knows basic
+stuff like ``.invoke()``\ 'ing requests, downloading files, or switching
+between data centers. This is primary to keep the method count per class
+and file low and manageable.
+
+Both clients make use of the ``network/mtproto_sender.py``. The
+``MtProtoSender`` class handles packing requests with the ``salt``,
+``id``, ``sequence``, etc., and also handles how to process responses
+(i.e. pong, RPC errors). This class communicates through Telegram via
+its ``.connection`` member.
+
+The ``Connection`` class uses a ``extensions/tcp_client``, a C#-like
+``TcpClient`` to ease working with sockets in Python. All the
+``TcpClient`` know is how to connect through TCP and writing/reading
+from the socket with optional cancel.
+
+The ``Connection`` class bundles up all the connections modes and sends
+and receives the messages accordingly (TCP full, obfuscated,
+intermediate…).
+
+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.

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

@@ -0,0 +1,73 @@
+===============================
+Telegram API in Other Languages
+===============================
+
+
+Telethon was made for **Python**, and as far as I know, there is no
+*exact* port to other languages. However, there *are* other
+implementations made by awesome people (one needs to be awesome to
+understand the official Telegram documentation) on several languages
+(even more Python too), listed below:
+
+C
+*
+
+Possibly the most well-known unofficial open source implementation out
+there by `@vysheng <https://github.com/vysheng>`__,
+`tgl <https://github.com/vysheng/tgl>`__, and its console client
+`telegram-cli <https://github.com/vysheng/tg>`__. Latest development
+has been moved to `BitBucket <https://bitbucket.org/vysheng/tdcli>`__.
+
+C++
+***
+
+The newest (and official) library, written from scratch, is called
+`tdlib <https://github.com/tdlib/td>`__ and is what the Telegram X
+uses. You can find more information in the official documentation,
+published `here <https://core.telegram.org/tdlib/docs/>`__.
+
+JavaScript
+**********
+
+`@zerobias <https://github.com/zerobias>`__ is working on
+`telegram-mtproto <https://github.com/zerobias/telegram-mtproto>`__,
+a work-in-progress JavaScript library installable via
+`npm <https://www.npmjs.com/>`__.
+
+Kotlin
+******
+
+`Kotlogram <https://github.com/badoualy/kotlogram>`__ is a Telegram
+implementation written in Kotlin (one of the
+`official <https://blog.jetbrains.com/kotlin/2017/05/kotlin-on-android-now-official/>`__
+languages for
+`Android <https://developer.android.com/kotlin/index.html>`__) by
+`@badoualy <https://github.com/badoualy>`__, currently as a beta–
+yet working.
+
+PHP
+***
+
+A PHP implementation is also available thanks to
+`@danog <https://github.com/danog>`__ and his
+`MadelineProto <https://github.com/danog/MadelineProto>`__ project, with
+a very nice `online
+documentation <https://daniil.it/MadelineProto/API_docs/>`__ too.
+
+Python
+******
+
+A fairly new (as of the end of 2017) Telegram library written from the
+ground up in Python by
+`@delivrance <https://github.com/delivrance>`__ and his
+`Pyrogram <https://github.com/pyrogram/pyrogram>`__ library.
+There isn't really a reason to pick it over Telethon and it'd be kinda
+sad to see you go, but it would be nice to know what you miss from each
+other library in either one so both can improve.
+
+Rust
+****
+
+Yet another work-in-progress implementation, this time for Rust thanks
+to `@JuanPotato <https://github.com/JuanPotato>`__ under the fancy
+name of `Vail <https://github.com/JuanPotato/Vail>`__.

readthedocs/extra/developing/test-servers.rst

@@ -5,14 +5,14 @@ Test Servers
 
 To run Telethon on a test server, use the following code:
 
-.. code-block:: python
+    .. code-block:: python
 
-    client = TelegramClient(None, api_id, api_hash)
-    client.session.set_dc(dc_id, '149.154.167.40', 80)
+        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
+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).
 
@@ -28,14 +28,8 @@ Valid phone numbers are ``99966XYYYY``, where ``X`` is the ``dc_id`` and
 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
+    .. 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.
+        client = TelegramClient(None, api_id, api_hash)
+        client.session.set_dc(2, '149.154.167.40', 80)
+        await client.start(phone='9996621234', code_callback=lambda: '22222')

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

@@ -8,7 +8,7 @@ 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,
+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

readthedocs/extra/examples/bots.rst

@@ -0,0 +1,61 @@
+====
+Bots
+====
+
+
+.. note::
+
+    These examples assume you have read :ref:`accessing-the-full-api`.
+
+
+Talking to Inline Bots
+**********************
+
+You can query an inline bot, such as `@VoteBot`__ (note, *query*,
+not *interact* with a voting message), by making use of the
+:tl:`GetInlineBotResultsRequest` request:
+
+    .. code-block:: python
+
+        from telethon.tl.functions.messages import GetInlineBotResultsRequest
+
+        bot_results = await client(GetInlineBotResultsRequest(
+            bot, user_or_chat, 'query', ''
+        ))
+
+And you can select any of their results by using
+:tl:`SendInlineBotResultRequest`:
+
+    .. code-block:: python
+
+        from telethon.tl.functions.messages import SendInlineBotResultRequest
+
+        await client(SendInlineBotResultRequest(
+            get_input_peer(user_or_chat),
+            obtained_query_id,
+            obtained_str_id
+        ))
+
+
+Talking to Bots with special reply markup
+*****************************************
+
+To interact with a message that has a special reply markup, such as
+`@VoteBot`__ polls, you would use :tl:`GetBotCallbackAnswerRequest`:
+
+    .. code-block:: python
+
+        from telethon.tl.functions.messages import GetBotCallbackAnswerRequest
+
+        await client(GetBotCallbackAnswerRequest(
+            user_or_chat,
+            msg.id,
+            data=msg.reply_markup.rows[wanted_row].buttons[wanted_button].data
+        ))
+
+It's a bit verbose, but it has all the information you would need to
+show it visually (button rows, and buttons within each row, each with
+its own data).
+
+__ https://t.me/vote
+__ https://t.me/vote

readthedocs/extra/examples/chats-and-channels.rst

@@ -0,0 +1,309 @@
+===============================
+Working with Chats and Channels
+===============================
+
+
+.. note::
+
+    These examples assume you have read :ref:`accessing-the-full-api`.
+
+
+Joining a chat or channel
+*************************
+
+Note that :tl:`Chat` are normal groups, and :tl:`Channel` are a
+special form of ``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://lonamiwebs.github.io/Telethon/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]
+        ))
+
+
+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.
+
+
+Retrieving all chat members (channels too)
+******************************************
+
+.. note::
+
+    Use the `telethon.telegram_client.TelegramClient.iter_participants`
+    friendly method instead unless you have a better reason not to!
+
+    This method will handle different chat types for you automatically.
+
+
+In order to get all the members from a mega-group or channel, you need
+to use :tl:`GetParticipantsRequest`. As we can see it needs an
+:tl:`InputChannel`, (passing the mega-group or channel you're going to
+use will work), and a mandatory :tl:`ChannelParticipantsFilter`. The
+closest thing to "no filter" is to simply use
+:tl:`ChannelParticipantsSearch` with an empty ``'q'`` string.
+
+If we want to get *all* the members, we need to use a moving offset and
+a fixed limit:
+
+    .. code-block:: python
+
+        from telethon.tl.functions.channels import GetParticipantsRequest
+        from telethon.tl.types import ChannelParticipantsSearch
+        from time import sleep
+
+        offset = 0
+        limit = 100
+        all_participants = []
+
+        while True:
+            participants = await client(GetParticipantsRequest(
+                channel, ChannelParticipantsSearch(''), offset, limit,
+                hash=0
+            ))
+            if not participants.users:
+                break
+            all_participants.extend(participants.users)
+            offset += len(participants.users)
+
+
+.. note::
+
+    If you need more than 10,000 members from a group you should use the
+    mentioned ``client.get_participants(..., aggressive=True)``. It will
+    do some tricks behind the scenes to get as many entities as possible.
+    Refer to `issue 573`__ for more on this.
+
+
+Note that :tl:`GetParticipantsRequest` returns :tl:`ChannelParticipants`,
+which may have more information you need (like the role of the
+participants, total count of members, etc.)
+
+__ https://github.com/LonamiWebs/Telethon/issues/573
+
+
+Recent Actions
+**************
+
+"Recent actions" is simply the name official applications have given to
+the "admin log". Simply use :tl:`GetAdminLogRequest` for that, and
+you'll get AdminLogResults.events in return which in turn has the final
+`.action`__.
+
+__ https://lonamiwebs.github.io/Telethon/types/channel_admin_log_event_action.html
+
+
+Admin Permissions
+*****************
+
+Giving or revoking admin permissions can be done with the :tl:`EditAdminRequest`:
+
+    .. code-block:: python
+
+        from telethon.tl.functions.channels import EditAdminRequest
+        from telethon.tl.types import ChannelAdminRights
+
+        # You need both the channel and who to grant permissions
+        # They can either be channel/user or input channel/input user.
+        #
+        # ChannelAdminRights is a list of granted permissions.
+        # Set to True those you want to give.
+        rights = ChannelAdminRights(
+            post_messages=None,
+            add_admins=None,
+            invite_users=None,
+            change_info=True,
+            ban_users=None,
+            delete_messages=True,
+            pin_messages=True,
+            invite_link=None,
+            edit_messages=None
+        ) 
+        # Equivalent to:
+        #     rights = ChannelAdminRights(
+        #         change_info=True,
+        #         delete_messages=True,
+        #         pin_messages=True
+        #     )
+
+        # Once you have a ChannelAdminRights, invoke it
+        await client(EditAdminRequest(channel, user, rights))
+
+        # User will now be able to change group info, delete other people's
+        # messages and pin messages.
+
+
+.. note::
+
+    Thanks to `@Kyle2142`__ for `pointing out`__ that you **cannot** set all
+    parameters to ``True`` to give a user full permissions, as not all
+    permissions are related to both broadcast channels/megagroups.
+
+    E.g. trying to set ``post_messages=True`` in a megagroup will raise an
+    error. It is recommended to always use keyword arguments, and to set only
+    the permissions the user needs. If you don't need to change a permission,
+    it can be omitted (full list `here`__).
+
+
+Restricting Users
+*****************
+
+Similar to how you give or revoke admin permissions, you can edit the
+banned rights of an user through :tl:`EditAdminRequest` and its parameter
+:tl:`ChannelBannedRights`:
+
+    .. code-block:: python
+
+        from telethon.tl.functions.channels import EditBannedRequest
+        from telethon.tl.types import ChannelBannedRights
+
+        from datetime import datetime, timedelta
+
+        # Restricting an user for 7 days, only allowing view/send messages.
+        #
+        # Note that it's "reversed". You must set to ``True`` the permissions
+        # you want to REMOVE, and leave as ``None`` those you want to KEEP.
+        rights = ChannelBannedRights(
+            until_date=datetime.now() + timedelta(days=7),
+            view_messages=None,
+            send_messages=None,
+            send_media=True,
+            send_stickers=True,
+            send_gifs=True,
+            send_games=True,
+            send_inline=True,
+            embed_links=True
+        )
+
+        # The above is equivalent to
+        rights = ChannelBannedRights(
+            until_date=datetime.now() + timedelta(days=7),
+            send_media=True,
+            send_stickers=True,
+            send_gifs=True,
+            send_games=True,
+            send_inline=True,
+            embed_links=True
+        )
+
+        await client(EditBannedRequest(channel, user, rights))
+
+
+Kicking a member
+****************
+
+Telegram doesn't actually have a request to kick an user from a group.
+Instead, you need to restrict them so they can't see messages. Any date
+is enough:
+
+    .. code-block:: python
+
+        from telethon.tl.functions.channels import EditBannedRequest
+        from telethon.tl.types import ChannelBannedRights
+
+        await client(EditBannedRequest(channel, user, ChannelBannedRights(
+            until_date=None,
+            view_messages=True
+        )))
+
+
+__ https://github.com/Kyle2142
+__ https://github.com/LonamiWebs/Telethon/issues/490
+__ https://lonamiwebs.github.io/Telethon/constructors/channel_admin_rights.html
+
+
+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/extra/examples/projects-using-telethon.rst

@@ -0,0 +1,44 @@
+=======================
+Projects using Telethon
+=======================
+
+This page lists some real world examples showcasing what can be built with
+the library.
+
+.. note::
+
+    Do you have a project that uses the library or know of any that's not
+    listed here? Feel free to leave a comment at
+    `issue 744 <https://github.com/LonamiWebs/Telethon/issues/744>`_
+    so it can be included in the next revision of the documentation!
+
+.. _projects-telegram-export:
+
+telegram-export
+***************
+
+`Link <https://github.com/expectocode/telegram-export>`_ /
+`Author's website <https://github.com/expectocode>`_
+
+A tool to download Telegram data (users, chats, messages, and media)
+into a database (and display the saved data).
+
+.. _projects-mautrix-telegram:
+
+mautrix-telegram
+****************
+
+`Link <https://github.com/tulir/mautrix-telegram>`_ /
+`Author's website <https://maunium.net/>`_
+
+A Matrix-Telegram hybrid puppeting/relaybot bridge.
+
+.. _projects-telegramtui:
+
+TelegramTUI
+***********
+
+`Link <https://github.com/bad-day/TelegramTUI>`_ /
+`Author's website <https://github.com/bad-day>`_
+
+A Telegram client on your terminal.

readthedocs/extra/examples/users.rst

@@ -0,0 +1,70 @@
+=====
+Users
+=====
+
+
+.. note::
+
+    These examples assume you have read :ref:`accessing-the-full-api`.
+
+
+Retrieving full information
+***************************
+
+If you need to retrieve the bio, biography or about information for an 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.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(
+            client.upload_file('/path/to/some/file')
+        ))

readthedocs/extra/examples/working-with-messages.rst

@@ -0,0 +1,143 @@
+=====================
+Working with messages
+=====================
+
+
+.. note::
+
+    These examples assume you have read :ref:`accessing-the-full-api`.
+
+
+Forwarding messages
+*******************
+
+.. note::
+
+    Use the `telethon.telegram_client.TelegramClient.forward_messages`
+    friendly method instead unless you have a better reason not to!
+
+    This method automatically accepts either a single message or many of them.
+
+.. code-block:: python
+
+        # If you only have the message IDs
+        await client.forward_messages(
+            entity,  # to which entity you are forwarding the messages
+            message_ids,  # the IDs of the messages (or message) to forward
+            from_entity  # who sent the messages?
+        )
+
+        # If you have ``Message`` objects
+        await client.forward_messages(
+            entity,  # to which entity you are forwarding the messages
+            messages  # the messages (or message) to forward
+        )
+
+        # You can also do it manually if you prefer
+        from telethon.tl.functions.messages import ForwardMessagesRequest
+
+        messages = foo()  # retrieve a few messages (or even one, in a list)
+        from_entity = bar()
+        to_entity = baz()
+
+        await client(ForwardMessagesRequest(
+            from_peer=from_entity,  # who sent these messages?
+            id=[msg.id for msg in messages],  # which are the messages?
+            to_peer=to_entity  # who are we forwarding them to?
+        ))
+
+The named arguments are there for clarity, although they're not needed because
+they appear in order. You can obviously just wrap a single message on the list
+too, if that's all you have.
+
+
+Searching Messages
+*******************
+
+.. note::
+
+    Use the `telethon.telegram_client.TelegramClient.iter_messages`
+    friendly method instead unless you have a better reason not to!
+
+    This method has ``search`` and ``filter`` parameters that will
+    suit your needs.
+
+Messages are searched through the obvious :tl:`SearchRequest`, but you may run
+into issues_. A valid example would be:
+
+    .. code-block:: python
+
+        from telethon.tl.functions.messages import SearchRequest
+        from telethon.tl.types import InputMessagesFilterEmpty
+
+        filter = InputMessagesFilterEmpty()
+        result = await client(SearchRequest(
+            peer=peer,      # On which chat/conversation
+            q='query',      # What to search for
+            filter=filter,  # Filter to use (maybe filter for media)
+            min_date=None,  # Minimum date
+            max_date=None,  # Maximum date
+            offset_id=0,    # ID of the message to use as offset
+            add_offset=0,   # Additional offset
+            limit=10,       # How many results
+            max_id=0,       # Maximum message ID
+            min_id=0,       # Minimum message ID
+            from_id=None,   # Who must have sent the message (peer)
+            hash=0          # Special number to return nothing on no-change
+        ))
+
+It's important to note that the optional parameter ``from_id`` could have
+been omitted (defaulting to ``None``). Changing it to :tl:`InputUserEmpty`, as one
+could think to specify "no user", won't work because this parameter is a flag,
+and it being unspecified has a different meaning.
+
+If one were to set ``from_id=InputUserEmpty()``, it would filter messages
+from "empty" senders, which would likely match no users.
+
+If you get a ``ChatAdminRequiredError`` on a channel, it's probably because
+you tried setting the ``from_id`` filter, and as the error says, you can't
+do that. Leave it set to ``None`` and it should work.
+
+As with every method, make sure you use the right ID/hash combination for
+your ``InputUser`` or ``InputChat``, or you'll likely run into errors like
+``UserIdInvalidError``.
+
+
+Sending stickers
+****************
+
+Stickers are nothing else than ``files``, and when you successfully retrieve
+the stickers for a certain sticker set, all you will have are ``handles`` to
+these files. Remember, the files Telegram holds on their servers can be
+referenced through this pair of ID/hash (unique per user), and you need to
+use this handle when sending a "document" message. This working example will
+send yourself the very first sticker you have:
+
+    .. code-block:: python
+
+        # Get all the sticker sets this user has
+        sticker_sets = await client(GetAllStickersRequest(0))
+
+        # Choose a sticker set
+        sticker_set = sticker_sets.sets[0]
+
+        # Get the stickers for this sticker set
+        stickers = await client(GetStickerSetRequest(
+            stickerset=InputStickerSetID(
+                id=sticker_set.id, access_hash=sticker_set.access_hash
+            )
+        ))
+
+        # Stickers are nothing more than files, so send that
+        await client(SendMediaRequest(
+            peer=client.get_me(),
+            media=InputMediaDocument(
+                id=InputDocument(
+                    id=stickers.documents[0].id,
+                    access_hash=stickers.documents[0].access_hash
+                )
+            )
+        ))
+
+
+.. _issues: https://github.com/LonamiWebs/Telethon/issues/215

readthedocs/extra/troubleshooting/deleted-limited-or-deactivated-accounts.rst

@@ -0,0 +1,27 @@
+========================================
+Deleted, Limited or Deactivated Accounts
+========================================
+
+If you're from Iran or Russia, 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,
+and to sign up with these phones through an official application.
+
+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.
+
+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`__.
+
+
+__ https://t.me/SpamBot
+__ https://github.com/LonamiWebs/Telethon/issues/297

readthedocs/extra/troubleshooting/enable-logging.rst

@@ -0,0 +1,40 @@
+================
+Enabling Logging
+================
+
+Telethon makes use of the `logging`__ module, and you can enable it as follows:
+
+.. code:: python
+
+    import logging
+    logging.basicConfig(level=logging.DEBUG)
+
+The library has the `NullHandler`__ added by default so that no log calls
+will be printed unless you explicitly enable it.
+
+You can also `use the module`__ on your own project very easily:
+
+    .. code-block:: python
+
+        import logging
+        logger = logging.getLogger(__name__)
+
+        logger.debug('Debug messages')
+        logger.info('Useful information')
+        logger.warning('This is a warning!')
+
+
+If you want to enable ``logging`` for your project *but* use a different
+log level for the library:
+
+    .. code-block:: python
+
+        import logging
+        logging.basicConfig(level=logging.DEBUG)
+        # For instance, show only warnings and above
+        logging.getLogger('telethon').setLevel(level=logging.WARNING)
+
+
+__ https://docs.python.org/3/library/logging.html
+__ https://docs.python.org/3/howto/logging.html#configuring-logging-for-a-library
+__ https://docs.python.org/3/howto/logging.html

readthedocs/extra/troubleshooting/rpc-errors.rst

@@ -0,0 +1,29 @@
+==========
+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). All the errors are
+available in :ref:`telethon-errors-package`, but some examples are:
+
+-  ``FloodWaitError`` (420), the same request was repeated many times.
+   Must wait ``.seconds`` (you can access this parameter).
+-  ``SessionPasswordNeededError``, if you have setup two-steps
+   verification on Telegram.
+-  ``CdnFileTamperedError``, if the media you were trying to download
+   from a CDN has been altered.
+-  ``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``.

readthedocs/extra/wall-of-shame.rst

@@ -0,0 +1,63 @@
+=============
+Wall of Shame
+=============
+
+
+This project has an
+`issues <https://github.com/LonamiWebs/Telethon/issues>`__ section for
+you to file **issues** whenever you encounter any when working with the
+library. Said section is **not** for issues on *your* program but rather
+issues with Telethon itself.
+
+If you have not made the effort to 1. read through the docs and 2.
+`look for the method you need <https://lonamiwebs.github.io/Telethon/>`__,
+you will end up on the `Wall of
+Shame <https://github.com/LonamiWebs/Telethon/issues?q=is%3Aissue+label%3ARTFM+is%3Aclosed>`__,
+i.e. all issues labeled
+`"RTFM" <http://www.urbandictionary.com/define.php?term=RTFM>`__:
+
+       **rtfm**
+       Literally "Read The F--king Manual"; a term showing the
+       frustration of being bothered with questions so trivial that the asker
+       could have quickly figured out the answer on their own with minimal
+       effort, usually by reading readily-available documents. People who
+       say"RTFM!" might be considered rude, but the true rude ones are the
+       annoying people who take absolutely no self-responibility and expect to
+       have all the answers handed to them personally.
+
+       *"Damn, that's the twelveth time that somebody posted this question
+       to the messageboard today! RTFM, already!"*
+
+       *by Bill M. July 27, 2004*
+
+If you have indeed read the docs, and have tried looking for the method,
+and yet you didn't find what you need, **that's fine**. Telegram's API
+can have some obscure names at times, and for this reason, there is a
+`"question"
+label <https://github.com/LonamiWebs/Telethon/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aclosed%20label%3Aquestion%20>`__
+with questions that are okay to ask. Just state what you've tried so
+that we know you've made an effort, or you'll go to the Wall of Shame.
+
+Of course, if the issue you're going to open is not even a question but
+a real issue with the library (thankfully, most of the issues have been
+that!), you won't end up here. Don't worry.
+
+Current winner
+--------------
+
+The current winner is `issue
+213 <https://github.com/LonamiWebs/Telethon/issues/213>`__:
+
+**Issue:**
+
+    .. figure:: https://user-images.githubusercontent.com/6297805/29822978-9a9a6ef0-8ccd-11e7-9ec5-934ea0f57681.jpg
+       :alt: Winner issue
+
+       Winner issue
+
+**Answer:**
+
+    .. figure:: https://user-images.githubusercontent.com/6297805/29822983-9d523402-8ccd-11e7-9fb1-5783740ee366.jpg
+       :alt: Winner issue answer
+
+       Winner issue answer

readthedocs/index.rst

@@ -1,32 +1,41 @@
-========================
-Telethon's Documentation
-========================
+.. Telethon documentation master file, created by
+   sphinx-quickstart on Fri Nov 17 15:36:11 2017.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
 
-.. 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()
+====================================
+Welcome to Telethon's documentation!
+====================================
 
 
-* 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/.
+Pure Python 3 Telegram client library.
+Official Site `here <https://lonamiwebs.github.io/Telethon>`_.
+Please follow the links on the index below to navigate from here,
+or use the menu on the left. Remember to read the :ref:`changelog`
+when you upgrade!
+
+.. important::
+   If you're new here, you want to read :ref:`getting-started`. If you're
+   looking for the method reference, you should check :ref:`telethon-package`.
+
+   The mentioned :ref:`telethon-package` is an important section and it
+   contains the friendly methods that **you should use** most of the time.
+
+
+.. note::
+
+    We assume that you have some experience working with ``asyncio``,
+    if you don't you should probably use the threaded version of the
+    library, or either learn how to use ``asyncio``. All the code
+    here assumes you're writing the code inside an ``async def`` so
+    we can use ``await`` across the examples.
+
+    Then you can ``import asyncio`` and run
+    ``asyncio.get_event_loop().run_until_complete(my_method())``
 
 
 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
@@ -34,86 +43,90 @@ 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.
+.. _installation-and-usage:
 
 .. toctree::
-    :hidden:
-    :caption: First Steps
+   :maxdepth: 2
+   :caption: Installation and Simple Usage
 
-    basic/installation
-    basic/signing-in
-    basic/quick-start
-    basic/updates
-    basic/next-steps
+   extra/basic/getting-started
+   extra/basic/installation
+   extra/basic/creating-a-client
+   extra/basic/telegram-client
+   extra/basic/entities
+   extra/basic/working-with-updates
+
+
+.. _Advanced-usage:
 
 .. toctree::
-    :hidden:
-    :caption: Quick References
+   :maxdepth: 2
+   :caption: Advanced Usage
 
-    quick-references/faq
-    quick-references/client-reference
-    quick-references/events-reference
-    quick-references/objects-reference
+   extra/advanced-usage/accessing-the-full-api
+   extra/advanced-usage/sessions
+   extra/advanced-usage/update-modes
+
+
+.. _Examples:
 
 .. toctree::
-    :hidden:
-    :caption: Concepts
+   :maxdepth: 2
+   :caption: Examples
 
-    concepts/strings
-    concepts/entities
-    concepts/chats-vs-channels
-    concepts/updates
-    concepts/sessions
-    concepts/full-api
-    concepts/errors
-    concepts/botapi-vs-mtproto
-    concepts/asyncio
+   extra/examples/working-with-messages
+   extra/examples/chats-and-channels
+   extra/examples/users
+   extra/examples/bots
+   extra/examples/projects-using-telethon
+
+
+.. _Troubleshooting:
 
 .. toctree::
-    :hidden:
-    :caption: Full API Examples
+   :maxdepth: 2
+   :caption: Troubleshooting
 
-    examples/word-of-warning
-    examples/chats-and-channels
-    examples/users
-    examples/working-with-messages
+   extra/troubleshooting/enable-logging
+   extra/troubleshooting/deleted-limited-or-deactivated-accounts
+   extra/troubleshooting/rpc-errors
+
+
+.. _Developing:
 
 .. toctree::
-    :hidden:
-    :caption: Developing
+   :maxdepth: 2
+   :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
+   extra/developing/philosophy.rst
+   extra/developing/api-status.rst
+   extra/developing/test-servers.rst
+   extra/developing/project-structure.rst
+   extra/developing/coding-style.rst
+   extra/developing/understanding-the-type-language.rst
+   extra/developing/tips-for-porting-the-project.rst
+   extra/developing/telegram-api-in-other-languages.rst
+
+
+.. _More:
 
 .. toctree::
-    :hidden:
-    :caption: Miscellaneous
+   :maxdepth: 2
+   :caption: More
+
+   extra/changelog
+   extra/wall-of-shame.rst
 
-    misc/changelog
-    misc/compatibility-and-convenience
 
 .. toctree::
-    :hidden:
-    :caption: Telethon Modules
+   :caption: Telethon modules
 
-    modules/client
-    modules/events
-    modules/custom
-    modules/utils
-    modules/errors
-    modules/sessions
-    modules/network
-    modules/helpers
+   modules
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

readthedocs/misc/compatibility-and-convenience.rst

@@ -1,185 +0,0 @@
-.. _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.rst

@@ -0,0 +1,7 @@
+telethon
+========
+
+.. toctree::
+   :maxdepth: 3
+
+   telethon

readthedocs/modules/client.rst

@@ -1,103 +0,0 @@
-.. _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

@@ -1,163 +0,0 @@
-==============
-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

@@ -1,20 +0,0 @@
-.. _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/helpers.rst

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

readthedocs/modules/network.rst

@@ -1,33 +0,0 @@
-.. _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

@@ -1,27 +0,0 @@
-.. _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

@@ -1,12 +0,0 @@
-.. _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

@@ -1,202 +0,0 @@
-.. _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

@@ -1,247 +0,0 @@
-================
-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

@@ -1,423 +0,0 @@
-.. _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

@@ -1,353 +0,0 @@
-=================
-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

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

readthedocs/telethon.crypto.rst

@@ -0,0 +1,53 @@
+telethon\.crypto package
+========================
+
+
+telethon\.crypto\.aes module
+----------------------------
+
+.. automodule:: telethon.crypto.aes
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+telethon\.crypto\.aes\_ctr module
+---------------------------------
+
+.. automodule:: telethon.crypto.aes_ctr
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+telethon\.crypto\.auth\_key module
+----------------------------------
+
+.. automodule:: telethon.crypto.auth_key
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+telethon\.crypto\.cdn\_decrypter module
+---------------------------------------
+
+.. automodule:: telethon.crypto.cdn_decrypter
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+telethon\.crypto\.factorization module
+--------------------------------------
+
+.. automodule:: telethon.crypto.factorization
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+telethon\.crypto\.rsa module
+----------------------------
+
+.. automodule:: telethon.crypto.rsa
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+

readthedocs/telethon.errors.rst

@@ -0,0 +1,24 @@
+.. _telethon-errors-package:
+
+
+telethon\.errors package
+========================
+
+
+telethon\.errors\.common module
+-------------------------------
+
+.. automodule:: telethon.errors.common
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+telethon\.errors\.rpc\_base\_errors module
+------------------------------------------
+
+.. automodule:: telethon.errors.rpc_base_errors
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+

readthedocs/telethon.events.rst

@@ -1,12 +1,9 @@
-.. _telethon-events:
+.. _telethon-events-package:
 
-=============
-Update Events
-=============
+telethon\.events package
+========================
 
-.. currentmodule:: telethon.events
-
-Every event (builder) subclasses `common.EventBuilder`,
+Every event (builder) subclasses `telethon.events.common.EventBuilder`,
 so all the methods in it can be used from any event builder/event instance.
 
 .. automodule:: telethon.events.common
@@ -14,57 +11,51 @@ so all the methods in it can be used from any event builder/event instance.
     :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/telethon.extensions.rst

@@ -0,0 +1,29 @@
+telethon\.extensions package
+============================
+
+
+telethon\.extensions\.binary\_reader module
+-------------------------------------------
+
+.. automodule:: telethon.extensions.binary_reader
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+telethon\.extensions\.markdown module
+-------------------------------------
+
+.. automodule:: telethon.extensions.markdown
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+telethon\.extensions\.tcp\_client module
+----------------------------------------
+
+.. automodule:: telethon.extensions.tcp_client
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+

readthedocs/telethon.network.rst

@@ -0,0 +1,37 @@
+telethon\.network package
+=========================
+
+
+telethon\.network\.authenticator module
+---------------------------------------
+
+.. automodule:: telethon.network.authenticator
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+telethon\.network\.connection module
+------------------------------------
+
+.. automodule:: telethon.network.connection
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+telethon\.network\.mtproto\_plain\_sender module
+------------------------------------------------
+
+.. automodule:: telethon.network.mtproto_plain_sender
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+telethon\.network\.mtproto\_sender module
+-----------------------------------------
+
+.. automodule:: telethon.network.mtproto_sender
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+

readthedocs/telethon.rst

@@ -0,0 +1,107 @@
+.. _telethon-package:
+
+
+telethon package
+================
+
+
+telethon\.telegram\_client module
+---------------------------------
+
+.. automodule:: telethon.telegram_client
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+telethon\.telegram\_bare\_client module
+---------------------------------------
+
+.. automodule:: telethon.telegram_bare_client
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+telethon\.utils module
+----------------------
+
+.. automodule:: telethon.utils
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+telethon\.helpers module
+------------------------
+
+.. automodule:: telethon.helpers
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+telethon\.events package
+------------------------
+
+.. toctree::
+
+    telethon.events
+
+
+telethon\.update\_state module
+------------------------------
+
+.. automodule:: telethon.update_state
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+telethon\.sessions module
+-------------------------
+
+.. automodule:: telethon.sessions
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+telethon\.cryto package
+------------------------
+
+.. toctree::
+
+    telethon.crypto
+
+telethon\.errors package
+------------------------
+
+.. toctree::
+
+    telethon.errors
+
+telethon\.extensions package
+----------------------------
+
+.. toctree::
+
+    telethon.extensions
+
+telethon\.network package
+-------------------------
+
+.. toctree::
+
+    telethon.network
+
+telethon\.tl package
+--------------------
+
+.. toctree::
+
+    telethon.tl
+
+
+
+Module contents
+---------------
+
+.. automodule:: telethon
+    :members:
+    :undoc-members:
+    :show-inheritance:

readthedocs/telethon.tl.custom.rst

@@ -0,0 +1,21 @@
+telethon\.tl\.custom package
+============================
+
+
+telethon\.tl\.custom\.draft module
+----------------------------------
+
+.. automodule:: telethon.tl.custom.draft
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+
+telethon\.tl\.custom\.dialog module
+-----------------------------------
+
+.. automodule:: telethon.tl.custom.dialog
+    :members:
+    :undoc-members:
+    :show-inheritance:

readthedocs/telethon.tl.rst

@@ -0,0 +1,41 @@
+telethon\.tl package
+====================
+
+
+.. toctree::
+
+    telethon.tl.custom
+
+
+telethon\.tl\.gzip\_packed module
+---------------------------------
+
+.. automodule:: telethon.tl.gzip_packed
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+telethon\.tl\.message\_container module
+---------------------------------------
+
+.. automodule:: telethon.tl.message_container
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+telethon\.tl\.tl\_message module
+--------------------------------
+
+.. automodule:: telethon.tl.tl_message
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+telethon\.tl\.tlobject module
+-----------------------------
+
+.. automodule:: telethon.tl.tlobject
+    :members:
+    :undoc-members:
+    :show-inheritance:
+

requirements.txt

@@ -1,2 +1,3 @@
 pyaes
 rsa
+typing

run_tests.py

@@ -0,0 +1,24 @@
+#!/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

@@ -11,79 +11,65 @@ Extra supported commands are:
 """
 
 import itertools
-import json
 import os
 import re
 import shutil
-import sys
-import urllib.request
-from pathlib import Path
-from subprocess import run
+from codecs import open
+from sys import argv, version_info
 
 from setuptools import find_packages, setup
 
-# 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, new=None):
+    def __init__(self):
         self.original = None
-        self.new = new or str(Path(__file__).parent.resolve())
 
     def __enter__(self):
-        # 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)
+        self.original = os.path.abspath(os.path.curdir)
+        os.chdir(os.path.abspath(os.path.dirname(__file__)))
         return self
 
     def __exit__(self, *args):
         os.chdir(self.original)
 
 
-API_REF_URL = 'https://tl.telethon.dev/'
+GENERATOR_DIR = 'telethon_generator'
+LIBRARY_DIR = 'telethon'
 
-GENERATOR_DIR = Path('telethon_generator')
-LIBRARY_DIR = Path('telethon')
+ERRORS_IN_JSON = os.path.join(GENERATOR_DIR, 'data', 'errors.json')
+ERRORS_IN_DESC = os.path.join(GENERATOR_DIR, 'data', 'error_descriptions')
+ERRORS_OUT = os.path.join(LIBRARY_DIR, 'errors', 'rpc_error_list.py')
 
-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'
+TLOBJECT_IN_CORE_TL = os.path.join(GENERATOR_DIR, 'data', 'mtproto_api.tl')
+TLOBJECT_IN_TL = os.path.join(GENERATOR_DIR, 'data', 'telegram_api.tl')
+TLOBJECT_OUT = os.path.join(LIBRARY_DIR, 'tl')
 IMPORT_DEPTH = 2
 
-DOCS_IN_RES = GENERATOR_DIR / 'data/html'
-DOCS_OUT = Path('docs')
+DOCS_IN_RES = os.path.join(GENERATOR_DIR, 'data', 'html')
+DOCS_OUT = 'docs'
 
 
-def generate(which, action='gen'):
-    from telethon_generator.parsers import\
-        parse_errors, parse_methods, parse_tl, find_layer
-
+def generate(which):
+    from telethon_generator.parsers import parse_errors, parse_tl, find_layer
     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)))
+    layer = find_layer(TLOBJECT_IN_TL)
+    errors = list(parse_errors(ERRORS_IN_JSON, ERRORS_IN_DESC))
+    tlobjects = list(itertools.chain(
+        parse_tl(TLOBJECT_IN_CORE_TL, layer=layer),
+        parse_tl(TLOBJECT_IN_TL, layer=layer)))
 
     if not which:
         which.extend(('tl', 'errors'))
 
-    clean = action == 'clean'
+    clean = 'clean' in which
     action = 'Cleaning' if clean else 'Generating'
+    if clean:
+        which.remove('clean')
 
     if 'all' in which:
         which.remove('all')
@@ -103,121 +89,76 @@ def generate(which, action='gen'):
         which.remove('errors')
         print(action, 'RPCErrors...')
         if clean:
-            if ERRORS_OUT.is_file():
-                ERRORS_OUT.unlink()
+            if os.path.isfile(ERRORS_OUT):
+                os.remove(ERRORS_OUT)
         else:
-            with ERRORS_OUT.open('w') as file:
+            with open(ERRORS_OUT, 'w', encoding='utf-8') 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))
+            if os.path.isdir(DOCS_OUT):
+                shutil.rmtree(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)
+            generate_docs(tlobjects, errors, layer, DOCS_IN_RES, DOCS_OUT)
 
     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".'
-        )
+        print('The following items were not understood:', which)
+        print('  Consider using only "tl", "errors" and/or "docs".')
+        print('  Using only "clean" will clean them. "all" to act on all.')
+        print('  For instance "gen tl errors".')
 
 
-def main(argv):
-    if len(argv) >= 2 and argv[1] in ('gen', 'clean'):
-        generate(argv[2:], argv[1])
+def main():
+    if len(argv) >= 2 and argv[1] == 'gen':
+        generate(argv[2:])
 
     elif len(argv) >= 2 and argv[1] == 'pypi':
-        # 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:
+        except:
             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)
+        # 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
 
+        for x in ('build', 'dist', 'Telethon_aio.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'):
-            shutil.rmtree(x, ignore_errors=True)
+        for x in ('build', 'dist', 'Telethon_aio.egg-info'):
+            rmtree(x, ignore_errors=True)
 
     else:
         # e.g. install from GitHub
-        if GENERATOR_DIR.is_dir():
+        if os.path.isdir(GENERATOR_DIR):
             generate(['tl', 'errors'])
 
         # Get the long description from the README file
-        with open('README.rst', 'r', encoding='utf-8') as f:
+        with open('README.rst', encoding='utf-8') as f:
             long_description = f.read()
 
-        with open('telethon/version.py', 'r', encoding='utf-8') as f:
+        with open('telethon/version.py', encoding='utf-8') as f:
             version = re.search(r"^__version__\s*=\s*'(.*)'.*$",
                                 f.read(), flags=re.MULTILINE).group(1)
         setup(
-            name='Telethon',
+            name='Telethon-aio',
             version=version,
-            description="Full-featured Telegram client library for Python 3",
+            description="Full-featured Telegram client library for Python 3, "
+                        "modified to work under Python's asyncio module.",
             long_description=long_description,
 
-            url='https://github.com/LonamiWebs/Telethon',
+            url='https://github.com/LonamiWebs/Telethon/tree/asyncio',
             download_url='https://github.com/LonamiWebs/Telethon/releases',
 
             author='Lonami Exo',
@@ -228,14 +169,14 @@ def main(argv):
             # 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',
+            python_requires='>=3.4',
 
             # See https://pypi.python.org/pypi?%3Aaction=list_classifiers
             classifiers=[
                 #   3 - Alpha
                 #   4 - Beta
                 #   5 - Production/Stable
-                'Development Status :: 5 - Production/Stable',
+                'Development Status :: 3 - Alpha',
 
                 'Intended Audience :: Developers',
                 'Topic :: Communications :: Chat',
@@ -243,16 +184,22 @@ def main(argv):
                 'License :: OSI Approved :: MIT License',
 
                 'Programming Language :: Python :: 3',
+                'Programming Language :: Python :: 3.4',
                 'Programming Language :: Python :: 3.5',
-                'Programming Language :: Python :: 3.6',
-                'Programming Language :: Python :: 3.7',
-                'Programming Language :: Python :: 3.8',
+                'Programming Language :: Python :: 3.6'
             ],
             keywords='telegram api chat client library messaging mtproto',
             packages=find_packages(exclude=[
-                'telethon_*', 'tests*'
+                'telethon_generator', 'telethon_tests', 'run_tests.py',
+                'try_telethon.py',
+                'telethon_generator/parser/__init__.py',
+                'telethon_generator/parser/source_builder.py',
+                'telethon_generator/parser/tl_object.py',
+                'telethon_generator/parser/tl_parser.py',
             ]),
-            install_requires=['pyaes', 'rsa'],
+            # We must be careful not to miss any comma here... v
+            install_requires=['pyaes', 'rsa', 'async_generator',
+                              'typing' if version_info < (3, 5, 2) else ""],
             extras_require={
                 'cryptg': ['cryptg']
             }
@@ -260,5 +207,5 @@ def main(argv):
 
 
 if __name__ == '__main__':
-    with TempWorkDir():
-        main(sys.argv)
+    with TempWorkDir():  # Could just use a try/finally but this is + reusable
+        main()

telethon/__init__.py

@@ -1,13 +1,9 @@
-from .client.telegramclient import TelegramClient
+import logging
+from .telegram_bare_client import TelegramBareClient
+from .telegram_client 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
+from . import tl, version
+
 
 __version__ = version.__version__
-
-__all__ = [
-    'TelegramClient', 'Button',
-    'types', 'functions', 'custom', 'errors',
-    'events', 'utils', 'connection'
-]
+logging.getLogger(__name__).addHandler(logging.NullHandler())

telethon/_updates/__init__.py

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

telethon/_updates/entitycache.py

@@ -1,59 +0,0 @@
-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

@@ -1,825 +0,0 @@
-"""
-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

@@ -1,195 +0,0 @@
-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__})