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_trailing_comments()

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

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_trailing_comments()

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

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_spacing(spacing)

Replace the per-Location spacing dict.