Utilities

Extras that are useful when using NestedText.

nestedtext.get_value_from_keys(obj, keys)

Get value from keys.

Parameters

• obj – Your data set as returned by load() or loads().

• keys – A tuple of keys taken from a keymap.

Returns

The value that corresponds to a tuple of keys from a keymap.

nestedtext.get_lines_from_keys(obj, keys, keymap, kind='value', sep=None)

Get line numbers from normalized keys.

This function returns the line numbers of the key or value selected by keys. It is used when reporting an error in a value that is possibly a multiline string. If the location contained in a keymap were used the user would only see the line number of the first line, which may confuse some users into believing the error is actually contained in the first line. Using this function gives both the starting and ending line number so the user focuses on the whole string and not just the first line.

If sep is given, either one line number or both the beginning and ending line numbers are given, joined with the separator. In this case the line numbers start from line 1.

If sep is not given, the line numbers are returned as a tuple containing a pair of integers that is tailored to be suitable to be arguments to the Python slice function (see example). The beginning line number and 1 plus the ending line number is returned as a tuple. In this case the line numbers start at 0.

If the value is requested and it is a composite (a dictionary or list), the line on which it ends cannot be easily determined, so the value is treated as if it consists of a single line. This is considered tolerable as it is expected that this function is primarily used to return the line number of leaf values, which are always strings.

Parameters

• obj – Your data set as returned by load() or loads().

• keys – The collection of keys that identify a value in the dataset.

• keymap – The keymap returned from load() or loads().

• kind (str) – Specify either ‘key’ or ‘value’ depending on which token is desired.

• sep – The separator string. If given a string is returned and sep is inserted between two line numbers. Otherwise a tuple is returned.

Example

>>> import nestedtext as nt

>>> doc = '''
... key:
...     > this is line 1
...     > this is line 2
...     > this is line 3
... '''

>>> data = nt.loads(doc, keymap=(keymap:={}))
>>> keys = ("key",)
>>> lines = nt.get_lines_from_keys(data, keys, keymap, sep="-")
>>> text = doc.splitlines()
>>> print(
...     f"Lines {lines}:",
...     *text[slice(*nt.get_lines_from_keys(data, keys, keymap))],
...     sep="\n"
... )
Lines 3-5:
    > this is line 1
    > this is line 2
    > this is line 3

nestedtext.get_original_keys(keys, keymap, strict=False)

Get original keys from normalized keys.

Parameters

• keys – The collection of keys that identify a value in the dataset.

• keymap – The keymap returned from load() or loads().

• strict – If true, a KeyError will be raised if the given keys are not found in the keymap. Otherwise, the given key will be returned rather than the original key. This is helpful when reporting errors on required keys that do not exist in the data set. Since they are not in the dataset, no original key is available.

Returns

A tuple containing the original keys names.

nestedtext.join_keys(keys, sep=', ', keymap=None)

Joins the keys into a string.

Parameters

• keys – A tuple of keys.

• sep – The separator string. It is inserted between each key during the join.

• keymap – The keymap returned from load() or loads(). It is optional. If given the given keys are converted to the original keys before the joining.

Returns

A string containing the joined keys.