API¶

class jotting.book.book(title, parent=None, **content)[source]¶

Create a new book for logging.

Parameters:

title (string, function, or class) – A string representing the title of the book. For functions and classes, a title is infered from its title, and module. Inference attempt to drill down into closures to determin the root function, or class. This typically happens when a function or class has many decorators.
parent (string or None) – The tag of the last book. If None then the last book within the current thread is used. To link across threads or processes, you must manually communicate this.
**content (any) – A dictionary of content that will be logged when the book is opened.

classmethod conclude(*args, **kwargs)[source]¶: Write the content that will be logged when the book closes.

classmethod current(data=None)[source]¶

Get the current book, or metadata from the current book.

Parameters:	data (string or None) – A string indicating a desired piece of metadata from the current book. If `None`, then the current book is returned instead.
Returns:	The current book, or an entry in its metadata.
Return type:	`book`

classmethod distribute(*outlets)[source]¶: Set which jotting.to.Outlet objects recieve logs.

metadata¶: Get a copy of this book’s metadata.

classmethod outlets()[source]¶: Get the outlets for all books.

status¶

Get this book’s tag.

Returns:	‘started’, ‘working’, ‘success’, or ‘failure’.
Return type:	string

tag¶: Get this book’s tag.

classmethod write(*args, **kwargs)[source]¶: Write a log to the currently open book.

class jotting.to.Outlet(style=<jotting.style.Raw object>, *args, **kwargs)[source]¶

A base Outlet class.

Subclasses should override the _handler() method.

Parameters:

style (callable) – A function that returns a formated log string. This is usually a jotting.to.Style object that returns a string.
*args (any) – Positional arguments passed to Outlet._handler() - a method meant to be overriden in subclasses. You can use outlet() to turn functions into an Outlets whose handler is that function.
**kwargs (any) – Keyword arguments passed to Outlet._handler() - a method meant to be overriden in subclasses. You can use outlet() to turn functions into an Outlets whose handler is that function.

jotting.to.outlet(handler)[source]¶

Turn a function into an Outlet.

This decorator should wrap functions that send logs wherever they need to go.

Parameters:	handler (callable) – A function of the form `(log, args, kwargs)`, where `log` is a log generated by a user, and `args, **kwargs` are the parameters that initialize the outlet (e.g. `File(path=/path/to/file)`).

class jotting.read.Complete(source)[source]¶

Read a complete set of logs from a file or list of dictionaries.

This class will organize a given set of logs such that they are contextually, but not necessarilly chronologically ordered. You can get a string representation of the given logs styled as a jotting.style.Tree simply by converting it to a string (e.g. str(Complete(my_source))), or you can iterate over the reordered logs (e.g. list(Complete(my_source))) and style them yourself later.

Parameters:	source (string or iterable containing log strings) – If given as a string `source` will be interpreted as a filepath. Otherwise source should it should be a list of log strings.

class jotting.read.Stream(*outlets)[source]¶

Read a stream of log strings or dictionaries.

Parameters:	outlets (callable*) – A series of callable `Outlet` objects that will receive logs one at a time. Logs will be collected and then distributed in batches, in order to make guesses about causes and effects. This only works for logs that were created synchronously.

Notes

The stream attempts to make educated guesses about causes and effects. In other words, it will attempt to reorder the logs. This works well for logs that were synchronously created.

For logs created in parrallel threads or processes, you should store your logs in a file, and read them back with Complete.

class jotting.style.Log[source]¶: A basic formater that only creates successes, and failures.

class jotting.style.Raw[source]¶: Creates a string representation of the log object.

class jotting.style.Style[source]¶: The base Style type.

class jotting.style.Tree[source]¶: An ascii tree representation for logs.