# demopkg

> API reference for the Python package `demopkg`, generated by starlight-pydocs.
> Rendered pages: https://ewels.github.io/starlight-pydocs/api/demopkg/

# demopkg

*module*

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:

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

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/__init__.py#L1-L1)

## demopkg.DEFAULT_TIMEOUT

*attribute* · *module attribute*

```python
DEFAULT_TIMEOUT: float = 30.0
```

Seconds to wait for report generation before giving up.

Used as the default for [`Report.generate`][demopkg.report.Report.generate].

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/__init__.py#L20-L20)

## demopkg.Report

*class*

```python
class Report(BaseReport)
```

Bases: `demopkg.report.BaseReport`

Re-exported from: `demopkg.report`

A named collection of scored sections.

**Parameters**

- `name` (`str`) — Human readable report name, also used as the file stem.
- `scores` (`dict[str, float] | None`) (default: `None`) — Mapping of metric name to score. Defaults to an empty mapping.

**Attributes**

- `name` — The report name.
- `scores` (`dict[str, float]`) — The scores passed to the constructor.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L57-L160)

### demopkg.Report.name

*attribute* · *instance attribute*

```python
name = name
```

The report name.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L70-L70)

### demopkg.Report.scores

*attribute* · *instance attribute*

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

Mapping of metric name to score.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L72-L72)

### demopkg.Report.format

*attribute* · *class attribute* · *instance attribute*

```python
format: str = 'txt'
```

Inherited from: `demopkg.report.BaseReport`

Default output format, as a bare file extension.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L29-L29)

### demopkg.Report.title

*property* · *writable*

```python
title: str
```

Title used in the rendered output.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L154-L156)

### demopkg.Report.is_valid

*property*

```python
is_valid: bool
```

Inherited from: `demopkg.report.BaseReport`

Whether [`validate`][demopkg.report.BaseReport.validate] passes.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L52-L54)

### demopkg.Report.from_mapping

*method* · *classmethod*

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

Build a report from an existing mapping of scores.

**Parameters**

- `data` (`Mapping[str, float]`) — Metric name to score.
- `name` (`str`) (default: `'report'`) — Name for the new report.

**Returns**

- (`Report`) — A new report holding a copy of `data`.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L140-L151)

### demopkg.Report.generate

*method*

```python
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**

- `*sections` (`str`) (default: `()`) — Section names to include, in order. When empty every known section is rendered.
- `title` (`str | None`) (default: `None`) — Overrides the report title. Defaults to the report name.
- `timeout` (`float`) (default: `DEFAULT_TIMEOUT`) — Seconds to wait before giving up.
- `**options` (`Any`) (default: `{}`) — 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**

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

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L76-L110)

### demopkg.Report.render

*method*

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

Render one section or a list of sections.

**Parameters**

- `value` (`str | list[str]`) — A single section name or a list of them.

**Returns**

- (`str | list[str]`) — Rendered output matching the shape of `value`.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L118-L129)

### demopkg.Report.supported_formats

*method* · *staticmethod*

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

List the formats a report can be saved as.

**Returns**

- (`tuple[str, ...]`) — Format extensions, without leading dots.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L131-L138)

### demopkg.Report.save

*method*

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

Inherited from: `demopkg.report.BaseReport`

Write the rendered report to `path`.

**Parameters**

- `path` (`pathlib.Path`) — Destination file. Parent directories must exist.

**Raises**

- `OSError` — If the file cannot be written.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L32-L41)

### demopkg.Report.validate

*method*

```python
def validate() -> bool
```

Inherited from: `demopkg.report.BaseReport`

Check the report for structural problems.

**Returns**

- (`bool`) — True when the report is well formed.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L43-L49)

## demopkg.generate_report

*function*

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

Re-exported from: `demopkg.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][demopkg.report.Report] whose
[generate][demopkg.report.Report.generate] method writes a
[pathlib.Path][pathlib.Path]. A reference nothing resolves, such as
[nosuchpkg.Thing][], is left exactly as it was written.

**Parameters**

- `source` — Anything with a `read()` method; deliberately unannotated.
- `name` (`str`) — Name for the resulting report.
- `fmt` (`str`) (default: `'md'`) — Output format for the report.

**Returns**

- (`Report`) — A populated report.

**Raises**

- `ReportError` — If `source` cannot be read.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L163-L187)

**Modules**

- `demopkg.compat`
- `demopkg.models`
- `demopkg.report`
- `demopkg.utils`

---

# demopkg.compat

*module*

Backwards compatible aliases, without an `__all__`.

The public surface of this module is inferred: `legacy_name` and `LEGACY_LIMIT`
are public, `_shim` is private, and `Report` is an import (so it is only shown
when imported members are not filtered out).

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/compat.py#L1-L1)

