NestedTextError

exception nestedtext.NestedTextError(*args, **kwargs)

The load and dump functions all raise NestedTextError when they discover an error. NestedTextError subclasses both the Python ValueError and the Error exception from Inform. You can find more documentation on what you can do with this exception in the Inform documentation.

All exceptions provide the following attributes:

args

The exception arguments. A tuple that usually contains the problematic value.

template

The possibly parameterized text used for the error message.

Exceptions raised by the loads() or load() functions provide the following additional attributes:

source

The source of the NestedText content, if given. This is often a filename.

line

The text of the line of NestedText content where the problem was found.

prev_line

The text of the meaningful line immediately before where the problem was found. This will not be a comment or blank line.

lineno

The number of the line where the problem was found. Line numbers are zero based except when included in messages to the end user.

colno

The number of the character where the problem was found on line. Column numbers are zero based.

codicil

The line that contains the error decorated with the location of the error.

The exception culprit is the tuple that indicates where the error was found. With exceptions from loads() or load(), the culprit consists of the source name, if available, and the line number. With exceptions from dumps() or dump(), the culprit consists of the keys that lead to the problematic value.

As with most exceptions, you can simply cast it to a string to get a reasonable error message.

>>> from textwrap import dedent
>>> import nestedtext as nt

>>> content = dedent("""
...     name1: value1
...     name1: value2
...     name3: value3
... """).strip()

>>> try:
...     print(nt.loads(content))
... except nt.NestedTextError as e:
...     print(str(e))
2: duplicate key: name1.
       1 ❬name1: value1❭
       2 ❬name1: value2❭
          ▲

You can also use the report method to print the message directly. This is appropriate if you are using inform for your messaging as it follows inform’s conventions:

>> try:
..     print(nt.loads(content))
.. except nt.NestedTextError as e:
..     e.report()
error: 2: duplicate key: name1.
    ❬name1: value2❭
     ▲

The terminate method prints the message directly and exits:

>> try:
..     print(nt.loads(content))
.. except nt.NestedTextError as e:
..     e.terminate()
error: 2: duplicate key: name1.
    ❬name1: value2❭
     ▲

With exceptions generated from load() or loads() you may see extra lines at the end of the message that show the problematic lines if you have the exception report itself as above. Those extra lines are referred to as the codicil and they can be very helpful in illustrating the actual problem. You do not get them if you simply cast the exception to a string, but you can access them using NestedTextError.get_codicil(). The codicil or codicils are returned as a tuple. You should join them with newlines before printing them.

>>> try:
...     print(nt.loads(content))
... except nt.NestedTextError as e:
...     print(e.get_message())
...     print(*e.get_codicil(), sep="\n")
duplicate key: name1.
   1 ❬name1: value1❭
   2 ❬name1: value2❭
      ▲

Note the ❬ and ❭ characters in the codicil. They delimit the extent of the text on each line and help you see troublesome leading or trailing white space.

Exceptions produced by NestedText contain a template attribute that contains the basic text of the message. You can change this message by overriding the attribute using the template argument when using report, terminate, or render. render is like casting the exception to a string except that allows for the passing of arguments. For example, to convert a particular message to Spanish, you could use something like the following.

>>> try:
...     print(nt.loads(content))
... except nt.NestedTextError as e:
...     template = None
...     if e.template == "duplicate key: {}.":
...         template = "llave duplicada: {}."
...     print(e.render(template=template))
2: llave duplicada: name1.
       1 ❬name1: value1❭
       2 ❬name1: value2❭
          ▲

get_message(template=None)

Get exception message.

Parameters:

template (str) –

This argument is treated as a format string and is passed both the unnamed and named arguments. The resulting string is treated as the message and returned.

If not specified, the template keyword argument passed to the exception is used. If there was no template argument, then the positional arguments of the exception are joined using sep and that is returned.

Returns:

The formatted message without the culprits.

get_culprit(culprit=None)

Get the culprits.

Culprits are extra pieces of information attached to an error that help to identify the source of the error. For example, file name and line number where the error was found are often attached as culprits.

Return the culprit as a tuple. If a culprit is specified as an argument, it is appended to the exception’s culprit without modifying it.

Parameters:

culprit (string, number or tuple of strings and numbers) – A culprit or collection of culprits that is appended to the return value without modifying the cached culprit.

Returns:

The culprit argument is prepended to the exception’s culprit and the combination is returned. The return value is always in the form of a tuple even if there is only one component.

get_codicil(codicil=None)

Get the codicils.

A codicil is extra text attached to an error that can clarify the error message or to give extra context.

Return the codicil as a tuple. If a codicil is specified as an argument, it is appended to the exception’s codicil without modifying it.

Parameters:

codicil (string or tuple of strings) – A codicil or collection of codicils that is appended to the return value without modifying the cached codicil.

Returns:

The codicil argument is appended to the exception’s codicil and the combination is returned. The return value is always in the form of a tuple even if there is only one component.

report(**new_kwargs)

Report exception to the user.

Prints the error message on the standard output.

The inform.error() function is called with the exception arguments.

Parameters:

**kwargs – report() takes any of the normal keyword arguments normally allowed on an informant (culprit, template, etc.). Any keyword argument specified here overrides those that were specified when the exception was first raised.

terminate(**new_kwargs)

Report exception and terminate.

Prints the error message on the standard output and exits the program.

The inform.fatal() function is called with the exception arguments.

Parameters:

**kwargs – report() takes any of the normal keyword arguments normally allowed on an informant (culprit, template, etc.). Any keyword argument specified here overrides those that were specified when the exception was first raised.

reraise(**new_kwargs)

Re-raise the exception with replaced arguments.

render(template=None, include_codicil=True)

Convert exception to a string for use in an error message.

Parameters:

• template (str) –

  This argument is treated as a format string and is passed both the unnamed and named arguments. The resulting string is treated as the message and returned.

  If not specified, the template keyword argument passed to the exception is used. If there was no template argument, then the positional arguments of the exception are joined using sep and that is returned.

• include_codicil (bool) – Include the codicil in the rendered message.

Returns:

The formatted message with any culprits.