repomatic.tabular module

Row type a committed store materializes into.

class repomatic.tabular.RecordT

Row type a committed store materializes into.

alias of TypeVar(‘RecordT’)

repomatic.tabular.render_csv(headers, rows)

Render a header row and its data rows as CSV text.

Newlines are \n on every platform, since the output is committed and a platform-dependent line ending would make the file churn between a Windows and a Unix runner.

Parameters:

• headers (Sequence[str]) – Column names, in order.

• rows (Iterable[Sequence[object]]) – One sequence of cells per row, in the same order.

Return type:

str

Returns:

The complete CSV document, newline-terminated.

class repomatic.tabular.ReportAction(*values)

Bases: Enum

What a job did to one item, as the markdown report spells it.

Each member’s value is the emoji-decorated label the report table shows, so a renderer reads the label off the action. No parallel mapping exists for a new member to miss.

The members are the union of the vocabularies every report needs, and each report uses the subset that applies to it: the release-notes sync never unsubscribes, and the notification sweep has nothing to call in sync. What they share is the outcome pair every dry-runnable sweep reports.

DROPPED = '🗑️ Dropped'

DRY_RUN = '👁️ Dry-run'

FAILED = '⚠️ Failed'

SKIPPED = '✅ In sync'

UNSUBSCRIBED = '🔕 Unsubscribed'

UPDATED = '🔄 Updated'

UPLOADED = '⬆️ Uploaded'

repomatic.tabular.render_markdown_table(headers, rows, align=())

Render a GitHub-flavored Markdown table.

Cells are used as given: a caller wanting a code span, a link or an emoji renders it into the cell first. Nothing is escaped, matching what every report renderer did by hand before this existed: none of them ever feeds a cell carrying a |.

Parameters:

• headers (Sequence[object]) – Column titles, in order.

• rows (Iterable[Sequence[object]]) – One sequence of cells per row, in the same order.

• align (Sequence[str]) – Per-column alignment, left, right or center; an empty entry (or a list shorter than headers) leaves that column on the parser default. Alignment only changes how a renderer justifies the column, so it is worth declaring where it carries meaning, like a numeric column read against its neighbours.

Return type:

str

Returns:

The table’s lines joined with newlines, no trailing newline.

Raises:

KeyError – On an alignment name outside the vocabulary.

repomatic.tabular.read_csv(path)

Read a committed CSV into one mapping per row.

Every cell comes back as a string: CSV carries no types, so a caller wanting a number coerces it. A missing file reads as no rows, which is what a first run sees.

Parameters:

path (Path) – Path to the CSV file.

Return type:

list[dict[str, str]]

Returns:

One mapping per data row, keyed by column name.

Raises:

ValueError – When the file exists but carries no header row. Loud on purpose: a truncated or half-written file must never be silently treated as empty and clobbered by the next write_csv().

repomatic.tabular.load_records(path, from_row, kind)

Materialize a committed store through a row parser, loudly.

The committed-dataset counterpart of read_csv(): one row-to-record pass with one failure contract, so every store fails the same way.

Parameters:

• path (Path) – Path to the CSV store.

• from_row (Callable[[Mapping[str, Any]], TypeVar(RecordT)]) – The row parser, typically the record class’s from_row classmethod.

• kind (str) – What the store holds, opening the failure message.

Return type:

list[TypeVar(RecordT)]

Returns:

The parsed records.

Raises:

ValueError – When the store exists but cannot be parsed. Loud on purpose: a corrupt store must never be silently clobbered by the next write.

repomatic.tabular.write_csv(path, content)

Write rendered CSV to path, leaving an unchanged file alone.

Parameters:

• path (Path) – Path to the CSV file.

• content (str) – Rendered CSV, from render_csv().

Return type:

bool

Returns:

True when the file content changed.