Clean up and complete RTD documentation

readthedocs/extra/developing/api-status.rst

@@ -0,0 +1,54 @@
+==========
+API Status
+==========
+
+
+In an attempt to help everyone who works with the Telegram API, the
+library will by default report all *Remote Procedure Call* errors to
+`RPC PWRTelegram <https://rpc.pwrtelegram.xyz/>`__, a public database
+anyone can query, made by `Daniil <https://github.com/danog>`__. All the
+information sent is a ``GET`` request with the error code, error message
+and method used.
+
+If you still would like to opt out, simply set
+``client.session.report_errors = False`` to disable this feature, or
+pass ``report_errors=False`` as a named parameter when creating a
+``TelegramClient`` instance. However Daniil would really thank you if
+you helped him (and everyone) by keeping it on!
+
+Querying the API status
+***********************
+
+The API is accessed through ``GET`` requests, which can be made for
+instance through ``curl``. A JSON response will be returned.
+
+**All known errors and their description**:
+
+.. code:: bash
+
+    curl https://rpc.pwrtelegram.xyz/?all
+
+**Error codes for a specific request**:
+
+.. code:: bash
+
+    curl https://rpc.pwrtelegram.xyz/?for=messages.sendMessage
+
+**Number of ``RPC_CALL_FAIL``\ 's**:
+
+.. code:: bash
+
+    curl https://rpc.pwrtelegram.xyz/?rip  # last hour
+    curl https://rpc.pwrtelegram.xyz/?rip=$(time()-60)  # last minute
+
+**Description of errors**:
+
+.. code:: bash
+
+    curl https://rpc.pwrtelegram.xyz/?description_for=SESSION_REVOKED
+
+**Code of a specific error**:
+
+.. code:: bash
+
+    curl https://rpc.pwrtelegram.xyz/?code_for=STICKERSET_INVALID

readthedocs/extra/developing/coding-style.rst

@@ -0,0 +1,22 @@
+============
+Coding Style
+============
+
+
+Basically, make it **readable**, while keeping the style similar to the
+code of whatever file you're working on.
+
+Also note that not everyone has 4K screens for their primary monitors,
+so please try to stick to the 80-columns limit. This makes it easy to
+``git diff`` changes from a terminal before committing changes. If the
+line has to be long, please don't exceed 120 characters.
+
+For the commit messages, please make them *explanatory*. Not only
+they're helpful to troubleshoot when certain issues could have been
+introduced, but they're also used to construct the change log once a new
+version is ready.
+
+If you don't know enough Python, I strongly recommend reading `Dive Into
+Python 3 <http://www.diveintopython3.net/>`__, available online for
+free. For instance, remember to do ``if x is None`` or
+``if x is not None`` instead ``if x == None``!

readthedocs/extra/developing/philosophy.rst

@@ -0,0 +1,25 @@
+==========
+Philosophy
+==========
+
+
+The intention of the library is to have an existing MTProto library
+existing with hardly any dependencies (indeed, wherever Python is
+available, you can run this library).
+
+Being written in Python means that performance will be nowhere close to
+other implementations written in, for instance, Java, C++, Rust, or
+pretty much any other compiled language. However, the library turns out
+to actually be pretty decent for common operations such as sending
+messages, receiving updates, or other scripting. Uploading files may be
+notably slower, but if you would like to contribute, pull requests are
+appreciated!
+
+If ``libssl`` is available on your system, the library will make use of
+it to speed up some critical parts such as encrypting and decrypting the
+messages. Files will notably be sent and downloaded faster.
+
+The main focus is to keep everything clean and simple, for everyone to
+understand how working with MTProto and Telegram works. Don't be afraid
+to read the source, the code won't bite you! It may prove useful when
+using the library on your own use cases.

readthedocs/extra/developing/project-structure.rst

@@ -0,0 +1,43 @@
+=================
+Project Structure
+=================
+
+
+Main interface
+**************
+
+The library itself is under the ``telethon/`` directory. The
+``__init__.py`` file there exposes the main ``TelegramClient``, a class
+that servers as a nice interface with the most commonly used methods on
+Telegram such as sending messages, retrieving the message history,
+handling updates, etc.
+
+The ``TelegramClient`` inherits the ``TelegramBareClient``. The later is
+basically a pruned version of the ``TelegramClient``, which knows basic
+stuff like ``.invoke()``\ 'ing requests, downloading files, or switching
+between data centers. This is primary to keep the method count per class
+and file low and manageable.
+
+Both clients make use of the ``network/mtproto_sender.py``. The
+``MtProtoSender`` class handles packing requests with the ``salt``,
+``id``, ``sequence``, etc., and also handles how to process responses
+(i.e. pong, RPC errors). This class communicates through Telegram via
+its ``.connection`` member.
+
+The ``Connection`` class uses a ``extensions/tcp_client``, a C#-like
+``TcpClient`` to ease working with sockets in Python. All the
+``TcpClient`` know is how to connect through TCP and writing/reading
+from the socket with optional cancel.
+
+The ``Connection`` class bundles up all the connections modes and sends
+and receives the messages accordingly (TCP full, obfuscated,
+intermediate…).
+
+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.

readthedocs/extra/developing/telegram-api-in-other-languages.rst

