Location

Location objects are returned from load() and loads() as the values in a keymap. They are also returned by get_location(). Objects of this class holds the line and column numbers of the key and value tokens.

class nestedtext.Location(line=None, col=None, key_line=None, key_col=None)

Holds information about the location of a token.

Returned from load() and loads() as the values in a keymap. Objects of this class holds the line and column numbers of the key and value tokens.

add_footer_comment(comment)

Append a Comment to the document’s footer.

add_header_comment(comment)

Append a Comment to the document’s header.

add_key_leading_comment(comment)

Append a Comment to the leading list for this key.

as_line(kind='value', offset=0)

Returns a string containing two lines that identify the token in context. The first line contains the line number and text of the line that contains the token. The second line contains a pointer to the token.

Parameters:

• kind – Specify either “key” or “value” depending on which token is desired.

• offset – If offset is None, the error pointer is not added to the line. If offset is an integer, the pointer is moved to the right by this many characters. The default is 0. If offset is a tuple, it must have two values. The first is the row offset and the second is the column offset. This is useful for annotating errors in multiline strings.

Raises:

*IndexError* if row offset is out of range. –

as_tuple(kind='value')

Returns the location of either the value or the key token as a tuple that contains the line number and the column number. The line and column numbers are 0 based.

Parameters:

kind – Specify either “key” or “value” depending on which token is desired.

get_footer_comments()

Return the document’s footer Comments.

Footer comments only ever live on the document-root Location, i.e., keymap[()]. On any other Location this list is empty.

get_header_comments()

Return the document’s header Comments.

Header comments only ever live on the document-root Location, i.e., keymap[()]. On any other Location this list is empty.

get_key_leading_comments()

Return the leading Comments associated with this key.

get_key_leading_provider()

Return the per-child key_leading provider callable, if any.

A provider has the signature

provider(child_key) -> list[Comment]

where child_key is the dict key (or list index) of one of this Location’s children. When this Location’s value is rendered the dumper invokes the provider for every child, and prepends the returned Comments to that child’s static get_key_leading_comments() list. Closures over the callable’s state can dedup or build Comments dynamically.

Returned Comments whose tab is None are normalized to tab=0 at emit time (natural indent). Providers are callables and are not JSON-serializable; they are dropped on keymap_to_jsonable() round-trips.

get_key_trailing_comments()

Return Comments between the key line and the value line (multiline case).

get_key_trailing_provider()

Return the per-child key_trailing provider; see get_key_leading_provider() for semantics.

get_line_numbers(kind='value', sep=None)

Returns the line numbers of a token either as a pair of integers or as a string.

Parameters:

• kind – 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. In this case the line numbers start at 1.

  If sep is not given, a tuple of integers is returned. In this case the line numbers start at 0, but the second number returned is the last line number plus 1. This form is suitable to use with the Python slice function to extract the lines from the NestedText source.

get_spacing()

Return the per-Location spacing dict (empty if none was set).

When non-empty, this dict replaces the dumps() spacing argument for this Location’s entire subtree. Integer keys count relative depth below this Location: 0 is the number of blank lines between this Location’s direct children, 1 between its grandchildren, and so on. Absent depth keys default to 0 – the global spacing is not consulted as a fallback.

The "edges" key is only consulted on the document-root Location (keymap[()]); it is ignored elsewhere.

get_value_leading_comments()

Return Comments leading the value (multiline case).

get_value_leading_provider()

Return the per-child value_leading provider; see get_key_leading_provider() for semantics.

get_value_trailing_comments()

Return Comments trailing the value (after its last line).

get_value_trailing_provider()

Return the per-child value_trailing provider; see get_key_leading_provider() for semantics.

set_footer_comments(comments)

Replace the document’s footer Comments.

set_header_comments(comments)

Replace the document’s header Comments.

set_key_leading_comments(comments)

Replace the leading Comments for this key.

set_key_leading_provider(provider)

Replace the per-child key_leading provider callable.

Pass None to clear it. See get_key_leading_provider() for the expected callable signature.

set_key_trailing_provider(provider)

Replace the per-child key_trailing provider callable.

set_spacing(spacing)

Replace the per-Location spacing dict.

set_value_leading_provider(provider)

Replace the per-child value_leading provider callable.

set_value_trailing_provider(provider)

Replace the per-child value_trailing provider callable.