Telethon/client/doc/developing/project-structure.rst

Project Structure
=================

.. currentmodule:: telethon

The repository contains several folders, each with their own "package".


benches/
--------

This folder contains different benchmarks.
Pretty straightforward.


stubs/
------

If a dependency doesn't support typing, files here must work around that.


tools/
------

Various utility scripts.
Each script should have a "comment" at the top explaining what they are for.

See ``DEVELOPING.md`` in the repository root to learn how to use some of the tools.


generator/
----------

A package that should not be published and is only used when developing the library.
The implementation is private and exists under the ``src/*/_impl/`` folder.
Only select parts are exported under public modules.
Tests live under ``tests/``.

The implementation consists of a parser and a code generator.

The parser is able to read parse ``.tl`` files (:term:`Type Language` definition files).
It doesn't do anything with the files other than to represent the content as Python objects.

The code generator uses the parsed definitions to generate Python code.
Most of the code to serialize and deserialize objects lives under ``serde/``.

An in-memory "filesystem" structure is kept before writing all files to disk.
This makes it possible to execute most of the process in a sans-io manner.
Once the code generation finishes, all files are written to disk at once.

See ``DEVELOPING.md`` in the repository root to learn how to generate code.


client/
-------

The Telethon client library and documentation lives here.
This is the package that gets published.
The implementation is private and exists under the ``src/*/_impl/`` folder.
Only select parts are exported under public modules.
Tests live under ``tests/``.

The client implementation consists of several subpackages.

The ``tl`` package sits at the bottom.
It is where the generated code is placed.
It also contains some of the definitions needed for the generated code to work.
Even though all the :term:`RPC` live here, this package can't do anything by itself.

The ``crypto`` package implements all the encryption and decryption rules used by Telegram.
Details concerning the :term:`MTProto` are mostly avoided, so the package can be generally useful.

The ``mtproto`` package implements the logic required to talk to Telegram.
It is implemented in a sans-io manner.
This package is responsible for generating an authorization key and serializing packets.
It also contains some optimizations which are not strictly necessary when implementing the library.

The ``mtsender`` package simply adds IO to ``mtproto``.
It is responsible for driving the network, enqueuing requests, and waiting for results.

The ``session`` crate implements what's needed to manage the :term:`session` state.
The logic to handle and correctly order updates also lives here, in a sans-io manner.

The ``client`` ties everything together.
This is what defines the Pythonic API to interact with Telegram.
Custom object and event types also live here.

Even though only common methods are implemented, the code is still huge.
For this reason, the :class:`Client` implementation is separated from the class definition.
The class definition only contains documentation and calls functions defined in other files.
A tool under ``tools/`` exists to make it easy to keep these two in sync.

If you plan to port the library to a different language, good luck!
You will need a code generator, the ``crypto``, ``mtproto`` and ``mtsender`` packages to have an initial working version.
The tests are your friend, write them too!