demopkg

Search symbols

Type part of a name or a dotted path

Demo package used by the starlight-pydocs test suite.

demopkg exists to exercise every feature of the documentation renderer: google-style docstring sections, inheritance, overloads, positional-only and keyword-only parameters, re-exports through __all__, pydantic models, deprecations and private members that must stay hidden.

The public surface is declared explicitly in __all__, so anything not listed there is invisible to the default member filter.

Examples

Build a report and write it to disk:

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

Attributes

Name	Description
DEFAULT_TIMEOUT	Seconds to wait for report generation before giving up.

Classes

Name	Description
Report	A named collection of scored sections.

Functions

Name	Description
generate_report	Build a report from a source object.

Modules

• compatBackwards compatible aliases, without an __all__.
• modelsPydantic models, documented through the griffe_pydantic extension.
• reportReport classes and the functions that build them.
• utilsHelpers that operate on reports.

DEFAULT_TIMEOUTattributemodule attribute#

DEFAULT_TIMEOUT: float = 30.0

Seconds to wait for report generation before giving up.

Used as the default for Report.generate.

Reportclass#

Re-exported from demopkg.report

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.

generate_reportfunction#

Re-exported from demopkg.report

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.