logstack Documentation Release 0.1 Remi Rampin Apr 08, 2017
Contents 1 Getting started 1 2 Contents 3 2.1 Reference................................................. 3 2.2 Internal reference............................................. 4 3 Links 7 4 Indices and tables 9 Python Module Index 11 i
ii
CHAPTER 1 Getting started This simple example will show you how to setup logging and logstack and log some simple messages to the console, with context: import logging, logstack console = logging.streamhandler() console.setformatter(logstack.formatter()) logging.getlogger().addhandler(console) def bar(): logstack.push("doing stuff", in_bar=true) # irrelevant context def baz(): logstack.push(in_baz=true) # relevant context with logstack.pushed(something=[1, 2, 3]): # context for debug(), logging.debug("in block") # discarded with it raise ValueError("ohno") def foo(): logstack.push("starting up", in_foo=true) # relevant context bar() baz() try: foo() except: logging.critical("got an exception!", exc_info=true) # triggers logging In this example, the following trace will be printed: Got an exception! Traceback (most recent call last): File "getting_started.py", line 23, in <module> foo() File "getting_started.py", line 20, in foo starting up (in_foo=true) baz() File "getting_started.py", line 15, in baz 1
logstack Documentation, Release 0.1 (in_baz=true) raise ValueError("ohno") ValueError: ohno Here, the doing stuff (in_bar=true) message was not displayed because the function finished without logging anything. This makes the logfile much clearer because contextual information stays contextual, i.e. is only shown to shed light on an actual event. Note that, except when pushing contexts, the standard logging module is used; though a special Formatter with the custom traceback logic must be used. 2 Chapter 1. Getting started
CHAPTER 2 Contents Reference logstack is a very simple modules made up of different components: the formatter, which allows the context stack to be printed from the logging module, the stack-manipulating methods: push() and pushed(), and the context class, set through set_context_class(). Contexts Contexts are the objects that are pushed onto the logging stack. When you call logstack.push(), the arguments are simply passed to the context class to build an instance that is stored on the stack. That class thus determines the signature of context-pushing methods; its str () method determines how the contexts are rendered. logstack.set_context_class(cls) Changes the class used to build/format contexts. This class gets passed the arguments that were given to push() or pushed(), and is converted to a string to be put in the traceback. The default is DefaultContext which takes a message and keyword parameters. class logstack.defaultcontext(msg=none, **kwargs) Default context formatter. It takes an optional message and any number of parameters, passed as keyword arguments. For example, using: logstack.push("opening a file", filename="foo.txt", mode="r") will display: Opening a file (filename="foo.txt", mode="r") 3
logstack Documentation, Release 0.1 Manipulating the stack In order for this module to have any effect, you need to add context information. This information is associated with the stack, which means that the context you add will be discarded when the current function returns. This is so that when logging happens, only the relevant information gets printed alongside the original message. You don t want to see what went right, you just want to know what was going on when something wrong happens. logstack.push(*args, **kwargs) Push some context onto the stack. You don t have to pop this, it is associated with the caller s stack frame. logstack.pushed(*args, **kwargs) Push some context onto the stack. The context is removed when leaving the context manager. Internal reference class logstack.exceptionformattermixin Logging formatter that inserts the context objects in the traceback. class logstack.formatter(*args, **kwargs) Version of logging.formatter with the custom traceback. logstack.set_context_class(cls) Changes the class used to build/format contexts. This class gets passed the arguments that were given to push() or pushed(), and is converted to a string to be put in the traceback. The default is DefaultContext which takes a message and keyword parameters. logstack.push(*args, **kwargs) Push some context onto the stack. You don t have to pop this, it is associated with the caller s stack frame. class logstack.pushed(*args, **kwargs) Push some context onto the stack. The context is removed when leaving the context manager. class logstack.framelocal.framelocalcontextstorage Implementation of context storage that uses a stackframe s locals. This creates a logstack_frame_contexts local in the scope where push() is called. It is a list that contains the pushed contexts. This way, they are tied with the lifetime of the frame and can be easily accessed while walking up a traceback. No actual data is stored in here. Thread safety is provided by Python. get(frame) Returns the list of contexts associated with the stack frame. remove(frame, ctx) Removes a specific context from a stack frame. Raises ValueError if there was no such context. 4 Chapter 2. Contents
logstack Documentation, Release 0.1 set(frame, ctx) Associate a new context with the stack frame. 2.2. Internal reference 5
logstack Documentation, Release 0.1 6 Chapter 2. Contents
CHAPTER 3 Links The excellent standard logging module The structlog library, similar in some ways 7
logstack Documentation, Release 0.1 8 Chapter 3. Links
CHAPTER 4 Indices and tables genindex modindex search 9
logstack Documentation, Release 0.1 10 Chapter 4. Indices and tables
Python Module Index l logstack, 4 logstack.framelocal, 4 11
logstack Documentation, Release 0.1 12 Python Module Index
Index E ExceptionFormatterMixin (class in logstack), 4 F Formatter (class in logstack), 4 FrameLocalContextStorage (class in logstack.framelocal), 4 G get() (logstack.framelocal.framelocalcontextstorage method), 4 L logstack (module), 4 logstack.framelocal (module), 4 P push() (in module logstack), 4 pushed (class in logstack), 4 R remove() (logstack.framelocal.framelocalcontextstorage method), 4 S set() (logstack.framelocal.framelocalcontextstorage method), 4 set_context_class() (in module logstack), 4 13