docs: logging and the context

docs/index.rst

@@ -52,7 +52,6 @@
     :caption: Scripting
 
     scripting/overview
-    scripting/context
     scripting/events
     scripting/api
 

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:

docs/scripting/context.rst

@@ -1,4 +0,0 @@
-.. _context:
-
-Context
-=======

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
+-----------
 
-.. _GitHub: https://github.com/mitmproxy/mitmproxy
+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
+
+
+
+Developing scripts
+------------------

examples/logging.py

@@ -0,0 +1,6 @@
+from mitmproxy import ctx
+
+
+def start():
+    ctx.log.info("This is some informative text.")
+    ctx.log.error("This is an error.")

mitmproxy/controller.py

@@ -49,24 +49,39 @@ class LogEntry(object):
 
 
 class Log(object):
+    """
+        The central logger, exposed to scripts as mitmproxy.ctx.log.
+    """
     def __init__(self, master):
         self.master = master
 
-    def __call__(self, text, level="info"):
-        self.master.add_log(text, level)
-
     def debug(self, txt):
+        """
+            Log with level debug.
+        """
         self(txt, "debug")
 
     def info(self, txt):
+        """
+            Log with level info.
+        """
         self(txt, "info")
 
     def warn(self, txt):
+        """
+            Log with level warn.
+        """
         self(txt, "warn")
 
     def error(self, txt):
+        """
+            Log with level error.
+        """
         self(txt, "error")
 
+    def __call__(self, text, level="info"):
+        self.master.add_log(text, level)
+
 
 class Master(object):
     """