Specs

Parameter specifications for export and serialisation


from svetlanna.specs import ...

Classes

ParameterSaveContext

Generates different context managers that can be used to write a parameter data to output stream or file.

Methods

__init__ constructor


__init__(self, parameter_name: str, directory: Path)

📥 Parameters

Parameter	Type	Description
`parameter_name`	`str`	the human-readable name for the parameter
`directory`	`str`	the directory where the generated file will be saved, if any
`stream`	`TextIO`	stream where the generated text will be written, if any

get_new_filepath


get_new_filepath(self, extension: str) -> Path

Create a new filepath for a specific extension. The generated filename of a specific extension will have a unique name ending with _<n>.<extension>, where <n> is auto-incrementing index.

📥 Parameters

Parameter	Type	Description
`extension`	`str`	filename extension

📤 Returns

Path

relative path to the file

rel_filepath


rel_filepath(self, filepath: Path) -> Path

Get relative to specs file filepath

📥 Parameters

Parameter	Type	Description
`filepath`	`Path`	absolute path

📤 Returns

Path

relative path

file


file(self, filepath: Path) -> Generator[BufferedWriter, Any, None]

Context manager for the output file

📥 Parameters

Parameter	Type	Description
`filepath`	`Path`	filepath

Yields

Generator[BufferedWriter, Any, None] — Buffer

Representation

Inherits: Generic[ParameterSaveContext_]

Base class for a parameter representation

MarkdownRepresentation

Inherits: Representation[ParameterSaveContext_]

Representation that can be exported to markdown file

Methods

to_markdown


to_markdown(self, out: TextIO, context: ParameterSaveContext_) -> None

Write the parameter related data to be shown in a markdown file. The text should be written to the out stream.

📥 Parameters

Parameter	Type	Description
`out`	`TextIO`	output text stream
`context`	`ParameterSaveContext_`	the parameter save context

StrRepresentation

Inherits: Representation[ParameterSaveContext_]

Representation that can be exported in the text format

Methods

to_str


to_str(self, out: TextIO, context: ParameterSaveContext_) -> None

Write the parameter related data to be shown as a plain text. The text should be written to the out stream.

📥 Parameters

Parameter	Type	Description
`out`	`TextIO`	output text stream
`context`	`ParameterSaveContext_`	the parameter save context

HTMLRepresentation

Inherits: Representation[ParameterSaveContext_]

Representation that can be exported to the HTML

Methods

to_html


to_html(self, out: TextIO, context: ParameterSaveContext_) -> None

Write the parameter related data to be shown in a HTML file. The text should be written to the out stream.

📥 Parameters

Parameter	Type	Description
`out`	`TextIO`	output text stream
`context`	`ParameterSaveContext_`	the parameter save context

ImageRepr

Inherits: StrRepresentation MarkdownRepresentation HTMLRepresentation

Representation of the parameter as an image. Image generation is based on the pillow package.

Methods

__init__ constructor


__init__(self, value: Any, mode: Literal['1', 'L', 'LA', 'P', 'RGB', 'RGBA'] = 'L', format: str = 'png', show_image: bool = True)

📥 Parameters

Parameter	Type	Description
`value`	`Any`	The image data. See `matplotlib.pyplot.imshow` docs.
`mode`	`Literal['1', 'L', 'LA', 'P', 'RGB', 'RGBA'], optional`	the mode of the image, see https://pillow.readthedocs.io/en/stable/handbook/concepts.html#concept-modes . By default `L`
`format`	`str, optional`	the image format, by default ‘png’

draw_image


draw_image(self, context: ParameterSaveContext, filepath: Path) -> Image.Image

Draw image into the file, using pillow package.

📥 Parameters

Parameter	Type	Description
`context`	`ParameterSaveContext`	the parameter save context
`filepath`	`Path`	path to the image file to be created

to_str


to_str(self, out: TextIO, context: ParameterSaveContext)

to_markdown


to_markdown(self, out: TextIO, context: ParameterSaveContext)

to_html


to_html(self, out: TextIO, context: ParameterSaveContext)

ReprRepr

Inherits: StrRepresentation MarkdownRepresentation HTMLRepresentation

Representation of the parameter as a plain text. The __repr__ method is used to generate the text.

Methods

__init__ constructor


__init__(self, value: Any)

📥 Parameters

Parameter	Type	Description
`value`	`Any`	object with defined `__repr__` method that will be used to generate plain text.

to_str


to_str(self, out: TextIO, context: ParameterSaveContext)

to_markdown


to_markdown(self, out: TextIO, context: ParameterSaveContext)

to_html


to_html(self, out: TextIO, context: Any)

NpyFileRepr

Inherits: StrRepresentation MarkdownRepresentation

Representation of the parameter as a .npy file.

Methods

__init__ constructor


__init__(self, value: ArrayLike)

📥 Parameters

Parameter	Type	Description
`value`	`ArrayLike`	parameter data.

save_to_file


save_to_file(self, context: ParameterSaveContext, filepath: Path)

