python-telegram 0.18.0__tar.gz → 2.0.0__tar.gz

python_telegram-2.0.0/.gitignore

@@ -0,0 +1,13 @@
+dist
+build
+python_telegram.egg-info
+.tdlib_files
+.tdlib_files*
+.tox
+.mypy_cache
+MANIFEST
+*.pyc
+.DS_Store
+.vscode
+telegram/lib/
+/tdlib/

python_telegram-2.0.0/CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing
+
+Pull requests are welcome!
+
+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/latest/).
+
+## Reporting bugs
+
+We use [GitHub
+Issues](https://github.com/alexander-akhmetov/python-telegram/issues) to track
+bugs. If you find a bug, please open a new issue.
+
+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 `main`.
+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 [ruff](https://docs.astral.sh/ruff/) as an autoformatter and linter.
+
+## Tests
+
+To run tests you need to install [tox](https://tox.wiki/).
+
+Run tests:
+
+```shell
+tox
+```
+
+Run a specific test using python 3.12:
+
+```shell
+tox -e py312 -- -k test_add_message_handler
+```
+
+`tests/test_tdlib_binary.py` loads a real `tdlib` and skips when it cannot find one, so a
+checkout with no system `tdlib` still runs a green suite.
+
+## tdlib binaries
+
+The binaries are not in this repository. They are built in
+[tdlib-compiled](https://github.com/alexander-akhmetov/tdlib-compiled), which publishes one
+per platform as a release with a `SHA256SUMS` and a `BUILD-INFO.json`.
+
+`tdlib.lock` pins that release tag, the asset names, the wheel platform tags and the sha256
+of each asset. Bumping tdlib is a PR that changes only that file: copy the tag, the digests
+and the `wheel_platform` values out of the new release's `BUILD-INFO.json`, so the lock
+always describes bytes that exist.
+
+To build one platform wheel yourself, download the asset for your target and run:
+
+```shell
+PYTHON_TELEGRAM_TDLIB_TARGET=macos-arm64 PYTHON_TELEGRAM_TDLIB_DIR=tdlib python -m build --wheel
+```
+
+With no `PYTHON_TELEGRAM_TDLIB_TARGET` the build produces a binary-free pure wheel, which is
+what `pip install -e .` needs.
+
+`make docker/build` installs the released PyPI version, not your working tree.
+
+## Release checklist
+
+1. Bump `__version__` in `telegram/__init__.py` and write the changelog entry.
+2. Tag a release candidate first, for example `1.1.0rc1`. The tag pattern matches it and
+   PyPI does not serve a prerelease by default, so it exercises all four wheels, the four
+   verification runners, the attestation and trusted publishing with a version nobody
+   installs by accident.
+3. Install the release candidate wheel and run `examples/echo_bot.py` against a bot token,
+   on macOS arm64 and on Linux. Watch the full
+   `NONE -> WAIT_TDLIB_PARAMETERS -> WAIT_PHONE_NUMBER -> READY` sequence. This is the only
+   check that covers the login request payloads; the smoke test cannot, because they need a
+   live session.
+4. Tag the final version.

python_telegram-2.0.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.5
+Name: python-telegram
+Version: 2.0.0
+Summary: Python library to help you build your own Telegram clients
+Project-URL: Source, https://github.com/alexander-akhmetov/python-telegram
+Project-URL: Documentation, https://python-telegram.readthedocs.io/latest/
+Project-URL: Tutorial, https://python-telegram.readthedocs.io/latest/tutorial.html
+Project-URL: Changelog, https://python-telegram.readthedocs.io/latest/changelog.html
+Author-email: Alexander Akhmetov <me@alx.cx>
+License: MIT
+License-File: LICENSE
+Keywords: api,client,td,tdjson,tdlib,telegram
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: telegram-text==0.2.0
+Description-Content-Type: text/markdown
+
+# python-telegram
+
+[![Build Status](https://github.com/alexander-akhmetov/python-telegram/workflows/python-telegram%20tests/badge.svg)](https://github.com/alexander-akhmetov/python-telegram/actions)
+[![PyPI](https://img.shields.io/pypi/v/python-telegram.svg)](https://pypi.python.org/pypi/python-telegram)
+[![Read the Docs](https://img.shields.io/readthedocs/python-telegram/latest.svg)](https://python-telegram.readthedocs.io/latest/)
+
+Python API for the [tdlib](https://github.com/tdlib/td) library.
+It helps you build your own Telegram clients.
+
+`tdlib` connects to Telegram over MTProto, the same protocol the official apps use.
+This library signs in as a full Telegram account with a phone number, and it can do what a regular client can do.
+
+It is not a wrapper around the HTTP Bot API.
+If you only need a bot, [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot) is a better fit.
+You can still sign in as a bot here by passing `bot_token` instead of `phone`.
+
+- [Changelog](https://python-telegram.readthedocs.io/latest/changelog.html)
+- [Documentation](https://python-telegram.readthedocs.io/latest/)
+- [Tutorial](https://python-telegram.readthedocs.io/latest/tutorial.html)
+
+## Installation
+
+This library requires Python 3.10+. Windows is not supported.
+
+```shell
+pip install python-telegram
+```
+
+See [documentation](https://python-telegram.readthedocs.io/latest/#installation) for more details.
+
+### tdlib
+
+Four wheels bundle a `tdlib` binary. Each one works on Python 3.10 through 3.14:
+
+| Platform | Wheel | Needs at least |
+| --- | --- | --- |
+| Linux x86_64 | `manylinux_2_28_x86_64` | glibc 2.28 |
+| Linux aarch64 | `manylinux_2_28_aarch64` | glibc 2.28 |
+| macOS arm64 | `macosx_11_0_arm64` | macOS 11 |
+| macOS x86_64 | `macosx_10_15_x86_64` | macOS 10.15 |
+
+Those binaries link OpenSSL and zlib statically, so they need nothing from the system.
+
+Anywhere else, pip installs the source distribution, which carries no binary. On musl, on
+32-bit ARM, or with an older glibc, [compile](https://tdlib.github.io/td/build.html) `tdlib`
+yourself.
+
+`python-telegram` looks for the library in this order, and logs which one it used:
+
+1. the `library_path` argument
+2. the `PYTHON_TELEGRAM_TDLIB_PATH` environment variable
+3. a system-wide `tdjson`
+4. the bundled binary
+
+A system-wide `tdlib` therefore wins over the bundled one. To point at a specific build,
+pass its path. The file is called `libtdjson.so` on Linux and `libtdjson.dylib` on macOS:
+
+```python
+tg = Telegram(
+    # ...
+    library_path="/usr/local/lib/libtdjson.so",
+)
+```
+
+If nothing can be found, `TDJson()` raises `TDLibNotFoundError`, an `OSError` subclass whose
+message names the platform, the paths tried and the overrides.
+
+### Docker
+
+This library has a [docker image](https://hub.docker.com/r/akhmetov/python-telegram/):
+
+```sh
+docker run -i -t --rm \
+            -v /tmp/docker-python-telegram/:/tmp/ \
+            akhmetov/python-telegram \
+            python3 /app/examples/send_message.py $API_ID $API_HASH $PHONE $CHAT_ID $TEXT
+```
+
+## How to use the library
+
+First, [register a new Telegram application](https://my.telegram.org/apps/) to get your `api_id` and `api_hash`.
+Check out the [tutorial](https://python-telegram.readthedocs.io/latest/tutorial.html) for more details.
+
+Basic example:
+
+```python
+from telegram.client import Telegram
+from telegram.text import Spoiler
+
+tg = Telegram(
+    api_id=123456,
+    api_hash="api_hash",
+    phone="+31611111111",  # you can pass 'bot_token' instead
+    database_encryption_key="changekey123",
+    files_directory="/tmp/.tdlib_files/",
+)
+tg.login()
+
+# The chat must be in the tdlib database before you can send a message to it.
+# `get_chats` loads up to `limit` chats from the main chat list.
+result = tg.get_chats(limit=100)
+result.wait()
+
+chat_id = 123456789
+result = tg.send_message(chat_id, Spoiler("Hello world!"))
+
+# `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.
+```
+
+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):
+
+```python
+tg.call_method("getUser", params={"user_id": user_id})
+```
+
+More examples can be found in the [/examples/ directory](/examples/).
+
+---
+
+More information is available in the [documentation](https://python-telegram.readthedocs.io/latest/).
+
+## Development
+
+See [CONTRIBUTING.md](/CONTRIBUTING.md).

python_telegram-2.0.0/README.md

@@ -0,0 +1,129 @@
+# python-telegram
+
+[![Build Status](https://github.com/alexander-akhmetov/python-telegram/workflows/python-telegram%20tests/badge.svg)](https://github.com/alexander-akhmetov/python-telegram/actions)
+[![PyPI](https://img.shields.io/pypi/v/python-telegram.svg)](https://pypi.python.org/pypi/python-telegram)
+[![Read the Docs](https://img.shields.io/readthedocs/python-telegram/latest.svg)](https://python-telegram.readthedocs.io/latest/)
+
+Python API for the [tdlib](https://github.com/tdlib/td) library.
+It helps you build your own Telegram clients.
+
+`tdlib` connects to Telegram over MTProto, the same protocol the official apps use.
+This library signs in as a full Telegram account with a phone number, and it can do what a regular client can do.
+
+It is not a wrapper around the HTTP Bot API.
+If you only need a bot, [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot) is a better fit.
+You can still sign in as a bot here by passing `bot_token` instead of `phone`.
+
+- [Changelog](https://python-telegram.readthedocs.io/latest/changelog.html)
+- [Documentation](https://python-telegram.readthedocs.io/latest/)
+- [Tutorial](https://python-telegram.readthedocs.io/latest/tutorial.html)
+
+## Installation
+
+This library requires Python 3.10+. Windows is not supported.
+
+```shell
+pip install python-telegram
+```
+
+See [documentation](https://python-telegram.readthedocs.io/latest/#installation) for more details.
+
+### tdlib
+
+Four wheels bundle a `tdlib` binary. Each one works on Python 3.10 through 3.14:
+
+| Platform | Wheel | Needs at least |
+| --- | --- | --- |
+| Linux x86_64 | `manylinux_2_28_x86_64` | glibc 2.28 |
+| Linux aarch64 | `manylinux_2_28_aarch64` | glibc 2.28 |
+| macOS arm64 | `macosx_11_0_arm64` | macOS 11 |
+| macOS x86_64 | `macosx_10_15_x86_64` | macOS 10.15 |
+
+Those binaries link OpenSSL and zlib statically, so they need nothing from the system.
+
+Anywhere else, pip installs the source distribution, which carries no binary. On musl, on
+32-bit ARM, or with an older glibc, [compile](https://tdlib.github.io/td/build.html) `tdlib`
+yourself.
+
+`python-telegram` looks for the library in this order, and logs which one it used:
+
+1. the `library_path` argument
+2. the `PYTHON_TELEGRAM_TDLIB_PATH` environment variable
+3. a system-wide `tdjson`
+4. the bundled binary
+
+A system-wide `tdlib` therefore wins over the bundled one. To point at a specific build,
+pass its path. The file is called `libtdjson.so` on Linux and `libtdjson.dylib` on macOS:
+
+```python
+tg = Telegram(
+    # ...
+    library_path="/usr/local/lib/libtdjson.so",
+)
+```
+
+If nothing can be found, `TDJson()` raises `TDLibNotFoundError`, an `OSError` subclass whose
+message names the platform, the paths tried and the overrides.
+
+### Docker
+
+This library has a [docker image](https://hub.docker.com/r/akhmetov/python-telegram/):
+
+```sh
+docker run -i -t --rm \
+            -v /tmp/docker-python-telegram/:/tmp/ \
+            akhmetov/python-telegram \
+            python3 /app/examples/send_message.py $API_ID $API_HASH $PHONE $CHAT_ID $TEXT
+```
+
+## How to use the library
+
+First, [register a new Telegram application](https://my.telegram.org/apps/) to get your `api_id` and `api_hash`.
+Check out the [tutorial](https://python-telegram.readthedocs.io/latest/tutorial.html) for more details.
+
+Basic example:
+
+```python
+from telegram.client import Telegram
+from telegram.text import Spoiler
+
+tg = Telegram(
+    api_id=123456,
+    api_hash="api_hash",
+    phone="+31611111111",  # you can pass 'bot_token' instead
+    database_encryption_key="changekey123",
+    files_directory="/tmp/.tdlib_files/",
+)
+tg.login()
+
+# The chat must be in the tdlib database before you can send a message to it.
+# `get_chats` loads up to `limit` chats from the main chat list.
+result = tg.get_chats(limit=100)
+result.wait()
+
+chat_id = 123456789
+result = tg.send_message(chat_id, Spoiler("Hello world!"))
+
+# `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.
+```
+
+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):
+
+```python
+tg.call_method("getUser", params={"user_id": user_id})
+```
+
+More examples can be found in the [/examples/ directory](/examples/).
+
+---
+
+More information is available in the [documentation](https://python-telegram.readthedocs.io/latest/).
+
+## Development
+
+See [CONTRIBUTING.md](/CONTRIBUTING.md).

{python-telegram-0.18.0 → python_telegram-2.0.0}/docs/requirements.txt

@@ -1,3 +1,4 @@
 sphinx
 sphinx-autobuild
 autodoc
+sphinx-immaterial

python_telegram-2.0.0/docs/source/changelog.rst

@@ -0,0 +1,176 @@
+=========
+Changelog
+=========
+
+[2.0.0] - 2026-08-23
+--------------------
+
+- tdlib 1.8.31 is replaced by tdlib 1.8.66.
+- ``python-telegram`` is now published as four platform wheels instead of one ``py3-none-any`` wheel: ``manylinux_2_28_x86_64``, ``manylinux_2_28_aarch64``, ``macosx_11_0_arm64`` and ``macosx_10_15_x86_64``. Each bundles a ``tdlib`` that links OpenSSL and zlib statically, so it needs nothing from the system.
+- The bundled binary now works on Apple Silicon. The old one was x86_64 only and ``ctypes`` refused to load it (`#377 <https://github.com/alexander-akhmetov/python-telegram/issues/377>`_).
+- The bundled Linux binary no longer needs OpenSSL 1.1, which reached end of life in 2023 and is absent from Debian 12+, Ubuntu 22.04+ and RHEL 9. Importing the library in those images failed with ``libssl.so.1.1: cannot open shared object file``.
+- Installing from the source distribution no longer gives you a ``tdlib`` binary. The sdist is the fallback for the platforms the four wheels do not cover, so install ``tdlib`` system-wide or pass ``library_path``.
+- The library can now be pointed at a specific ``tdlib`` with the ``PYTHON_TELEGRAM_TDLIB_PATH`` environment variable. The search order is ``library_path``, then that variable, then a system-wide ``tdjson``, then the bundled binary. Which one was used is logged.
+- When no library can be found or loaded, ``TDJson`` raises ``TDLibNotFoundError`` instead of a raw ``dlopen`` message. It subclasses ``OSError``, which is what ``ctypes.CDLL`` used to raise, so existing handlers keep working.
+- Login no longer fails with a ``ValueError`` on ``authorizationStateWaitPremiumPurchase``, and an authorization state this library has never heard of now resolves to ``AuthorizationState.UNKNOWN`` instead of raising.
+
+Breaking changes, from the tdlib 1.8.66 signatures:
+
+- ``get_web_page_instant_view`` takes ``only_local`` instead of ``force_full``. tdlib removed ``force_full``; ``only_local`` means something different, "use locally available information only, without any network request".
+- ``import_contacts`` now sends each contact as an ``importedContact`` rather than a ``contact``. That is what ``importContacts`` takes in 1.8.66.
+- ``addProxy`` now nests the server, port and type inside a ``proxy`` object. Code that calls ``call_method('addProxy', ...)`` directly has to be updated.
+
+[1.0.0] - 2026-07-25
+--------------------
+
+- Python 3.9 is no longer supported.
+- Added support for Python 3.13 and 3.14.
+- Login no longer fails with a ``ValueError`` when tdlib reports an authorization state that ``AuthorizationState`` did not know about: ``authorizationStateWaitEmailAddress``, ``authorizationStateWaitEmailCode``, ``authorizationStateWaitOtherDeviceConfirmation`` and ``authorizationStateLoggingOut``.
+- Added email authorization support: ``send_email_address`` and ``send_email_code``.
+- ``stop`` no longer blocks forever when tdlib does not answer, and no longer leaves the client running when tdlib answers with an error. It now waits up to 5 seconds for the session to close, which can be changed with ``stop(close_timeout=...)``.
+- Calling a method after ``stop`` raises ``ClientDestroyedError`` instead of crashing the process. The destroyed tdlib handle was passed to the C library as a ``NULL`` pointer.
+- An exception raised by an update handler no longer stops the worker thread. The error is logged and the worker keeps processing the queue.
+- When the handler queue is full, the update is dropped and an error is logged instead of raising ``queue.Full``.
+- ``get_chats`` no longer sends the ``offset_order`` and ``offset_chat_id`` parameters. tdlib removed them from ``getChats`` in 1.8.0 and silently ignored them since then, so passing them had no effect. The signature is now ``get_chats(limit=100, chat_list=None)``, which also makes it possible to read the archive and chat folders instead of only the main chat list. This is a breaking change for code that passes the offsets.
+- Added ``load_chats``, which wraps the tdlib ``loadChats`` method.
+
+[0.19.0] - 2024-06-23
+---------------------
+
+- Python versions 3.7 and 3.8 are no longer supported.
+- tdlib 1.8.31.
+
+[0.18.0] - 2023-03-13
+---------------------
+
+- Added support for tdlib > 1.8.5. (thanks to @JleMyP)
+
+[0.17.0] - 2023-01-25
+---------------------
+
+- Added ``import_contacts`` method. (thanks to @vlad-lf)
+- Added markup support. It is now possible to send formatted text (html/markdown and telegram-specific formats, for example hidden spoiler styling) (thanks to @SKY-ALIN)
+
+[0.16.0] - 2022-08-18
+---------------------
+
+- Search for the system library first, and fallback to the embedded one if the system was not found.
+- Fixed the finding system library mechanism (thanks to @weirdo-neutrino)
+- tdlib v1.8.5
+
+[0.15.0] - 2021-12-03
+---------------------
+
+- tdlib v1.7.9. Fixes ``UPDATE_APP_TO_LOGIN`` errors.
+
+[0.14.0] - 2020-12-17
+---------------------
+
+- tdlib v1.7.0
+
+[0.13.0] - 2020-11-16
+---------------------
+
+- Non-blocking login, see ``examples/get_me_non_blocking_login.py`` (thanks to @melfnt).
+- Better stop. python-telegram calls ``close`` and waits until tdlib is closed.
+
+[0.12.0] - 2020-03-29
+---------------------
+
+- New example: ``examples/clear_group_messages.py`` (thanks to @h4x3rotab)
+- Proxy support (thanks to @h4x3rotab)
+- New methods: ``delete_messages``, ``get_supergroup_full_info``, ``create_basic_group_chat``. (thanks to @h4x3rotab)
+- Fix #67: fixed infinite waiting for a result during login or for an ``ok`` result type.
+- New Telegram initialization parameter: ``use_secret_chats`` (``True`` by default) (thanks to @DopeforHope)
+- Fix #81: ``encryption_key`` for tdlib database encryption is now being sent to tdlib as a base64 encoded string.
+
+[0.11.0] - 2020-02-15
+---------------------
+
+- ``tdlib`` upgraded to ``v1.6.0`` (from `this repository <https://github.com/alexander-akhmetov/tdlib-compiled>`_)
+- Added a new parameter to the ``call_method``: ``block=False``. If it is set to ``True``, the method waits for the result from tdlib.
+- Added ``Telegram.get_message`` method (thanks to @ali-shokoohi)
+- Fixed a race condition when in some cases ``AsyncResult.wait()`` could raise ``TimeoutError`` or end up in an endless loop. (thanks to @akamaus)
+- Added a new method: ``get_user``.
+- Added ``Telegram.remove_update_handler`` function to remove update handlers.
+
+[0.10.0] - 2019-04-10
+---------------------
+
+- **Incompatible** Linux library has been changed, now it's compiled on Ubuntu with libc.
+
+[0.9.0] - 2019-04-05
+--------------------
+
+- **Incompatible** default path for files is changed. Now the library uses an md5 hash of the phone number or bot token instead of just a phone number.
+  It should not be noticeable for most cases, but if you rely on locally saved files or database, you need to pass the ``files_directory`` parameter to the ``telegram.client.Telegram``.
+- Fixed problem with randomly raised "Database encryption key is needed" errors during login process. (#12)
+- Fixed ``stop`` method execution. (#8)
+- Added ``examples/bot_login.py`` example.
+
+[0.8.0] - 2019-03-17
+--------------------
+
+- ``telegram.client.Telegram`` now supports any update type with a new method ``add_update_handler(handler_type, func)``
+- ``tdlib v 1.3.0``
+- Fixed problem with openssl in Dockerfile (#4)
+
+[0.7.0]
+-------
+
+- New method ``getMe`` with an example.
+
+[0.6.1] - 2018-05-01
+--------------------
+
+- Fixes for the Linux pre-compiled tdlib library.
+
+[0.6.0] - 2018-05-01
+--------------------
+
+- Fixes for the Linux pre-compiled tdlib library.
+
+[0.5.0] - 2018-05-01
+--------------------
+
+- New **required** parameter in the ``telegram.client.Telegram``: ``database_encryption_key``.
+
+- Compiled ``tdlib`` files now are in the pypi package (Linux and MacOS).
+
+- Default location of the tdlib's files changed to ``/tmp/.tdlib_files/{phone_number}``.
+
+- Now you can define additional optional params:
+
+    * use_test_dc (default False)
+    * device_model
+    * system_version
+    * system_language_code
+    * application_version
+    * use_message_database (default True)
+
+- Added new example: ``chat_stats.py``.
+
+[0.4.0] - 2018-04-29
+--------------------
+
+Added two new methods:
+
+-  ``get_instant_view`` - get instant view of a web page
+-  ``call_method`` - call any method with any params
+
+New example: `get_instant_view.py <https://github.com/alexander-akhmetov/python-telegram/blob/main/examples/get_instant_view.py>`_
+
+[0.3.1] - 2018-04-29
+--------------------
+
+-  Logging level in the examples changed to ``INFO``.
+-  Added new ``Makefile`` command: ``docker-echo-bot``.
+-  All ``docker-`` commands in the ``Makefile`` now mount ``/tmp/`` from
+   a host machine to store tdlib's files.
+
+[0.3.0] - 2018-04-28
+--------------------
+
+-  Added ``Dockerfile`` and ``Makefile`` with some examples.
+-  Changed directory for tdlib files to
+   ``/tmp/.tdlib_files_{self.phone}/``.