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, level: int)

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 iterators over error and warnings.

abstract add_subsections(*labels: str) → Sequence[Notepad]

Add a sequence/chain of subsections.

Parameters:

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

abstract iter_sections() → Iterator[Notepad]

Iterate over nodes in the depth-first fashion.

Returns: a depth-first iterator over Notepad nodes.

add_subsection(label: str) → Notepad

Add a single labeled subsection.

Parameters:

label – a label to use for the new subsection.

property label: str

Get the section label.

property level: int

Get the level of the notepad node (distance from the top-level hierarchy node).

property issues: Sequence[Issue]

Get an iterable with the issues of the current section.

add_issue(level: Level, message: str, solution: str | None = None)

Add an issue with certain level, message, and an optional solution.

add_error(message: str, solution: str | None = None)

A convenience function for adding an error with a message and an optional solution.

errors() → Iterator[Issue]

Iterate over the errors of the current section.

error_count() → int

Returns:

count of errors found in this section.

Return type:

int

has_errors(include_subsections: bool = False) → bool

Returns:

True if one or more errors were found in the current section or its subsections.

Return type:

bool

add_warning(message: str, solution: str | None = None)

A convenience function for adding a warning with a message and an optional solution.

warnings() → Iterator[Issue]

Iterate over the warnings of the current section.

has_warnings(include_subsections: bool = False) → bool

Returns:

True if one or more warnings were found in the current section or its subsections.

Return type:

bool

warning_count() → int

Returns:

count of warnings found in this section.

Return type:

int

has_errors_or_warnings(include_subsections: bool = False) → bool

Returns:

True if one or more errors or warnings were found in the current section or its subsections.

Return type:

bool

visit(visitor: Callable[[Notepad], None])

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.

summarize(file: ~io.TextIOBase = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, indent: int = 2)

stairval.notepad.create_notepad(label: str) → Notepad

Create a default notepad.

Parameters:

label – the label of the notepad