diff options
Diffstat (limited to 'docs/scripting/overview.rst')
| -rw-r--r-- | docs/scripting/overview.rst | 43 |
1 files changed, 29 insertions, 14 deletions
diff --git a/docs/scripting/overview.rst b/docs/scripting/overview.rst index f8dd9f2e..a3b83e44 100644 --- a/docs/scripting/overview.rst +++ b/docs/scripting/overview.rst @@ -74,18 +74,24 @@ Whenever a handler is called, mitpmroxy rewrites the script environment so that it sees its own arguments as if it was invoked from the command-line. -Running scripts in parallel ---------------------------- +Logging and the context +----------------------- -We have a single flow primitive, so when a script is blocking, other requests are not processed. -While that's usually a very desirable behaviour, blocking scripts can be run threaded by using the -:py:obj:`mitmproxy.script.concurrent` decorator. -**If your script does not block, you should avoid the overhead of the decorator.** +Scripts should not output straight to stderr or stdout. Instead, the `log +<api.html#mitmproxy.controller.Log>`_ object on the ``ctx`` contexzt module +should be used, so that the mitmproxy host program can handle output +appropriately. So, mitmdump can print colorised sript output to the terminal, +and mitmproxy console can place script output in the event buffer. -.. literalinclude:: ../../examples/nonblocking.py - :caption: examples/nonblocking.py +Here's how this looks: + +.. literalinclude:: ../../examples/logging.py + :caption: :src:`examples/logging.py` :language: python +The ``ctx`` module also exposes the mitmproxy master object at ``ctx.master`` +for advanced usage. + Running scripts on saved flows ------------------------------ @@ -101,11 +107,20 @@ In this case, there are no client connections, and the events are run in the fol If the flow doesn't have a **response** or **error** associated with it, the matching events will be skipped. -Spaces in the script path -------------------------- -By default, spaces are interpreted as a separator between the inline script and its arguments -(e.g. ``-s 'foo.py 42'``). Consequently, the script path needs to be wrapped in a separate pair of -quotes if it contains spaces: ``-s '\'./foo bar/baz.py\' 42'``. +Concurrency +----------- + +We have a single flow primitive, so when a script is blocking, other requests +are not processed. While that's usually a very desirable behaviour, blocking +scripts can be run threaded by using the :py:obj:`mitmproxy.script.concurrent` +decorator. + +.. literalinclude:: ../../examples/nonblocking.py + :caption: :src:`examples/nonblocking.py` + :language: python + -.. _GitHub: https://github.com/mitmproxy/mitmproxy + +Developing scripts +------------------ |