python-telegram-bot

.. image:: https://raw.githubusercontent.com/python-telegram-bot/logos/master/logo-text/png/ptb-logo-text_768.png :align: center :target: https://python-telegram-bot.org :alt: python-telegram-bot Logo

.. image:: https://img.shields.io/pypi/v/python-telegram-bot.svg :target: https://pypi.org/project/python-telegram-bot/ :alt: PyPi 包版本

.. image:: https://img.shields.io/pypi/pyversions/python-telegram-bot.svg :target: https://pypi.org/project/python-telegram-bot/ :alt: 支持的Python版本

.. image:: https://img.shields.io/badge/Bot%20API-7.8-blue?logo=telegram :target: https://core.telegram.org/bots/api-changelog :alt: 支持的Bot API版本

.. image:: https://img.shields.io/pypi/dm/python-telegram-bot :target: https://pypistats.org/packages/python-telegram-bot :alt: PyPi 包月下载量

.. image:: https://readthedocs.org/projects/python-telegram-bot/badge/?version=stable :target: https://docs.python-telegram-bot.org/en/stable/ :alt: 文档状态

.. image:: https://img.shields.io/pypi/l/python-telegram-bot.svg :target: https://www.gnu.org/licenses/lgpl-3.0.html :alt: LGPLv3 许可证

.. image:: https://github.com/python-telegram-bot/python-telegram-bot/actions/workflows/unit_tests.yml/badge.svg?branch=master :target: https://github.com/python-telegram-bot/python-telegram-bot/ :alt: Github Actions 工作流

.. image:: https://codecov.io/gh/python-telegram-bot/python-telegram-bot/branch/master/graph/badge.svg :target: https://app.codecov.io/gh/python-telegram-bot/python-telegram-bot :alt: 代码覆盖率

.. image:: https://isitmaintained.com/badge/resolution/python-telegram-bot/python-telegram-bot.svg :target: https://isitmaintained.com/project/python-telegram-bot/python-telegram-bot :alt: 解决问题的中位时间

.. image:: https://api.codacy.com/project/badge/Grade/99d901eaa09b44b4819aec05c330c968 :target: https://app.codacy.com/gh/python-telegram-bot/python-telegram-bot/dashboard :alt: 代码质量: Codacy

.. image:: https://results.pre-commit.ci/badge/github/python-telegram-bot/python-telegram-bot/master.svg :target: https://results.pre-commit.ci/latest/github/python-telegram-bot/python-telegram-bot/master :alt: pre-commit.ci 状态

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg :target: https://github.com/psf/black :alt: 代码风格: Black

.. image:: https://img.shields.io/badge/Telegram-Channel-blue.svg?logo=telegram :target: https://t.me/pythontelegrambotchannel :alt: Telegram 频道

.. image:: https://img.shields.io/badge/Telegram-Group-blue.svg?logo=telegram :target: https://telegram.me/pythontelegrambotgroup :alt: Telegram 群组

我们为您提供了一个无法拒绝的包装器

我们有一个充满活力的开发者社区，在我们的 Telegram 群组 <https://telegram.me/pythontelegrambotgroup>_ 中互相帮助。加入我们吧！

通过我们的 Telegram 频道 <https://telegram.me/pythontelegrambotchannel>_ 了解库更新和新版本发布。

简介

这个库为 Telegram Bot API <https://core.telegram.org/bots/api>_ 提供了一个纯 Python 的异步接口。它兼容 Python 3.8+ 版本。

除了纯 API 实现外，这个库还提供了几个便捷方法和快捷方式，以及一些高级类，使得开发机器人变得简单直接。这些类包含在 telegram.ext 子模块中。

在安装_库之后，请务必查看关于 使用 PTB_ 的部分。

Telegram API 支持


这个库原生支持 Telegram Bot API **7.8** 的所有类型和方法。
此外，尚未原生包含的 Bot API 功能仍然可以使用，具体方法详见 `我们的 wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Bot-API-Forward-Compatibility>`_。

主要特性
~~~~~~~~~~~~~~~~

- `完全异步 <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Concurrency>`_
- 便捷的快捷方法，例如 `Message.reply_text <https://docs.python-telegram-bot.org/en/stable/telegram.message.html#telegram.Message.reply_text>`_
- `使用静态类型提示进行完全注释 <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Type-Checking>`_
- `可定制和可扩展的接口 <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Architecture>`_
- 无缝集成 `webhooks <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Webhooks>`_ 和 `轮询 <https://docs.python-telegram-bot.org/en/stable/telegram.ext.application.html#telegram.ext.Application.run_polling>`_
- `全面的文档和示例 <#working-with-ptb>`_

