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.
-
status
¶ Get this book’s tag.
Returns: ‘started’, ‘working’, ‘success’, or ‘failure’. Return type: string
-
tag
¶ Get this book’s tag.
-
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 useoutlet()
to turn functions into anOutlets
whose handler is that function. - **kwargs (any) – Keyword arguments passed to
Outlet._handler()
- a method meant to be overriden in subclasses. You can useoutlet()
to turn functions into anOutlets
whose handler is that function.
- style (callable) – A function that returns a formated log string. This is usually a
-
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)
, wherelog
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
.