add readthedocs files

readthedocs/extra/examples-signing-in.rst

@@ -0,0 +1,54 @@
+=========================
+Signing In
+=========================
+
+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
+
+        client.sign_in(phone)
+        try:
+            client.sign_in(code=input('Enter code: '))
+        except SessionPasswordNeededError:
+            client.sign_in(password=getpass.getpass())
+
+Enabling 2FA
+*************
+
+If you don't have 2FA enabled, but you would like to do so through Telethon, take as example the following code snippet:
+
+    .. code-block:: python
+
+        import os
+        from hashlib import sha256
+        from telethon.tl.functions import account
+        from telethon.tl.types.account import PasswordInputSettings
+
+        new_salt = client(account.GetPasswordRequest()).new_salt
+        salt = new_salt + os.urandom(8)  # new random salt
+
+        pw = 'secret'.encode('utf-8')  # type your new password here
+        hint = 'hint'
+
+        pw_salted = salt + pw + salt
+        pw_hash = sha256(pw_salted).digest()
+
+        result = client(account.UpdatePasswordSettingsRequest(
+            current_password_hash=salt,
+            new_settings=PasswordInputSettings(
+                new_salt=salt,
+                new_password_hash=pw_hash,
+                hint=hint
+            )
+        ))
+
+Thanks to `Issue 259 <https://github.com/LonamiWebs/Telethon/issues/259>`_ for the tip!
+

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

