METADATA 6.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165
  1. Metadata-Version: 2.1
  2. Name: websockets
  3. Version: 9.1
  4. Summary: An implementation of the WebSocket Protocol (RFC 6455 & 7692)
  5. Home-page: https://github.com/aaugustin/websockets
  6. Author: Aymeric Augustin
  7. Author-email: aymeric.augustin@m4x.org
  8. License: BSD
  9. Platform: UNKNOWN
  10. Classifier: Development Status :: 5 - Production/Stable
  11. Classifier: Environment :: Web Environment
  12. Classifier: Intended Audience :: Developers
  13. Classifier: License :: OSI Approved :: BSD License
  14. Classifier: Operating System :: OS Independent
  15. Classifier: Programming Language :: Python
  16. Classifier: Programming Language :: Python :: 3
  17. Classifier: Programming Language :: Python :: 3.6
  18. Classifier: Programming Language :: Python :: 3.7
  19. Classifier: Programming Language :: Python :: 3.8
  20. Classifier: Programming Language :: Python :: 3.9
  21. Requires-Python: >=3.6.1
  22. .. image:: logo/horizontal.svg
  23. :width: 480px
  24. :alt: websockets
  25. |rtd| |pypi-v| |pypi-pyversions| |pypi-l| |pypi-wheel| |tests|
  26. .. |rtd| image:: https://readthedocs.org/projects/websockets/badge/?version=latest
  27. :target: https://websockets.readthedocs.io/
  28. .. |pypi-v| image:: https://img.shields.io/pypi/v/websockets.svg
  29. :target: https://pypi.python.org/pypi/websockets
  30. .. |pypi-pyversions| image:: https://img.shields.io/pypi/pyversions/websockets.svg
  31. :target: https://pypi.python.org/pypi/websockets
  32. .. |pypi-l| image:: https://img.shields.io/pypi/l/websockets.svg
  33. :target: https://pypi.python.org/pypi/websockets
  34. .. |pypi-wheel| image:: https://img.shields.io/pypi/wheel/websockets.svg
  35. :target: https://pypi.python.org/pypi/websockets
  36. .. |tests| image:: https://github.com/aaugustin/websockets/workflows/tests/badge.svg?branch=master
  37. :target: https://github.com/aaugustin/websockets/actions?workflow=tests
  38. What is ``websockets``?
  39. -----------------------
  40. ``websockets`` is a library for building WebSocket servers_ and clients_ in
  41. Python with a focus on correctness and simplicity.
  42. .. _servers: https://github.com/aaugustin/websockets/blob/master/example/server.py
  43. .. _clients: https://github.com/aaugustin/websockets/blob/master/example/client.py
  44. Built on top of ``asyncio``, Python's standard asynchronous I/O framework, it
  45. provides an elegant coroutine-based API.
  46. `Documentation is available on Read the Docs. <https://websockets.readthedocs.io/>`_
  47. Here's how a client sends and receives messages:
  48. .. copy-pasted because GitHub doesn't support the include directive
  49. .. code:: python
  50. #!/usr/bin/env python
  51. import asyncio
  52. import websockets
  53. async def hello(uri):
  54. async with websockets.connect(uri) as websocket:
  55. await websocket.send("Hello world!")
  56. await websocket.recv()
  57. asyncio.get_event_loop().run_until_complete(
  58. hello('ws://localhost:8765'))
  59. And here's an echo server:
  60. .. code:: python
  61. #!/usr/bin/env python
  62. import asyncio
  63. import websockets
  64. async def echo(websocket, path):
  65. async for message in websocket:
  66. await websocket.send(message)
  67. asyncio.get_event_loop().run_until_complete(
  68. websockets.serve(echo, 'localhost', 8765))
  69. asyncio.get_event_loop().run_forever()
  70. Does that look good?
  71. `Get started with the tutorial! <https://websockets.readthedocs.io/en/stable/intro.html>`_
  72. Why should I use ``websockets``?
  73. --------------------------------
  74. The development of ``websockets`` is shaped by four principles:
  75. 1. **Simplicity**: all you need to understand is ``msg = await ws.recv()`` and
  76. ``await ws.send(msg)``; ``websockets`` takes care of managing connections
  77. so you can focus on your application.
  78. 2. **Robustness**: ``websockets`` is built for production; for example it was
  79. the only library to `handle backpressure correctly`_ before the issue
  80. became widely known in the Python community.
  81. 3. **Quality**: ``websockets`` is heavily tested. Continuous integration fails
  82. under 100% branch coverage. Also it passes the industry-standard `Autobahn
  83. Testsuite`_.
  84. 4. **Performance**: memory use is configurable. An extension written in C
  85. accelerates expensive operations. It's pre-compiled for Linux, macOS and
  86. Windows and packaged in the wheel format for each system and Python version.
  87. Documentation is a first class concern in the project. Head over to `Read the
  88. Docs`_ and see for yourself.
  89. .. _Read the Docs: https://websockets.readthedocs.io/
  90. .. _handle backpressure correctly: https://vorpus.org/blog/some-thoughts-on-asynchronous-api-design-in-a-post-asyncawait-world/#websocket-servers
  91. .. _Autobahn Testsuite: https://github.com/aaugustin/websockets/blob/master/compliance/README.rst
  92. Why shouldn't I use ``websockets``?
  93. -----------------------------------
  94. * If you prefer callbacks over coroutines: ``websockets`` was created to
  95. provide the best coroutine-based API to manage WebSocket connections in
  96. Python. Pick another library for a callback-based API.
  97. * If you're looking for a mixed HTTP / WebSocket library: ``websockets`` aims
  98. at being an excellent implementation of :rfc:`6455`: The WebSocket Protocol
  99. and :rfc:`7692`: Compression Extensions for WebSocket. Its support for HTTP
  100. is minimal — just enough for a HTTP health check.
  101. * If you want to use Python 2: ``websockets`` builds upon ``asyncio`` which
  102. only works on Python 3. ``websockets`` requires Python ≥ 3.6.1.
  103. What else?
  104. ----------
  105. Bug reports, patches and suggestions are welcome!
  106. To report a security vulnerability, please use the `Tidelift security
  107. contact`_. Tidelift will coordinate the fix and disclosure.
  108. .. _Tidelift security contact: https://tidelift.com/security
  109. For anything else, please open an issue_ or send a `pull request`_.
  110. .. _issue: https://github.com/aaugustin/websockets/issues/new
  111. .. _pull request: https://github.com/aaugustin/websockets/compare/
  112. Participants must uphold the `Contributor Covenant code of conduct`_.
  113. .. _Contributor Covenant code of conduct: https://github.com/aaugustin/websockets/blob/master/CODE_OF_CONDUCT.md
  114. ``websockets`` is released under the `BSD license`_.
  115. .. _BSD license: https://github.com/aaugustin/websockets/blob/master/LICENSE