log

The log module provides print methods debug, info, user, warning, and error, in increasing order of priority. Output is sent to stdout as well as to an html formatted log file if so configured.

class nutils.log.Log

Bases: object

Base class for log objects. A subclass should define a context() method that returns a context manager which adds a contextual layer and a write() method.

context(self, title, mayskip=False)

Return a context manager that adds a contextual layer named title.

Note

This function is abstract.

write(self, level, text)

Write text with log level level to the log.

Note

This function is abstract.

open(self, filename, mode, level, exists)

Create file object.

__weakref__

list of weak references to the object (if defined)

class nutils.log.DataLog(outdir)

Bases: nutils.log.Log

Output only data.

class nutils.log.ContextLog

Bases: nutils.log.Log

Base class for loggers that keep track of the current list of contexts.

The base class implements context() which keeps the attribute _context up-to-date.

_context

A list of contexts (strs) that are currently active.

context(self, title, mayskip=False)

Return a context manager that adds a contextual layer named title.

The list of currently active contexts is stored in _context.

class nutils.log.ContextTreeLog

Bases: nutils.log.ContextLog

Base class for loggers that display contexts as a tree.

_print_push_context(self, title)

Push a context to the log.

This method is called just before the first item of this context is added to the log. If no items are added to the log within this context or children of this context this method nor _print_pop_context() will be called.

Note

This function is abstract.

_print_pop_context(self)

Pop a context from the log.

This method is called whenever a context is exited, but only if _print_push_context() has been called before for the same context.

Note

This function is abstract.

_print_item(self, level, text)

Add an item to the log.

Note

This function is abstract.

write(self, level, text, **kwargs)

Write text with log level level to the log.

This method makes sure the current context is printed and calls _print_item().

class nutils.log.StdoutLog(stream=None)

Bases: nutils.log.ContextLog

Output plain text to stream.

class nutils.log.RichOutputLog(stream=None, *, progressinterval=None)

Bases: nutils.log.StdoutLog

Output rich (colored,unicode) text to stream.

class nutils.log.HtmlLog(outdir, *, title='nutils', scriptname=None, funcname=None, funcargs=None)

Bases: nutils.log.ContextTreeLog

Output html nested lists.

class nutils.log.IndentLog(outdir, *, progressinterval=None)

Bases: nutils.log.ContextTreeLog

Output indented html snippets.

class nutils.log.TeeLog(*logs)

Bases: nutils.log.Log

Simultaneously interface multiple logs

class nutils.log.RecordLog

Bases: nutils.log.Log

Log object that records log messages. All messages are forwarded to the log that whas active before activating this log (e.g. by with RecordLog() as record:). The recorded messages can be replayed to the log that’s currently active by replay().

Typical usage is caching expensive operations:

# compute
with RecordLog() as record:
  result = compute_something_expensive()
raw = pickle.dumps((record, result))
# reuse
record, result = pickle.loads(raw)
record.replay()

Note

Instead of using RecordLog and pickle manually, as in above example, we advice to use nutils.cache.FileCache instead.

Note

Exceptions raised while in a Log.context() are not recorded.

Note

Messages dispatched from forks (e.g. inside nutils.parallel.pariter()) are not recorded.

replay(self)

Replay this recorded log in the log that’s currently active.

nutils.log.range(title, *args)

Progress logger identical to built in range

nutils.log.iter(title, iterable, length=None)

Progress logger identical to built in iter

nutils.log.enumerate(title, iterable)

Progress logger identical to built in enumerate

nutils.log.zip(title, *iterables)

Progress logger identical to built in enumerate

nutils.log.count(title, start=0, step=1)

Progress logger identical to itertools.count

nutils.log.title(f)

Decorator, adds title argument with default value equal to the name of the decorated function, unless argument already exists. The title value is used in a static log context that is destructed with the function frame.

nutils.log.withcontext(f)

Decorator; executes the wrapped function in its own logging context.

nutils.log.open(filename, mode, *, level='user', exists='rename')

Open file in logger-controlled directory.

Parameters:
  • filename (str) –
  • mode (str) – Should be either 'w' (text) or 'wb' (binary data).
  • level (str) – Log level in which the filename is displayed. Default: 'user'.
  • exists (str) –

    Determines how existence of filename in the output directory should be handled. Valid values are:

    • 'overwrite': open the file and remove current contents.
    • 'rename': change the filename by adding the smallest positive suffix n for which filename-n.ext does not exist.
    • 'skip': return a dummy file object with attribute devnull set to False to allow content creation to be skipped altogether.