diff options
author | Aldo Cortesi <aldo@nullcube.com> | 2016-10-16 12:03:57 +1300 |
---|---|---|
committer | Aldo Cortesi <aldo@nullcube.com> | 2016-10-16 20:26:06 +1300 |
commit | 55cb2a85472de8698b3dabc7ddc920b930e355d9 (patch) | |
tree | d71682210fdae6456edda25d5df2af5e55a5f724 /docs/scripting/overview.rst | |
parent | a6c7a1ff918c5aa0285decb995096190888a2f51 (diff) | |
download | mitmproxy-55cb2a85472de8698b3dabc7ddc920b930e355d9.tar.gz mitmproxy-55cb2a85472de8698b3dabc7ddc920b930e355d9.tar.bz2 mitmproxy-55cb2a85472de8698b3dabc7ddc920b930e355d9.zip |
docs: logging and the context
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 +------------------ |