docs: logging and the context

4 files changed, 44 insertions, 24 deletions

diff --git a/docs/index.rst b/docs/index.rst
index 9a948678..cd32a1f6 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -52,7 +52,6 @@
     :caption: Scripting
 
     scripting/overview
-    scripting/context
     scripting/events
     scripting/api
 
diff --git a/docs/scripting/api.rst b/docs/scripting/api.rst
index a864b442..abc9ff3e 100644
--- a/docs/scripting/api.rst
+++ b/docs/scripting/api.rst
@@ -4,12 +4,22 @@
 API
 ===
 
+- Errors
+    - `mitmproxy.models.flow.Error <#mitmproxy.models.flow.Error>`_
 - HTTP
     - `mitmproxy.models.http.HTTPRequest <#mitmproxy.models.http.HTTPRequest>`_
     - `mitmproxy.models.http.HTTPResponse <#mitmproxy.models.http.HTTPResponse>`_
     - `mitmproxy.models.http.HTTPFlow <#mitmproxy.models.http.HTTPFlow>`_
-- Errors
-    - `mitmproxy.models.flow.Error <#mitmproxy.models.flow.Error>`_
+- Logging
+    - `mitmproxy.controller.Log <#mitmproxy.controller.Log>`_
+    - `mitmproxy.controller.LogEntry <#mitmproxy.controller.LogEntry>`_
+
+
+Errors
+------
+
+.. autoclass:: mitmproxy.models.flow.Error
+    :inherited-members:
 
 HTTP
 ----
@@ -23,8 +33,8 @@ HTTP
 .. autoclass:: mitmproxy.models.http.HTTPFlow
     :inherited-members:
 
-Errors
-------
+Logging
+--------
 
-.. autoclass:: mitmproxy.models.flow.Error
+.. autoclass:: mitmproxy.controller.Log
     :inherited-members:
diff --git a/docs/scripting/context.rst b/docs/scripting/context.rst
deleted file mode 100644
index 7c351598..00000000
--- a/docs/scripting/context.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-.. _context:
-
-Context
-=======
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
+------------------