stairval.notepad package

The module includes the Notepad API and the default implementation backed by a tree (not public).

Example

Create a new notepad with a top-level label order:

>>> from stairval.notepad import Notepad, create_notepad
>>> notepad = create_notepad('order')
>>> notepad.label
'order'

class stairval.notepad.Notepad(label: str | int, level: int)[source]

Bases: object

Record issues encountered during parsing/validation of a hierarchical data structure.

The issues can be organized in sections. Notepad keeps track of issues in one section and the subsections can be created by calling add_subsection(). The function returns an instance responsible for issues of a subsection.

A collection of the issues from the current section are available via issues property and the convenience functions provide iterables over error and warnings.

add_error(message: str, solution: str | None = None)[source]: A convenience function for adding an error with a message and an optional solution.

add_issue(level: Level, message: str, solution: str | None = None)[source]: Add an issue with certain level, message, and an optional solution.

add_subsection(label: str | int) → Notepad[source]

Add a single labeled subsection.

>>> from stairval.notepad import create_notepad
>>> foo = create_notepad('foo')
>>> bar = foo.add_subsection('bar')
>>> bar.label
'bar'

If a subsection with the label already exists, then it is returned.

>>> bar2 = foo.add_subsection('bar')
>>> bar2 is bar
True

Parameters:: label – a label to use for the new subsection.

abstractmethod add_subsections(*labels: str | int) → Sequence[Notepad][source]

Add a sequence/chain of subsections.

>>> from stairval.notepad import create_notepad
>>> foo = create_notepad('foo')
>>> subs = foo.add_subsections('bar', 0, 'baz')
>>> len(subs)
3

Already existing subsections are not re-created:

>>> subs2 = foo.add_subsections('bar', 0, 'bam')
>>> subs[0] is subs2[0]
True
>>> subs[1] is subs2[1]
True
>>> subs[2] is subs2[2]
False

Parameters:: labels – a sequence of labels for the new notepad subsections.

add_warning(message: str, solution: str | None = None)[source]: A convenience function for adding a warning with a message and an optional solution.

error_count() → int[source]

Returns:: count of errors found in this section.
Return type:: int

errors() → Iterable[Issue][source]: Iterate over the errors of the current section.

abstractmethod get_subsections() → Sequence[Notepad][source]

Get a sequence with subsections.

Returns: a sequence of the subsection nodes.

has_errors(include_subsections: bool = False) → bool[source]

Returns:: True if one or more errors were found in the current section or its subsections.
Return type:: bool

has_errors_or_warnings(include_subsections: bool = False) → bool[source]

Returns:: True if one or more errors or warnings were found in the current section or its subsections.
Return type:: bool

has_subsections() → bool[source]

Returns:: if the notepad has one or more subsections.
Return type:: True

has_warnings(include_subsections: bool = False) → bool[source]

Returns:: True if one or more warnings were found in the current section or its subsections.
Return type:: bool

property issues: Sequence[Issue]: Get an iterable with the issues of the current section.

iter_sections() → Iterable[Notepad][source]

Iterate over nodes in the depth-first fashion.

The iterable also includes the current node.

Returns: a depth-first iterable over Notepad nodes.

property label: str | int: Get the section label.

property level: int: Get the level of the notepad node (distance from the root node, which has the level of 0).

summarize(file: ~typing.TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, indent: int = 2)[source]

Summarize the notepad into file (STDOUT by default).

Parameters:

file – a TextIO-like object to write the summary into (STDOUT by default).
indent – the number of spaces to delimit the notepad subsections (default: 2).

summary(indent: int = 2) → str[source]

Summarize the notepad into a str.

Parameters:: indent – the number of spaces to delimit the notepad subsections (default: 2).
Returns:: The notepad summary.

visit(visitor: Callable[[Notepad], None])[source]: Performs a depth-first search on the notepad nodes and calls visitor with all nodes. :param visitor: a callable that takes the current notepad node as the only argument.

warning_count() → int[source]

Returns:: count of warnings found in this section.
Return type:: int

warnings() → Iterable[Issue][source]: Iterate over the warnings of the current section.

stairval.notepad.create_notepad(label: str) → Notepad[source]

Create a default notepad.

Parameters:: label – the label of the notepad