Save the parameter related data to npy file.

📥 Parameters

Parameter	Type	Description
`context`	`ParameterSaveContext`	the parameter save context
`filepath`	`Path`	path to the file to be created

to_str


to_str(self, out: TextIO, context: ParameterSaveContext)

to_markdown


to_markdown(self, out: TextIO, context: ParameterSaveContext)

PrettyReprRepr

Inherits: ReprRepr HTMLRepresentation

Same as ReprRepr but with better handling of Parameters and BoundedParameter

Methods

__init__ constructor


__init__(self, value: Any, units: str | None = None)

Representation of the parameter as a plain text. The __repr__ method is used to generate the text if the value is not torch.Tensor or Parameter.

📥 Parameters

Parameter	Type	Description
`value`	`Any`	object to generate plain text of.
`units`	`str	None, optional`

to_str


to_str(self, out: TextIO, context: ParameterSaveContext)

to_markdown


to_markdown(self, out: TextIO, context: ParameterSaveContext)

to_html


to_html(self, out: TextIO, context: ParameterSaveContext)

ParameterSpecs

Container with all representations for the parameter.

Methods

__init__ constructor


__init__(self, parameter_name: str, representations: Iterable[Representation]) -> None

📥 Parameters

Parameter	Type	Description
`name`	`str`	the parameter’s name.
`representations`	`Iterable[ParameterRepr]`	all representations of the parameter.

SubelementSpecs

Container for named subelement

Methods

__init__ constructor


__init__(self, subelement_type: str, subelement: 'Specsable')

📥 Parameters

Parameter	Type	Description
`subelement_type`	`str`	human-readable type of the subelement.
`subelement`	`Specsable`	the subelement.

Specsable

Inherits: Protocol

Represents any specsable object

Methods

to_specs


to_specs(self) -> Iterable[ParameterSpecs | SubelementSpecs]

_IndexedObject

Inherits: Generic[_T]

_WriterContext

Storage for additional info within ParameterSaveContext

_ElementInTree

Methods

create_copy


create_copy(self, subelement_type: str | None) -> '_ElementInTree'

_ElementsIterator

Properties

tree

Get a tree of all elements iterated

Methods

__init__ constructor


__init__(self, *iterables: Specsable) -> None

Functions

`context_generator(element: Specsable, element_index: int, directory: str | Path, subelements: list[SubelementSpecs]) -> _WriterContextGenerator`

Generate _WriterContext for the element

📥 Parameters

Parameter	Type	Description
`element`	`Specsable`	Element
`element_index`	`int`	Index of the element. It is used to create unique directory for element specs.
`directory`	`str	Path`

Yields

_WriterContext — context

Specs

Classes

ParameterSaveContext

Methods

📥 Parameters

📥 Parameters

📤 Returns

📥 Parameters

📤 Returns

📥 Parameters

Representation

MarkdownRepresentation

Methods

📥 Parameters

StrRepresentation

Methods

📥 Parameters

HTMLRepresentation

Methods

📥 Parameters

ImageRepr

Methods

📥 Parameters

📥 Parameters

ReprRepr

Methods

📥 Parameters

NpyFileRepr

Methods

📥 Parameters

📥 Parameters

PrettyReprRepr

Methods

📥 Parameters

ParameterSpecs

Methods

📥 Parameters

SubelementSpecs

Methods

📥 Parameters

Specsable

Methods

_IndexedObject

_WriterContext

_ElementInTree

Methods

_ElementsIterator

Properties

Methods

Functions

context_generator(element: Specsable, element_index: int, directory: str | Path, subelements: list[SubelementSpecs]) -> _WriterContextGenerator

📥 Parameters

write_specs_to_str(element: Specsable, element_index: int, writer_context_generator: _WriterContextGenerator, stream: TextIO)

write_specs_to_markdown(element: Specsable, element_index: int, writer_context_generator: _WriterContextGenerator, stream: TextIO)

write_specs_to_html(element: Specsable, element_index: int, writer_context_generator: _WriterContextGenerator, stream: TextIO)

write_elements_tree_to_str(tree: list[_ElementInTree], stream: TextIO)

write_elements_tree_to_markdown(tree: list[_ElementInTree], stream: TextIO)

write_specs(*iterables: Specsable)

`context_generator(element: Specsable, element_index: int, directory: str | Path, subelements: list[SubelementSpecs]) -> _WriterContextGenerator`

`write_specs_to_str(element: Specsable, element_index: int, writer_context_generator: _WriterContextGenerator, stream: TextIO)`

`write_specs_to_markdown(element: Specsable, element_index: int, writer_context_generator: _WriterContextGenerator, stream: TextIO)`

`write_specs_to_html(element: Specsable, element_index: int, writer_context_generator: _WriterContextGenerator, stream: TextIO)`

`write_elements_tree_to_str(tree: list[_ElementInTree], stream: TextIO)`

`write_elements_tree_to_markdown(tree: list[_ElementInTree], stream: TextIO)`

`write_specs(*iterables: Specsable)`