@@ -0,0 +1,99 @@
+=========================
+Working with messages
+=========================
+
+Forwarding messages
+*******************
+
+Note that ForwardMessageRequest_ (note it's Message, singular) will *not* work if channels are involved.
+This is because channel (and megagroups) IDs are not unique, so you also need to know who the sender is
+(a parameter this request doesn't have).
+
+Either way, you are encouraged to use ForwardMessagesRequest_ (note it's Message*s*, plural) *always*,
+since it is more powerful, as follows:
+
+    .. code-block:: python
+
+        from telethon.tl.functions.messages import ForwardMessagesRequest
+        #                                             note the s ^
+
+        messages = foo()  # retrieve a few messages (or even one, in a list)
+        from_entity = bar()
+        to_entity = baz()
+
+        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
+*******************
+
+Messages are searched through the obvious SearchRequest_, but you may run into issues_. A valid example would be:
+
+    .. code-block:: python
+
+        result = client(SearchRequest(
+            entity, 'query', InputMessagesFilterEmpty(), None, None, 0, 0, 100
+        ))
+
+It's important to note that the optional parameter ``from_id`` has been left omitted and thus defaults to ``None``.
+Changing it to 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 = client(GetAllStickersRequest(0))
+
+        # Choose a sticker set
+        sticker_set = sticker_sets.sets[0]
+
+        # Get the stickers for this sticker set
+        stickers = client(GetStickerSetRequest(
+            stickerset=InputStickerSetID(
+                id=sticker_set.id, access_hash=sticker_set.access_hash
+            )
+        ))
+
+        # Stickers are nothing more than files, so send that
+        client(SendMediaRequest(
+            peer=client.get_me(),
+            media=InputMediaDocument(
+                id=InputDocument(
+                    id=stickers.documents[0].id,
+                    access_hash=stickers.documents[0].access_hash
+                ),
+                caption=''
+            )
+        ))
+
+
+.. _ForwardMessageRequest: https://lonamiwebs.github.io/Telethon/methods/messages/forward_message.html
+.. _ForwardMessagesRequest: https://lonamiwebs.github.io/Telethon/methods/messages/forward_messages.html
+.. _SearchRequest: https://lonamiwebs.github.io/Telethon/methods/messages/search.html
+.. _issues: https://github.com/LonamiWebs/Telethon/issues/215
+.. _InputUserEmpty: https://lonamiwebs.github.io/Telethon/constructors/input_user_empty.html

readthedocs/extra/examples.rst

@@ -0,0 +1,66 @@
+
+
+*****************
+Examples
+*****************
+
+Prelude
+---------
+
+Before reading any specific example, make sure to read the following common steps:
+
+All the examples assume that you have successfully created a client and you're authorized as follows:
+
+    .. code-block:: python
+
+        from telethon import TelegramClient
+
+        # Use your own values here
+        api_id = 12345
+        api_hash = '0123456789abcdef0123456789abcdef'
+        phone_number = '+34600000000'
+
+        client = TelegramClient('some_name', api_id, api_hash)
+        client.connect()  # Must return True, otherwise, try again
+
+        if not client.is_user_authorized():
+            client.send_code_request(phone_number)
+            # .sign_in() may raise PhoneNumberUnoccupiedError
+            # In that case, you need to call .sign_up() to get a new account
+            client.sign_in(phone_number, input('Enter code: '))
+
+        # The `client´ is now ready
+
+Although Python will probably clean up the resources used by the ``TelegramClient``,
+you should always ``.disconnect()`` it once you're done:
+
+    .. code-block:: python
+
+        try:
+            # Code using the client goes here
+        except:
+            # No matter what happens, always disconnect in the end
+            client.disconnect()
+
+If the examples aren't enough, you're strongly advised to read the source code
+for the InteractiveTelegramClient_ for an overview on how you could build your next script.
+This example shows a basic usage more than enough in most cases. Even reading the source
+for the TelegramClient_ may help a lot!
+
+
+Signing In
+--------------
+
+.. toctree::
+    examples-signing-in
+
+
+Working with messages
+-----------------------
+
+.. toctree::
+    examples-working-with-messages
+
+
+.. _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/getting_started.rst

@@ -0,0 +1,103 @@
+.. 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.
+
+
+=================
+Getting Started!
+=================
+
+Installation
+**************
+
+To install Telethon, simply do:
+
+    ``pip install telethon``
+
+If you get something like ``"SyntaxError: invalid syntax"`` or any other error while installing, it's probably because ``pip`` defaults to Python 2, which is not supported. Use ``pip3`` instead.
+
+If you already have the library installed, upgrade with:
+
+    ``pip install --upgrade telethon``.
+
+You can also install the library directly from GitHub or a fork:
+
+   .. code-block:: python
+
+        # pip 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.
+
+
+
+
+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 be changed later as far as I'm aware.
+
+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
+
+       # These example values won't work. You must get your own api_id and
+       # api_hash from https://my.telegram.org, under API Development.
+       api_id = 12345
+       api_hash = '0123456789abcdef0123456789abcdef'
+       phone = '+34600000000'
+
+       client = TelegramClient('session_name', api_id, api_hash)
+       client.connect()
+
+       # If you already have a previous 'session_name.session' file, skip this.
+       client.sign_in(phone=phone)
+       me = client.sign_in(code=77777)  # Put whatever code you received here.
+
+**More details**: `Click here <https://github.com/lonamiwebs/telethon/wiki/Creating-a-Client>`_
+
+
+Simple Stuff
+**************
+   .. code-block:: python
+
+       print(me.stringify())
+
+       client.send_message('username', 'Hello! Talking to you from Telethon')
+       client.send_file('username', '/home/myself/Pictures/holidays.jpg')
+
+       client.download_profile_photo(me)
+       total, messages, senders = client.get_message_history('username')
+       client.download_media(messages[0])
+
+
+Diving In
+**************
+
+.. note:: More info in our Wiki!
+
+Sending Requests
+^^^^^^^^^^^^^^^^^^^^^
+    `Here <https://github.com/lonamiwebs/telethon/wiki/Session-Files>`__
+
+Working with updates
+^^^^^^^^^^^^^^^^^^^^^
+    `Here <https://github.com/lonamiwebs/telethon/wiki/Working-with-Updates>`__
+
+Accessing the full API
+^^^^^^^^^^^^^^^^^^^^^^^
+    `Here <https://github.com/lonamiwebs/telethon/wiki/Accessing-the-Full-API>`__
+