Merge branch 'master' into asyncio

.gitignore

@@ -1,5 +1,6 @@
 # Docs
 _build/
+docs/
 
 # Generated code
 telethon/tl/functions/

readthedocs/extra/advanced-usage/accessing-the-full-api.rst

@@ -137,4 +137,4 @@ This can further be simplified to:
 
 __ https://lonamiwebs.github.io/Telethon
 __ https://lonamiwebs.github.io/Telethon/methods/index.html
-__ https://lonamiwebs.github.io/Telethon/?q=message
+__ https://lonamiwebs.github.io/Telethon/?q=message&redirect=no

readthedocs/extra/basic/entities.rst

@@ -26,6 +26,12 @@ in response to certain methods, such as :tl:`GetUsersRequest`.
     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
 ****************
@@ -124,3 +130,21 @@ library, the raw requests you make to the API are also able to call
 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/installation.rst

@@ -54,7 +54,7 @@ Manual Installation
 
 3. Enter the cloned repository: ``cd Telethon``
 
-4. Run the code generator: ``python3 setup.py gen_tl``
+4. Run the code generator: ``python3 setup.py gen tl errors``
 
 5. Done!
 

readthedocs/extra/changelog.rst

@@ -14,6 +14,70 @@ it can take advantage of new goodies!
 .. contents:: List of All Versions
 
 
+Pickle-able objects (v0.18.3)
+=============================
+
+*Published at 2018/04/15*
+
+
+Now you can use Python's ``pickle`` module to serialize ``RPCError`` and
+any other ``TLObject`` thanks to **@vegeta1k95**! A fix that was fairly
+simple, but still might be useful for many people.
+
+As a side note, the documentation at https://lonamiwebs.github.io/Telethon
+now lists known ``RPCError`` for all requests, so you know what to expect.
+This required a major rewrite, but it was well worth it!
+
+Breaking changes
+~~~~~~~~~~~~~~~~
+
+- `telethon.telegram_client.TelegramClient.forward_messages` now returns
+  a single item instead of a list if the input was also a single item.
+
+Additions
+~~~~~~~~~
+
+- New `telethon.events.messageread.MessageRead` event, to find out when
+  and who read which messages as soon as it happens.
+- Now you can access ``.chat_id`` on all events and ``.sender_id`` on some.
+
+Bug fixes
+~~~~~~~~~
+
+- Possibly fix some bug regarding lost ``GzipPacked`` requests.
+- The library now uses the "real" layer 75, hopefully.
+- Fixed ``.entities`` name collision on updates by making it private.
+- ``AUTH_KEY_DUPLICATED`` is handled automatically on connection.
+- Markdown parser's offset uses ``match.start()`` to allow custom regex.
+- Some filter types (as a type) were not supported by
+  `telethon.telegram_client.TelegramClient.iter_participants`.
+- `telethon.telegram_client.TelegramClient.remove_event_handler` works.
+- `telethon.telegram_client.TelegramClient.start` works on all terminals.
+- :tl:`InputPeerSelf` case was missing from
+  `telethon.telegram_client.TelegramClient.get_input_entity`.
+
+Enhancements
+~~~~~~~~~~~~
+
+- The ``parse_mode`` for messages now accepts a callable.
+- `telethon.telegram_client.TelegramClient.download_media` accepts web previews.
+- `telethon.tl.custom.dialog.Dialog` instances can now be casted into
+  :tl:`InputPeer`.
+- Better logging when reading packages "breaks".
+- Better and more powerful ``setup.py gen`` command.
+
+Internal changes
+~~~~~~~~~~~~~~~~
+
+- The library won't call ``.get_dialogs()`` on entity not found. Instead,
+  it will ``raise ValueError()`` so you can properly ``except`` it.
+- Several new examples and updated documentation.
+- ``py:obj`` is the default Sphinx's role which simplifies ``.rst`` files.
+- ``setup.py`` now makes use of ``python_requires``.
+- Events now live in separate files.
+- Other minor changes.
+
+
 Several bug fixes (v0.18.2)
 ===========================
 

readthedocs/extra/developing/project-structure.rst

@@ -37,7 +37,11 @@ Auto-generated code
 *******************
 
 The files under ``telethon_generator/`` are used to generate the code
-that gets placed under ``telethon/tl/``. The ``TLGenerator`` takes in a
-``.tl`` file, and spits 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.
+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/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(functions.photos.UploadProfilePhotoRequest(
+            await client.upload_file('/path/to/some/file')
+        ))

readthedocs/index.rst

@@ -73,6 +73,7 @@ heavy job for you, so you can focus on developing an application.
 
    extra/examples/working-with-messages
    extra/examples/chats-and-channels
+   extra/examples/users
    extra/examples/bots
    extra/examples/projects-using-telethon
 

readthedocs/telethon.events.rst

@@ -3,12 +3,6 @@
 telethon\.events package
 ========================
 
-.. automodule:: telethon.events
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
-
 Every event (builder) subclasses `telethon.events.common.EventBuilder`,
 so all the methods in it can be used from any event builder/event instance.
 
@@ -18,8 +12,6 @@ so all the methods in it can be used from any event builder/event instance.
     :show-inheritance:
 
 
-Below all the event types are listed:
-
 .. automodule:: telethon.events.newmessage
     :members:
     :undoc-members:
@@ -54,3 +46,9 @@ Below all the event types are listed:
     :members:
     :undoc-members:
     :show-inheritance:
+
+.. automodule:: telethon.events
+    :members:
+    :undoc-members:
+    :show-inheritance:
+