安装
----------

你可以通过以下命令安装或升级 ``python-telegram-bot``：

.. code:: shell

    $ pip install python-telegram-bot --upgrade

要安装预发布版本，请额外使用 ``--pre`` `标志 <https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-pre>`_。

你也可以从源代码安装 ``python-telegram-bot``，尽管这通常不是必需的。

.. code:: shell

    $ git clone https://github.com/python-telegram-bot/python-telegram-bot
    $ cd python-telegram-bot
    $ pip install build
    $ python -m build

验证发布
~~~~~~~~~~~~~~~~~~

为了让你能够验证你下载的发布文件确实是由 ``python-telegram-bot`` 团队提供的，我们采取了以下措施。

从 v21.4 版本开始，所有发布都通过 `sigstore <https://sigstore.dev>`_ 进行签名。
相应的签名文件上传到 `GitHub 发布页面`_。
要验证签名，请安装 `sigstore Python 客户端 <https://pypi.org/project/sigstore/>`_ 并按照 `验证来自 GitHub Actions 的签名 <https://github.com/sigstore/sigstore-python#signatures-from-github-actions>`_ 的说明操作。对于 ``--repository`` 参数的输入，请使用值 ``python-telegram-bot/python-telegram-bot``。

早期版本使用 GPG 密钥签名。
签名上传到 `GitHub 发布页面`_ 和 `PyPI 项目 <https://pypi.org/project/python-telegram-bot/>`_，文件名以 ``.asc`` 后缀结尾。
公钥可以在 `这里 <https://github.com/python-telegram-bot/python-telegram-bot/tree/master/public_keys>`_ 找到。
密钥的命名格式为 ``<first_version>-<last_version>.gpg``。

此外，GitHub 发布页面还包含发布文件的 sha1 哈希值，文件名以 ``.sha1`` 后缀结尾。

依赖及其版本

python-telegram-bot 尽量减少对第三方依赖的使用。然而，对于某些功能，使用第三方库比重新实现功能更为明智。由于这些功能是可选的，相应的第三方依赖默认不会安装。相反，它们被列为可选依赖。这样可以避免不需要这些可选功能的用户遇到不必要的依赖冲突。

唯一必需的依赖是 httpx ~= 0.27 <https://www.python-httpx.org>_，用于 telegram.request.HTTPXRequest，即默认的网络后端。

python-telegram-bot 与其他库一起使用时最为有用。为了最小化依赖冲突，我们尽量在（可选）依赖的版本要求上保持灵活。另一方面，我们必须确保 python-telegram-bot 的稳定性，这就是为什么我们会设置版本限制。如果你因这些限制而遇到依赖冲突，请随时联系我们。

可选依赖 #####################

PTB 可以安装以下可选依赖：

pip install "python-telegram-bot[passport]" 安装 cryptography>=39.0.1 <https://cryptography.io/en/stable>_ 库。如果你想使用 Telegram Passport 相关功能，请使用此选项。
pip install "python-telegram-bot[socks]" 安装 httpx[socks] <https://www.python-httpx.org/#dependencies>_。如果你想在 Socks5 服务器后工作，请使用此选项。
pip install "python-telegram-bot[http2]" 安装 httpx[http2] <https://www.python-httpx.org/#dependencies>_。如果你想使用 HTTP/2，请使用此选项。
pip install "python-telegram-bot[rate-limiter]" 安装 aiolimiter~=1.1.0 <https://aiolimiter.readthedocs.io/en/stable/>_。如果你想使用 telegram.ext.AIORateLimiter，请使用此选项。
pip install "python-telegram-bot[webhooks]" 安装 tornado~=6.4 <https://www.tornadoweb.org/en/stable/>_ 库。如果你想使用 telegram.ext.Updater.start_webhook/telegram.ext.Application.run_webhook，请使用此选项。
pip install "python-telegram-bot[callback-data]" 安装 cachetools>=5.3.3,<5.5.0 <https://cachetools.readthedocs.io/en/latest/>_ 库。如果你想使用 任意 callback_data <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Arbitrary-callback_data>_，请使用此选项。
pip install "python-telegram-bot[job-queue]" 安装 APScheduler~=3.10.4 <https://apscheduler.readthedocs.io/en/3.x/>_ 库并强制使用 pytz>=2018.6 <https://pypi.org/project/pytz/>_，其中 pytz 是 APScheduler 的依赖。如果你想使用 telegram.ext.JobQueue，请使用此选项。要安装多个可选依赖项，请用逗号分隔它们，例如 pip install "python-telegram-bot[socks,webhooks]"。

