From 90233a0a42c452699791a4da352f2afed83da50f Mon Sep 17 00:00:00 2001 From: Arne Welzel Date: Mon, 18 Mar 2024 10:28:42 +0100 Subject: [PATCH] docs/python: Point users at WebSocket 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. --- doc/python.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/doc/python.rst b/doc/python.rst index c655ace82..a06f781b4 100644 --- a/doc/python.rst +++ b/doc/python.rst @@ -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 ` + instead. They are cross-platform, avoid pitfalls during deployment and upgrades + related to binary compatiblity. For debugging purposes, the WebSocket protocol + (in plaintext) is easier to introspect and monitor, 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