Skip to content

Commit

Permalink
docs/python: Point users at WebSocket
Browse files Browse the repository at this point in the history
Users on Slack somewhat regularly ask questions around how to use the Python
bindings and finding quirks with it. Just for us to tell them they
should be using WebSockets instead. These might not be perfect, but at
least we're open to hear feedback and improve them, which isn't
necessarily our stance for the Python bindings.

Put up a big banner to redirect users into the future. Seems "warning" is
warranted given our reluctance and future ideas around deprecation for
the bindings.
  • Loading branch information
awelzel committed Mar 18, 2024
1 parent 861c206 commit 4bc2f86
Showing 1 changed file with 10 additions and 0 deletions.
10 changes: 10 additions & 0 deletions doc/python.rst
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,16 @@
Python Bindings
===============

.. warning::

To interact with Zeek, Broker's Python bindings should almost never be the
first choice nowadays. Consider them deprecated for most purposes. When setting
out to develop a new integration with Zeek, consider using :ref:`WebSockets <web-socket>`
instead. They avoid pitfalls during deployment and upgrades related to binary
compatiblity. For debugging purposes, the WebSocket protocol (in plaintext)
is easier to introspect and monitor on the wire, too.


Almost all functionality of Broker is also accessible through Python
bindings. The Python API mostly mimics the C++ interface, but adds
transparent conversion between Python values and Broker values. In the
Expand Down

0 comments on commit 4bc2f86

Please sign in to comment.