websockets

.. image:: logo/horizontal.svg :width: 480px :alt: websockets

.. |licence| image:: https://img.shields.io/pypi/l/websockets.svg :target: https://pypi.python.org/pypi/websockets

.. |version| image:: https://img.shields.io/pypi/v/websockets.svg :target: https://pypi.python.org/pypi/websockets

.. |pyversions| image:: https://img.shields.io/pypi/pyversions/websockets.svg :target: https://pypi.python.org/pypi/websockets

.. |tests| image:: https://img.shields.io/github/checks-status/python-websockets/websockets/main?label=tests :target: https://github.com/python-websockets/websockets/actions/workflows/tests.yml

.. |docs| image:: https://img.shields.io/readthedocs/websockets.svg :target: https://websockets.readthedocs.io/

.. |openssf| image:: https://bestpractices.coreinfrastructure.org/projects/6475/badge :target: https://bestpractices.coreinfrastructure.org/projects/6475

什么是 `websockets`？

websockets 是一个用于在 Python 中构建 WebSocket_ 服务器和客户端的库，注重正确性、简洁性、稳健性和性能。

.. _WebSocket: https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API

基于 Python 标准异步 I/O 框架 asyncio 构建，默认实现提供了一个优雅的基于协程的 API。

还提供了基于 threading 的实现和一个 Sans-I/O 实现。

文档可在 Read the Docs 上查阅。<https://websockets.readthedocs.io/>_

以下是使用 asyncio API 的回显服务器示例：

.. code:: python

#!/usr/bin/env python

import asyncio
from websockets.server import serve

async def echo(websocket):
    async for message in websocket:
        await websocket.send(message)

async def main():
    async with serve(echo, "localhost", 8765):
        await asyncio.get_running_loop().create_future()  # 永远运行

asyncio.run(main())

以下是客户端使用 threading API 发送和接收消息的示例：

.. code:: python

#!/usr/bin/env python

from websockets.sync.client import connect

def hello():
    with connect("ws://localhost:8765") as websocket:
        websocket.send("Hello world!")
        message = websocket.recv()
        print(f"收到: {message}")

hello()

看起来不错吧？

从教程开始吧！<https://websockets.readthedocs.io/en/stable/intro/index.html>_

.. raw:: html

<hr>
<img align="left" height="150" width="150" src="https://yellow-cdn.veclightyear.com/835a84d5/de76c456-c59f-42af-9b41-28b83fbb4179.png">
<h3 align="center"><i>企业版 websockets</i></h3>
<p align="center"><i>作为 Tidelift 订阅的一部分提供</i></p>
<p align="center"><i>websockets 的维护者和数千个其他包的维护者正在与 Tidelift 合作，为您用于构建应用程序的开源依赖项提供商业支持和维护。节省时间，降低风险，改善代码健康，同时向您使用的确切依赖项的维护者付费。<a href="https://tidelift.com/subscription/pkg/pypi-websockets?utm_source=pypi-websockets&utm_medium=referral&utm_campaign=readme">了解更多。</a></i></p>
<hr>
<p>（如果您为 <code>websockets</code> 做出贡献并希望成为官方支持提供者，请<a href="https://fractalideas.com/">告诉我</a>。）</p>

为什么我应该使用 `websockets`？

websockets 的开发遵循四个原则：

正确性：websockets 经过大量测试，以确保符合 :rfc:6455。持续集成在 100% 分支覆盖率下才能通过。
简洁性：您只需要理解 msg = await ws.recv() 和 await ws.send(msg)。websockets 负责管理连接，让您可以专注于应用程序。
稳健性：websockets 是为生产环境而构建的。例如，在反压问题在 Python 社区广为人知之前，它是唯一一个正确处理反压的库。
性能：内存使用经过优化且可配置。C 扩展加速了昂贵的操作。它针对 Linux、macOS 和 Windows 进行了预编译，并为每个系统和 Python 版本打包成 wheel 格式。

文档是项目中的一等公民。前往 Read the Docs_ 亲自体验。

.. _Read the Docs: https://websockets.readthedocs.io/ .. _正确处理反压: https://vorpus.org/blog/some-thoughts-on-asynchronous-api-design-in-a-post-asyncawait-world/#websocket-servers

为什么我不应该使用 `websockets`？

如果您更喜欢回调而不是协程：websockets 的创建目的是为 Python 中管理 WebSocket 连接提供最佳的基于协程的 API。如果需要基于回调的 API，请选择其他库。
如果您正在寻找混合 HTTP / WebSocket 库：websockets 旨在成为 :rfc:6455：WebSocket 协议和 :rfc:7692：WebSocket 压缩扩展的优秀实现。它对 HTTP 的支持是最小的 —— 仅足够进行 HTTP 健康检查。

如果您想在同一服务器中同时使用两者，请查看在 websockets 基础上构建的支持 WebSocket 连接的 HTTP 框架，如 Sanic_。

.. _Sanic: https://sanicframework.org/en/