diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6296a280..46503bf8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,33 +2,32 @@ Pull requests are welcome! -Feel free to open an issue if you found a bug, have new ideas, suggestions or found a mistake -in [documentation](https://python-telegram.readthedocs.io/en/latest/). +Feel free to open an issue if you find a bug, have new ideas, suggestions, +or spot a mistake in the [documentation](https://python-telegram.readthedocs.io/en/latest/). ## Reporting bugs We use [GitHub Issues](https://github.com/alexander-akhmetov/python-telegram/issues) to track -bugs. If you found a bug, please, open a new issue. +bugs. If you find a bug, please open a new issue. -Try to include steps to reproduce and detailed description of the bug and maybe -some sample code. +Try to include steps to reproduce the bug, a detailed description, and some sample code if possible. ## Pull request process 1. Fork the repository and create a new branch from `master`. -2. Make your changes and do not forget about new tests :) +2. Make your changes and don't forget to add new tests :) 3. Ensure the tests pass with your changes. 4. Create a new PR! ## Coding style -The project uses [black](https://github.com/psf/black) as a autoformatter tool -and checker and a few linters. +The project uses [black](https://github.com/psf/black) as an autoformatter +and checker, along with a few linters. ## Tests -To run tests you have to install [tox](https://tox.readthedocs.io/en/latest/). +To run tests you need to install [tox](https://tox.readthedocs.io/en/latest/). Run tests: @@ -36,7 +35,7 @@ Run tests: tox ``` -Run a specific test using python 3.11: +Run a specific test using python 3.12: ```shell tox -e py311 -- -k test_add_message_handler diff --git a/README.md b/README.md index 8a9ea6e7..27ce2246 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,13 @@ pip install python-telegram See [documentation](http://python-telegram.readthedocs.io/en/latest/#installation) for more details. +### tdlib + +`python-telegram` comes with a precompiled `tdlib` library for Linux and MacOS. But it is highly recommended to [compile](https://tdlib.github.io/td/build.html) it yourself. +The precompiled library may not work on some systems, it is dynamically linked and requires specific versions of additional libraries. + +```shell + ### Docker This library has a [docker image](https://hub.docker.com/r/akhmetov/python-telegram/): @@ -33,9 +40,9 @@ docker run -i -t --rm \ python3 /app/examples/send_message.py $(API_ID) $(API_HASH) $(PHONE) $(CHAT_ID) $(TEXT) ``` -## How to use +## How to use the library -Have a look at the [tutorial](http://python-telegram.readthedocs.io/en/latest/tutorial.html) :) +Check out the [tutorial](http://python-telegram.readthedocs.io/en/latest/tutorial.html) for more details. Basic example: @@ -52,19 +59,20 @@ tg = Telegram( ) tg.login() -# if this is the first run, library needs to preload all chats -# otherwise the message will not be sent +# If this is the first run, the library needs to preload all chats. +# Otherwise, the message will not be sent. result = tg.get_chats() result.wait() chat_id: int result = tg.send_message(chat_id, Spoiler('Hello world!')) -# `tdlib` is asynchronous, so `python-telegram` always returns you an `AsyncResult` object. + +# `tdlib` is asynchronous, so `python-telegram` always returns an `AsyncResult` object. # You can receive a result with the `wait` method of this object. result.wait() print(result.update) -tg.stop() # you must call `stop` at the end of the script +tg.stop() # You must call `stop` at the end of the script. ``` You can also use `call_method` to call any [tdlib method](https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1_function.html): @@ -73,11 +81,11 @@ You can also use `call_method` to call any [tdlib method](https://core.telegram. tg.call_method('getUser', params={'user_id': user_id}) ``` -More examples you can find in the [/examples/ directory](/examples/). +More examples can be found in the [/examples/ directory](/examples/). --- -More information in the [documentation](http://python-telegram.readthedocs.io). +More information is available in the [documentation](http://python-telegram.readthedocs.io). ## Development diff --git a/docs/source/index.rst b/docs/source/index.rst index c9408c1d..edaa9bca 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -13,19 +13,19 @@ Welcome to python-telegram's documentation proxy changelog -Client for the `tdlib `_ library (at very early stage :) ). +Client for the `tdlib `_ library. Installation ------------ -At first you must install ``tdlib``. +First you need to install ``tdlib``. How to build tdlib ~~~~~~~~~~~~~~~~~~ `Official documentation `_ -Do not forget install it after: +After building the library, you need to install it: .. code-block:: bash @@ -35,26 +35,26 @@ Do not forget install it after: Library installation ~~~~~~~~~~~~~~~~~~~~ -This library works with Python 3.8+ only. +This library requires Python 3.8 or higher. .. code-block:: bash python3 -m pip install python-telegram -After you must `register `_ a new Telegram application. +Next, you need to `register `_ a new Telegram application. Now you can start using the library: :ref:`tutorial`. .. note:: - You can find more examples `here `_. + More examples can be found `here `_. .. note:: - The ``tdlib`` binary for Linux provided by ``python-shortcuts`` is built on Ubuntu with libc since version ``0.10.0``. Before ``0.10.0``, Alpine Linux was used with ``musl``. + The ``tdlib`` binary for Linux provided by ``python-shortcuts`` has been built on Ubuntu with libc strating from version ``0.10.0``. Versions before ``0.10.0`` were built on Alpine Linux with ``musl``. Docker ------ -This library has a `docker image `_ +A Docker image for this library is available `here `_ .. code-block:: bash diff --git a/docs/source/proxy.rst b/docs/source/proxy.rst index 667aa828..feb73bbf 100644 --- a/docs/source/proxy.rst +++ b/docs/source/proxy.rst @@ -7,7 +7,7 @@ Proxy How to use a proxy with tdlib ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Define proxy parameters and pass them to ``Telegram``: +To use a proxy with tdlib, define the proxy parameters and pass them to the ``Telegram`` class: .. code-block:: python diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst index 53386af0..ff9c48ac 100644 --- a/docs/source/tutorial.rst +++ b/docs/source/tutorial.rst @@ -13,9 +13,9 @@ Install the library: python3 -m pip install python-telegram -Let's create a simple echo-bot, which sends "pong" when it receives "ping". +Let's create a simple echo-bot that sends "pong" when it receives "ping". -Initialize a new telegram client with your credentials: +Initialize a new Telegram client with your credentials: .. code-block:: python @@ -29,32 +29,31 @@ Initialize a new telegram client with your credentials: ) .. note:: - The library (actually ``tdlib``) stores messages database and received files in the ``/tmp/.tdlib_files/{phone_number}/``. + The library configures ``tdlib`` to store the messages database and received files in the ``/tmp/.tdlib_files/{phone_number}/``. You can change this behaviour with the ``files_directory`` parameter. .. note:: - You can use bot tokens: just pass ``bot_token`` instead of ``phone``. + You can pass bot tokens by passing ``bot_token`` instead of ``phone``. -After that, you have to login: +Now you need to login to the Telegram. You can do it by calling the `login` method: .. code-block:: python tg.login() -In this example we use a blocking version of the `login` function. You can find an example for non-blocking usage here: :ref:`non_blocking_login`. -Telegram will send you a code in an SMS or as a Telegram message. If you have enabled 2FA, you will be asked for your password too. After successful login you can start using the library: +In this example, we use a blocking version of the ``login`` function. You can find an example for non-blocking usage here: :ref:`non_blocking_login`. +Telegram will send you a code via SMS or as a Telegram message. If you have enabled 2FA, you will also be asked for your password. After successful login, you can start using the library: .. code-block:: python - # this function will be called - # for each received message + # This function will be called for each received message. def new_message_handler(update): print('New message!') tg.add_message_handler(new_message_handler) - tg.idle() # blocking waiting for CTRL+C + tg.idle() # Blocking, waiting for CTRL+C. -This code adds a new message handler which prints a simple text every time it receives a new message. +This code adds a new message handler that prints a simple text every time it receives a new message. ``tg.idle()`` is neccessary to block your script and wait for an exit shortcut (``CTRL+C``). If you run this code, you will see something like that: @@ -69,7 +68,7 @@ Let's add more logic to the message handler: .. code-block:: python def new_message_handler(update): - # we want to process only text messages + # We want to process only text messages. message_content = update['message']['content'].get('text', {}) message_text = message_content.get('text', '').lower() is_outgoing = update['message']['is_outgoing'] @@ -97,7 +96,7 @@ Full code of our new bot: tg.login() def new_message_handler(update): - # we want to process only text messages + # We want to process only text messages. message_content = update['message']['content'].get('text', {}) message_text = message_content.get('text', '').lower() is_outgoing = update['message']['is_outgoing']