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.

write(self, level, text)

Write text with log level level to the log.

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

Create file object.


list of weak references to the object (if defined)

class nutils.log.DataLog(outdir)

Bases: nutils.log.Log

Output only data.

class nutils.log.CWDLog

Bases: nutils.log.Log

Output only data in de current working directory. This is different from DataLog(os.getcwd). if the current working directory changes afterwards.

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.


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.


This function is abstract.


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.


This function is abstract.

_print_item(self, level, text)

Add an item to the log.


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, *, verbose=4)

Bases: nutils.log.ContextLog

Output plain text to stream.

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

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=0.1)

Bases: nutils.log.ContextTreeLog

Output indented html snippets.

class nutils.log.TeeLog(*logs)

Bases: nutils.log.Log

Simultaneously interface multiple logs

Deprecated since version 5.0: The functionality is merged into nutils.log: multiple class:Log objects can be active at the same time and any can be (de)activated independently.

class nutils.log.RecordLog

Bases: nutils.log.Log

Log object that records log messages. The recorded messages can be replayed to the logs that are 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)


Instead of using RecordLog and pickle manually, as in the above example, we advice to use nutils.cache.function() or nutils.cache.Recursion instead.


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


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


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


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.

Deprecated since version 5.0.


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.

  • 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.