## demopkg.compat.LEGACY_LIMIT

*attribute* · *module attribute*

```python
LEGACY_LIMIT = 100
```

Largest report size the old API accepted.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/compat.py#L10-L10)

## demopkg.compat.legacy_name

*function*

```python
def legacy_name(report: Report) -> str
```

Return the name the old API would have used.

**Parameters**

- `report` (`Report`) — Report to name.

**Returns**

- (`str`) — The legacy name.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/compat.py#L14-L23)

---

# demopkg.models

*module*

Pydantic models, documented through the `griffe_pydantic` extension.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/models.py#L1-L1)

## demopkg.models.User

*class* · *pydantic model*

```python
class User(BaseModel)
```

Bases: `BaseModel`

Someone who can own a report.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/models.py#L6-L17)

### demopkg.models.User.email

*attribute* · *pydantic field*

```python
email: str
```

Contact address, lowercased on validation.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/models.py#L10-L10)

### demopkg.models.User.name

*attribute* · *pydantic field*

```python
name: str
```

Display name of the user.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/models.py#L9-L9)

### demopkg.models.User.reports

*attribute* · *pydantic field*

```python
reports: int = 0
```

How many reports the user owns.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/models.py#L11-L11)

---

# demopkg.report

*module*

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.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L1-L1)

## demopkg.report.BaseReport

*class*

```python
class BaseReport
```

Common behaviour shared by every report.

**Attributes**

- `format` (`str`) — File extension used when a report is saved without one.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L22-L54)

### demopkg.report.BaseReport.format

*attribute* · *class attribute* · *instance attribute*

```python
format: str = 'txt'
```

Default output format, as a bare file extension.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L29-L29)

### demopkg.report.BaseReport.is_valid

*property*

```python
is_valid: bool
```

Whether [`validate`][demopkg.report.BaseReport.validate] passes.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L52-L54)

### demopkg.report.BaseReport.save

*method*

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

Write the rendered report to `path`.

**Parameters**

- `path` (`pathlib.Path`) — Destination file. Parent directories must exist.

**Raises**

- `OSError` — If the file cannot be written.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L32-L41)

### demopkg.report.BaseReport.validate

*method*

```python
def validate() -> bool
```

Check the report for structural problems.

**Returns**

- (`bool`) — True when the report is well formed.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L43-L49)

## demopkg.report.Report

*class*

```python
class Report(BaseReport)
```

Bases: `demopkg.report.BaseReport`

A named collection of scored sections.

**Parameters**

- `name` (`str`) — Human readable report name, also used as the file stem.
- `scores` (`dict[str, float] | None`) (default: `None`) — Mapping of metric name to score. Defaults to an empty mapping.

**Attributes**

- `name` — The report name.
- `scores` (`dict[str, float]`) — The scores passed to the constructor.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L57-L160)

### demopkg.report.Report.name

*attribute* · *instance attribute*

```python
name = name
```

The report name.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L70-L70)

### demopkg.report.Report.scores

*attribute* · *instance attribute*

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

Mapping of metric name to score.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L72-L72)

### demopkg.report.Report.format

*attribute* · *class attribute* · *instance attribute*

```python
format: str = 'txt'
```

Inherited from: `demopkg.report.BaseReport`

Default output format, as a bare file extension.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L29-L29)

### demopkg.report.Report.title

*property* · *writable*

```python
title: str
```

Title used in the rendered output.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L154-L156)

### demopkg.report.Report.is_valid

*property*

```python
is_valid: bool
```

Inherited from: `demopkg.report.BaseReport`

Whether [`validate`][demopkg.report.BaseReport.validate] passes.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L52-L54)

### demopkg.report.Report.from_mapping

*method* · *classmethod*

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

Build a report from an existing mapping of scores.

**Parameters**

- `data` (`Mapping[str, float]`) — Metric name to score.
- `name` (`str`) (default: `'report'`) — Name for the new report.

**Returns**

- (`Report`) — A new report holding a copy of `data`.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L140-L151)

### demopkg.report.Report.generate

*method*

