demopkg.report

Report classes and the functions that build them.

This module holds the bulk of the fixture surface: a base class, a subclass that inherits and overrides members, overloaded methods, a static method, a class method, a property with a setter, and the package’s exception types.

Classes

Name	Description
BaseReport	Common behaviour shared by every report.
Report	A named collection of scored sections.
ReportError	Raised when a report cannot be generated.
ReportWarning	Warned when a report is generated with incomplete data.

Functions

Name	Description
generate_report	Build a report from a source object.
old_generate	Build a report the old way.

BaseReportclass#

class BaseReport

Common behaviour shared by every report.

Attributes

Name	Type	Description
format	str	File extension used when a report is saved without one.

formatattributeclass attributeinstance attribute#

format: str = 'txt'

Default output format, as a bare file extension.

is_validproperty#

is_valid: bool

Whether validate passes.

savemethod#

def save(path: pathlib.Path) -> None

Write the rendered report to path.

Parameters

Name	Type	Description
path	pathlib.Path	Destination file. Parent directories must exist.

Raises

OSError

If the file cannot be written.

validatemethod#

def validate() -> bool

Check the report for structural problems.

Returns

bool

True when the report is well formed.

Reportclass#

class Report(name: str, scores: dict[str, float] | None = None)

Bases: BaseReport

A named collection of scored sections.

Parameters

Name	Type	Default	Description
name	str	required	Human readable report name, also used as the file stem.
scores	dict[str, float] | None	None	Mapping of metric name to score. Defaults to an empty mapping.

Attributes

Name	Type	Description
name		The report name.
scores	dict[str, float]	The scores passed to the constructor.

nameattributeinstance attribute#

name = name

The report name.

scoresattributeinstance attribute#

scores: dict[str, float] = scores or {}

Mapping of metric name to score.

titlepropertywritable#

title: str

Title used in the rendered output.

from_mappingmethodclassmethod#

def from_mapping(data: Mapping[str, float], *, name: str = 'report') -> Report

Build a report from an existing mapping of scores.

Parameters

Name	Type	Default	Description
data	Mapping[str, float]	required	Metric name to score.
name	str	'report'	Name for the new report.

Returns

Report

A new report holding a copy of data.

generatemethod#

def generate(*sections: str, title: str | None = None, timeout: float = DEFAULT_TIMEOUT, **options: Any) -> pathlib.Path

Render the report and return the path it was written to.

Parameters

Name	Type	Default	Description
*sections	str	()	Section names to include, in order. When empty every known section is rendered.
title	str | None	None	Overrides the report title. Defaults to the report name.
timeout	float	DEFAULT_TIMEOUT	Seconds to wait before giving up.
**options	Any	{}	Extra renderer options, passed through untouched.

Returns

pathlib.Path

The path of the file that was written.

Raises

ReportError

If a requested section does not exist.

TimeoutError

If rendering takes longer than timeout.

Note

Generation is deliberately synchronous; run it in a thread if you need to keep an event loop responsive.

Examples

>>> Report("weekly").generate("summary", title="Weekly")
PosixPath('weekly.txt')

rendermethod#

def render(value: str | list[str]) -> str | list[str]

Render one section or a list of sections.

Parameters

Name	Type	Description
value	str | list[str]	A single section name or a list of them.

Returns

str | list[str]

Rendered output matching the shape of value.

supported_formatsmethodstaticmethod#

def supported_formats() -> tuple[str, ...]

List the formats a report can be saved as.

Returns

tuple[str, ...]

Format extensions, without leading dots.

Inherited from demopkg.report.BaseReport

formatattributeclass attributeinstance attribute#

Inherited from demopkg.report.BaseReport

format: str = 'txt'

Default output format, as a bare file extension.

is_validproperty#

Inherited from demopkg.report.BaseReport

is_valid: bool

Whether validate passes.

savemethod#

Inherited from demopkg.report.BaseReport

def save(path: pathlib.Path) -> None

Write the rendered report to path.

Parameters

Name	Type	Description
path	pathlib.Path	Destination file. Parent directories must exist.

Raises

OSError

If the file cannot be written.

validatemethod#

Inherited from demopkg.report.BaseReport

def validate() -> bool

Check the report for structural problems.

Returns

bool

True when the report is well formed.

ReportErrorclass#

class ReportError(Exception)

Bases: Exception

Raised when a report cannot be generated.

ReportWarningclass#

class ReportWarning(UserWarning)

Bases: UserWarning

Warned when a report is generated with incomplete data.

generate_reportfunction#

def generate_report(source, /, name: str, *, fmt: str = 'md') -> Report

Build a report from a source object.

Exercises a positional-only parameter (source, before the /) and a keyword-only one (fmt, after the *).

Returns a Report whose generate method writes a pathlib.Path. A reference nothing resolves, such as [nosuchpkg.Thing][], is left exactly as it was written.

Parameters

Name	Type	Default	Description
source		required	Anything with a read() method; deliberately unannotated.
name	str	required	Name for the resulting report.
fmt	str	'md'	Output format for the report.

Returns

Report

A populated report.

Raises

ReportError

If source cannot be read.

old_generatefunctionDeprecated#

Deprecated

Since 0.3. Use generate_report.

def old_generate(name: str) -> Report

Build a report the old way.

Parameters

Name	Type	Description
name	str	Name for the resulting report.

Returns

Report

A populated report.