此外，还提供了两个快捷方式：

pip install "python-telegram-bot[all]" 安装所有可选依赖项。
pip install "python-telegram-bot[ext]" 安装与 telegram.ext 相关的所有可选依赖项，即 [rate-limiter, webhooks, callback-data, job-queue]。

使用 PTB

一旦安装了库，你就可以开始使用它了 - 让我们开始吧！

快速入门


我们的 Wiki 包含一个 `API 介绍 <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Introduction-to-the-API>`_，解释了如何通过 ``python-telegram-bot`` 访问纯 Bot API。
此外，`教程：你的第一个机器人 <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Extensions---Your-first-Bot>`_ 介绍了如何借助 ``telegram.ext`` 模块轻松编程聊天机器人。

资源
~~~~~~~~~

- `包文档 <https://docs.python-telegram-bot.org/>`_ 是 ``python-telegram-bot`` 的技术参考。
  它包含所有可用类、模块、方法和参数的描述，以及 `更新日志 <https://docs.python-telegram-bot.org/changelog.html>`_。
- `wiki <https://github.com/python-telegram-bot/python-telegram-bot/wiki/>`_ 包含了许多关于 ``python-telegram-bot`` 不同功能的更详细介绍，以及其他超出技术文档范围的有用资源。
- 我们的 `示例部分 <https://docs.python-telegram-bot.org/examples.html>`_ 包含几个展示 Bot API 和 ``python-telegram-bot`` 不同功能的示例。
  即使这不是你的学习方法，也请看一看 ``echobot.py``。它是大多数机器人的事实上的基础。
  这些示例的代码已发布到公共领域，所以你可以从获取代码开始，在此基础上进行构建。
- 当然，`官方 Telegram Bot API 文档 <https://core.telegram.org/bots/api>`_ 也总是值得一读。

获取帮助

如果上述资源无法回答你的问题或让你感到不知所措，有几种获取帮助的方式。

我们有一个充满活力的开发者社区，在我们的 Telegram 群组 <https://telegram.me/pythontelegrambotgroup>_ 中互相帮助。加入我们！在这里提问通常是获得正确方向指引的最快方式。
通过开启 讨论 <https://github.com/python-telegram-bot/python-telegram-bot/discussions/new>_ 来提问。
你甚至可以使用 python-telegram-bot 标签 <https://stackoverflow.com/questions/tagged/python-telegram-bot>_ 在 Stack Overflow 上寻求帮助。

并发


从 v20.0 开始，``python-telegram-bot`` 建立在 Python 的 ``asyncio`` 模块之上。
由于 ``asyncio`` 通常是单线程的，``python-telegram-bot`` 目前不打算做到线程安全。
``python-telegram-bot`` API 中值得注意的部分在多线程环境中使用可能会导致问题（例如竞态条件），包括：

* ``telegram.ext.Application/Updater.update_queue``
* ``telegram.ext.ConversationHandler.check/handle_update``
* ``telegram.ext.CallbackDataCache``
* ``telegram.ext.BasePersistence``
* ``telegram.ext.filters`` 模块中所有允许在运行时添加/删除允许的用户/聊天的类

贡献
------------

我们欢迎各种规模的贡献。
请查看我们的 `贡献指南 <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.github/CONTRIBUTING.rst>`_ 以开始。
你也可以通过 `报告错误或功能请求 <https://github.com/python-telegram-bot/python-telegram-bot/issues/new/choose>`_ 来提供帮助。

捐赠
--------
有时我们会被问到是否接受捐赠来支持开发。
虽然我们感谢这种想法，但维护 PTB 是我们的爱好，我们几乎没有运营成本。因此，我们没有设置接受捐赠的渠道。
如果你仍然想捐赠，我们恳请你将捐赠给你选择的另一个开源项目/计划。

许可证
-------

你可以复制、分发和修改该软件，前提是修改要描述并根据 `LGPL-3 <https://www.gnu.org/licenses/lgpl-3.0.html>`_ 免费许可。
衍生作品（包括修改或与库静态链接的任何内容）只能在 LGPL-3 下重新分发，但使用该库的应用程序不必如此。

.. _`GitHub 发布页面`: https://github.com/python-telegram-bot/python-telegram-bot/releases>