Clean up and complete RTD documentation

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

@@ -1,24 +1,28 @@
 .. _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.
+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.
+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!
+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:
+This class will be your main interface with Telegram's API, and creating
+one is very simple:
 
     .. code-block:: python
 
@@ -31,14 +35,18 @@ This class will be your main interface with Telegram's API, and creating one is
 
         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 simply a JSON file which you can (but shouldn't) modify.
 
-Before using the client, you must be connected to Telegram. Doing so is very easy:
+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``.
+
+Before using the client, you must be connected to Telegram.
+Doing so is very easy:
 
     ``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:
+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``
 
@@ -52,13 +60,25 @@ If you're not authorized, you need to ``.sign_in()``:
         # If .sign_in raises SessionPasswordNeeded error, call .sign_in(password=...)
         # You can import both exceptions from telethon.errors.
 
-``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!
+``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
+
+        client = TelegramClient('anon', api_id, api_hash)
+        assert client.connect()
+        if not client.is_user_authorized():
+            client.send_code_request(phone_number)
+            me = client.sign_in(phone_number, input('Enter code: '))
+
 
 .. note::
-    If you want to use a **proxy**, you have to `install PySocks`__ (via pip or manual)
-    and then set the appropriated parameters:
+    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
 
@@ -72,5 +92,58 @@ You're now ready to use the client as you wish!
     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
+
+        client.sign_in(phone)
+        try:
+            client.sign_in(code=input('Enter code: '))
+        except SessionPasswordNeededError:
+            client.sign_in(password=getpass.getpass())
+
+
+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!
+
+
 __ https://github.com/Anorov/PySocks#installation
-__ https://github.com/Anorov/PySocks#usage-1%3E
+__ https://github.com/Anorov/PySocks#usage-1%3E