Clean up and complete RTD documentation

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

@@ -1,33 +1,41 @@
 .. _accessing-the-full-api:
 
-==========================
+======================
 Accessing the Full API
-==========================
+======================
 
-The ``TelegramClient`` doesn’t offer a method for every single request
-the Telegram API supports. However, it’s very simple to ``.invoke()``
-any request. Whenever you need something, don’t forget to `check the
+
+The ``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::
+
+    Removing the hand crafted documentation for methods is still
+    a work in progress!
+
+
 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.
+from a common type, and that's the reason for this distinction.
 
-Say ``client.send_message()`` didn’t exist, we could use the `search`__
-to look for “message”. There we would find `SendMessageRequest`__,
+Say ``client.send_message()`` didn't exist, we could use the `search`__
+to look for "message". There we would find `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:
+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:
+If you're going to use a lot of these, you may do:
 
     .. code-block:: python
     
@@ -53,20 +61,20 @@ Or we call ``.get_input_entity()``:
 
         peer = client.get_input_entity('someone')
 
-When you’re going to invoke an API method, most require you to pass an
+When you're going to invoke an API method, most require you to pass an
 ``InputUser``, ``InputChat``, or so on, this is why using
-``.get_input_entity()`` is more straightforward (and sometimes
-immediate, if you know the ID of the user for instance). If you also
-need to have information about the whole user, use ``.get_entity()``
-instead:
+``.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
+``.get_entity()`` instead:
 
     .. code-block:: python
 
         entity = 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
+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 ``.get_input_peer``:
 
     .. code-block:: python
@@ -83,10 +91,9 @@ request we do:
         result = 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:
+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
 
@@ -97,21 +104,21 @@ Remember to use the right types! To sum up:
 
 .. 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.
+    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).
+    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 as many items as possible".
-    This won't work for all of them though,
-    for instance, in "messages.search" it will actually return 0 items.
+    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
 __ https://lonamiwebs.github.io/Telethon/methods/messages/send_message.html
 __ https://lonamiwebs.github.io/Telethon/types/input_peer.html
-__ https://lonamiwebs.github.io/Telethon/constructors/input_peer_user.html
+__ https://lonamiwebs.github.io/Telethon/constructors/input_peer_user.html

readthedocs/extra/advanced-usage/sessions.rst

@@ -0,0 +1,46 @@
+.. _sessions:
+
+==============
+Session Files
+==============
+
+The first parameter you pass the 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 on the working directory.
+
+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``, or pass it as a
+parameter to the ``TelegramClient``.
+
+If you don't want to save the files as a database, you can also create
+your custom ``Session`` subclass and override the ``.save()`` and ``.load()``
+methods. For example, you could save it on a database:
+
+    .. code-block:: python
+
+        class DatabaseSession(Session):
+            def save():
+                # serialize relevant data to the database
+
+            def load():
+                # load relevant data to the database
+
+
+You should read the ````session.py```` source file to know what "relevant
+data" you need to keep track of.