```python
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**

- `*sections` (`str`) (default: `()`) — Section names to include, in order. When empty every known section is rendered.
- `title` (`str | None`) (default: `None`) — Overrides the report title. Defaults to the report name.
- `timeout` (`float`) (default: `DEFAULT_TIMEOUT`) — Seconds to wait before giving up.
- `**options` (`Any`) (default: `{}`) — 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**

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

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L76-L110)

### demopkg.report.Report.render

*method*

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

Render one section or a list of sections.

**Parameters**

- `value` (`str | list[str]`) — A single section name or a list of them.

**Returns**

- (`str | list[str]`) — Rendered output matching the shape of `value`.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L118-L129)

### demopkg.report.Report.supported_formats

*method* · *staticmethod*

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

List the formats a report can be saved as.

**Returns**

- (`tuple[str, ...]`) — Format extensions, without leading dots.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L131-L138)

### demopkg.report.Report.save

*method*

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

Inherited from: `demopkg.report.BaseReport`

Write the rendered report to `path`.

**Parameters**

- `path` (`pathlib.Path`) — Destination file. Parent directories must exist.

**Raises**

- `OSError` — If the file cannot be written.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L32-L41)

### demopkg.report.Report.validate

*method*

```python
def validate() -> bool
```

Inherited from: `demopkg.report.BaseReport`

Check the report for structural problems.

**Returns**

- (`bool`) — True when the report is well formed.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L43-L49)

## demopkg.report.ReportError

*class*

```python
class ReportError(Exception)
```

Bases: `Exception`

Raised when a report cannot be generated.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L209-L210)

## demopkg.report.ReportWarning

*class*

```python
class ReportWarning(UserWarning)
```

Bases: `UserWarning`

Warned when a report is generated with incomplete data.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L213-L214)

## demopkg.report.generate_report

*function*

```python
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][demopkg.report.Report] whose
[generate][demopkg.report.Report.generate] method writes a
[pathlib.Path][pathlib.Path]. A reference nothing resolves, such as
[nosuchpkg.Thing][], is left exactly as it was written.

**Parameters**

- `source` — Anything with a `read()` method; deliberately unannotated.
- `name` (`str`) — Name for the resulting report.
- `fmt` (`str`) (default: `'md'`) — Output format for the report.

**Returns**

- (`Report`) — A populated report.

**Raises**

- `ReportError` — If `source` cannot be read.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L163-L187)

## demopkg.report.old_generate

*function*

```python
def old_generate(name: str) -> Report
```

**Deprecated**: Since 0.3. Use [`generate_report`][demopkg.report.generate_report].

Build a report the old way.

**Parameters**

- `name` (`str`) — Name for the resulting report.

**Returns**

- (`Report`) — A populated report.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/report.py#L193-L206)

---

# demopkg.utils

*module*

Helpers that operate on reports.

Everything here is a plain function; the module has no `__all__`, so the public
surface comes from the `is_public` heuristics (no leading underscore, not
imported).

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/utils.py#L1-L1)

## demopkg.utils.SECTION_STYLES

*attribute* · *module attribute*

```python
SECTION_STYLES: dict[str, dict[str, str]] = {'summary': {'colour': '#1b1f2a', 'marker': '*', 'caption': 'Summary, at a glance'}, 'detail': {'colour': '#2a334e', 'marker': '-', 'caption': 'Detail (one row per metric)'}, 'appendix': {'colour': '#f2c641', 'marker': '+', 'caption': 'Appendix [optional, omitted by default]'}, 'footer': {'colour': '#aab2c4', 'marker': '.', 'caption': 'Footer, with the generated-at stamp'}}
```

How each section of a rendered report is presented.

Deliberately long: it is the fixture for a signature whose value is broken
across lines at its brackets and then folded behind a toggle. The captions hold
brackets, commas and quotes so the line-breaker has string literals to step
over.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/utils.py#L13-L18)

## demopkg.utils.describe

*function*

```python
def describe(report: Report, **extra: Any) -> str
```

Summarise a report in one line.

**Parameters**

- `report` (`Report`) — The report to describe.
- `**extra` (`Any`) (default: `{}`) — Extra key/value pairs appended to the summary.

**Returns**

- (`str`) — A single line of plain text.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/utils.py#L69-L79)

## demopkg.utils.iter_sections

*function*

```python
def iter_sections(report: Report) -> Iterator[str]
```

Walk the sections of a report in render order.

**Parameters**

- `report` (`Report`) — The report to walk.

**Yields**

- (`str`) — Section names, uppercased.

**Examples**

```pycon
>>> list(iter_sections(Report("weekly")))
[]
```

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/utils.py#L28-L42)

## demopkg.utils.merge_scores

*function*

```python
def merge_scores(left: Report, right: Report) -> dict[str, float]
```

Combine the scores of two reports.

**Parameters**

- `left` (`Report`) — Report whose scores take precedence.
- `right` (`Report`) — Report contributing the remaining scores.

**Returns**

- (`dict[str, float]`) — A new mapping holding both sets of scores.

**Raises**

- `ReportError` — If the two reports disagree on a metric.
- `TypeError` — If either argument is not a report.
- `ValueError` — If either report has no scores.

[View source](https://github.com/ewels/starlight-pydocs/blob/main/fixtures/demopkg/src/demopkg/utils.py#L45-L66)