Completely overhaul the documentation

readthedocs/quick-references/client-reference.rst

@@ -0,0 +1,188 @@
+.. _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 an 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
+    sign_up
+    log_out
+    edit_2fa
+
+Base
+----
+
+.. py:currentmodule:: telethon.client.telegrambaseclient.TelegramBaseClient
+
+.. autosummary::
+    :nosignatures:
+
+    connect
+    disconnect
+    is_connected
+    disconnected
+    loop
+
+Messages
+--------
+
+.. py:currentmodule:: telethon.client.messages.MessageMethods
+
+.. autosummary::
+    :nosignatures:
+
+    send_message
+    edit_message
+    delete_messages
+    forward_messages
+    iter_messages
+    get_messages
+    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
+
+Dialogs
+-------
+
+.. py:currentmodule:: telethon.client.dialogs.DialogMethods
+
+.. autosummary::
+    :nosignatures:
+
+    iter_dialogs
+    get_dialogs
+    iter_drafts
+    get_drafts
+    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
+    iter_admin_log
+    get_admin_log
+    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
+
+Bots
+----
+
+.. currentmodule:: telethon.client.bots.BotMethods
+
+.. autosummary::
+    :nosignatures:
+
+    inline_query
+
+Buttons
+-------
+
+.. currentmodule:: telethon.client.buttons.ButtonMethods
+
+.. autosummary::
+    :nosignatures:
+
+    build_reply_markup
+
+Account
+-------
+
+.. currentmodule:: telethon.client.account.AccountMethods
+
+.. autosummary::
+    :nosignatures:
+
+    takeout
+    end_takeout

readthedocs/quick-references/events-reference.rst

@@ -0,0 +1,203 @@
+================
+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).
+
+It is important to remember that **all events subclass**
+`ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>`!
+
+.. contents::
+
+
+ChatGetter
+==========
+
+All events subclass `ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>`,
+which means all events have (and you can access to):
+
+.. currentmodule:: telethon.tl.custom.chatgetter.ChatGetter
+
+.. autosummary::
+    :nosignatures:
+
+    chat
+    input_chat
+    chat_id
+    is_private
+    is_group
+    is_channel
+
+    get_chat
+    get_input_chat
+
+
+CallbackQuery
+=============
+
+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
+
+
+ChatAction
+==========
+
+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
+
+
+InlineQuery
+===========
+
+Full documentation for the `InlineQuery
+<telethon.events.inlinequery.InlineQuery>`.
+
+.. currentmodule:: telethon.events.inlinequery.InlineQuery.Event
+
+.. autosummary::
+    :nosignatures:
+
+        id
+        text
+        offset
+        geo
+        builder
+
+        answer
+
+
+MessageDeleted
+==============
+
+Full documentation for the `MessageDeleted
+<telethon.events.messagedeleted.MessageDeleted>`.
+
+It only has the ``deleted_id`` and ``deleted_ids`` attributes
+(in addition to the chat if the deletion happened in a channel).
+
+
+MessageEdited
+=============
+
+Full documentation for the `MessageEdited
+<telethon.events.messageedited.MessageEdited>`.
+
+This event is the same as `NewMessage
+<telethon.events.newmessage.NewMessage>`,
+but occurs only when an edit happens.
+
+
+MessageRead
+===========
+
+Full documentation for the `MessageRead
+<telethon.events.messageread.MessageRead>`.
+
+.. currentmodule:: telethon.events.messageread.MessageRead.Event
+
+.. autosummary::
+    :nosignatures:
+
+        inbox
+        message_ids
+
+        get_messages
+        is_read
+
+
+NewMessage
+==========
+
+Full documentation for the `NewMessage
+<telethon.events.newmessage.NewMessage>`.
+
+Note that 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.
+
+
+Raw
+===
+
+Raw events are not actual events. Instead, they are the raw
+:tl:`Update` object that Telegram sends. You normally shouldn't
+need these.
+
+
+UserUpdate
+==========
+
+Full documentation for the `UserUpdate
+<telethon.events.userupdate.UserUpdate>`.
+
+A lot of fields are attributes and not properties, so they
+are not shown here.
+
+.. currentmodule:: telethon.events.userupdate.UserUpdate.Event
+
+.. autosummary::
+    :nosignatures:
+
+        user
+        input_user
+        user_id
+
+        get_user
+        get_input_user

readthedocs/quick-references/faq.rst

@@ -0,0 +1,190 @@
+===
+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) 5s/%(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
+
+    import time
+    try:
+        client.send_message(chat, 'Hi')
+    except FloodWaitError as e:
+        print('Flood for', e.seconds)
+        time.sleep(e.seconds)
+
+
+My account was deleted/limited when using the library
+=====================================================
+
+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, 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`_.
+
+
+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 = client.get_me()
+    print(me.username)
+    #       ^ we used the dot operator to access the username attribute
+
+    result = 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()
+
+
+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/>`_.
+
+.. _logging: https://docs.python.org/3/library/logging.html
+.. _@SpamBot: https://t.me/SpamBot
+.. _issue 297: https://github.com/LonamiWebs/Telethon/issues/297

readthedocs/quick-references/objects-reference.rst

@@ -0,0 +1,259 @@
+=================
+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::
+
+
+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.
+
+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
+    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
+    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.
+
+.. 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
+
+
+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
+    text
+    request_location
+    request_phone
+    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``.
+
+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
+
+
+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