@@ -0,0 +1,64 @@
+===============================
+Telegram API in Other Languages
+===============================
+
+
+Telethon was made for **Python**, and as far as I know, there is no
+*exact* port to other languages. However, there *are* other
+implementations made by awesome people (one needs to be awesome to
+understand the official Telegram documentation) on several languages
+(even more Python too), listed below:
+
+C
+*
+
+Possibly the most well-known unofficial open source implementation out
+there by `**@vysheng** <https://github.com/vysheng>`__,
+```tgl`` <https://github.com/vysheng/tgl>`__, and its console client
+```telegram-cli`` <https://github.com/vysheng/tg>`__. Latest development
+has been moved to `BitBucket <https://bitbucket.org/vysheng/tdcli>`__.
+
+JavaScript
+**********
+
+`**@zerobias** <https://github.com/zerobias>`__ is working on
+```telegram-mtproto`` <https://github.com/zerobias/telegram-mtproto>`__,
+a work-in-progress JavaScript library installable via
+```npm`` <https://www.npmjs.com/>`__.
+
+Kotlin
+******
+
+`Kotlogram <https://github.com/badoualy/kotlogram>`__ is a Telegram
+implementation written in Kotlin (the now
+`official <https://blog.jetbrains.com/kotlin/2017/05/kotlin-on-android-now-official/>`__
+language for
+`Android <https://developer.android.com/kotlin/index.html>`__) by
+`**@badoualy** <https://github.com/badoualy>`__, currently as a beta–
+yet working.
+
+PHP
+***
+
+A PHP implementation is also available thanks to
+`**@danog** <https://github.com/danog>`__ and his
+`MadelineProto <https://github.com/danog/MadelineProto>`__ project, with
+a very nice `online
+documentation <https://daniil.it/MadelineProto/API_docs/>`__ too.
+
+Python
+******
+
+A fairly new (as of the end of 2017) Telegram library written from the
+ground up in Python by
+`**@delivrance** <https://github.com/delivrance>`__ and his
+`Pyrogram <https://github.com/pyrogram/pyrogram>`__ library! No hard
+feelings Dan and good luck dealing with some of your users ;)
+
+Rust
+****
+
+Yet another work-in-progress implementation, this time for Rust thanks
+to `**@JuanPotato** <https://github.com/JuanPotato>`__ under the fancy
+name of `Vail <https://github.com/JuanPotato/Vail>`__. This one is very
+early still, but progress is being made at a steady rate.

readthedocs/extra/developing/test-servers.rst

@@ -0,0 +1,32 @@
+============
+Test Servers
+============
+
+
+To run Telethon on a test server, use the following code:
+
+    .. code-block:: python
+
+        client = TelegramClient(None, api_id, api_hash)
+        client.session.server_address = '149.154.167.40'
+        client.connect()
+
+You can check your ``'test ip'`` on https://my.telegram.org.
+
+You should set ``None`` session so to ensure you're generating a new
+authorization key for it (it would fail if you used a session where you
+had previously connected to another data center).
+
+Once you're connected, you'll likely need to ``.sign_up()``. Remember
+`anyone can access the phone you
+choose <https://core.telegram.org/api/datacenter#testing-redirects>`__,
+so don't store sensitive data here:
+
+    .. code-block:: python
+
+        from random import randint
+
+        dc_id = '2'  # Change this to the DC id of the test server you chose
+        phone = '99966' + dc_id + str(randint(9999)).zfill(4)
+        client.send_code_request(phone)
+        client.sign_up(dc_id * 5, 'Some', 'Name')

readthedocs/extra/developing/tips-for-porting-the-project.rst

@@ -0,0 +1,17 @@
+============================
+Tips for Porting the Project
+============================
+
+
+If you're going to use the code on this repository to guide you, please
+be kind and don't forget to mention it helped you!
+
+You should start by reading the source code on the `first
+release <https://github.com/LonamiWebs/Telethon/releases/tag/v0.1>`__ of
+the project, and start creating a ``MtProtoSender``. Once this is made,
+you should write by hand the code to authenticate on the Telegram's
+server, which are some steps required to get the key required to talk to
+them. Save it somewhere! Then, simply mimic, or reinvent other parts of
+the code, and it will be ready to go within a few days.
+
+Good luck!

readthedocs/extra/developing/understanding-the-type-language.rst

@@ -0,0 +1,35 @@
+===============================
+Understanding the Type Language
+===============================
+
+
+`Telegram's Type Language <https://core.telegram.org/mtproto/TL>`__
+(also known as TL, found on ``.tl`` files) is a concise way to define
+what other programming languages commonly call classes or structs.
+
+Every definition is written as follows for a Telegram object is defined
+as follows:
+
+.. code:: tl
+
+    name#id argument_name:argument_type = CommonType
+
+This means that in a single line you know what the ``TLObject`` name is.
+You know it's unique ID, and you know what arguments it has. It really
+isn't that hard to write a generator for generating code to any
+platform!
+
+The generated code should also be able to *encode* the ``TLObject`` (let
+this be a request or a type) into bytes, so they can be sent over the
+network. This isn't a big deal either, because you know how the
+``TLObject``\ 's are made, and how the types should be serialized.
+
+You can either write your own code generator, or use the one this
+library provides, but please be kind and keep some special mention to
+this project for helping you out.
+
+This is only a introduction. The ``TL`` language is not *that* easy. But
+it's not that hard either. You're free to sniff the
+``telethon_generator/`` files and learn how to parse other more complex
+lines, such as ``flags`` (to indicate things that may or may not be
+written at all) and ``vector``\ 's.