Function reference

These descriptions are imported from Python docstrings at build time.

Analysis

Small, deterministic text analysis functions used by the workshop.

analysis.tokenize(text: str) → list[str][source]

Extract case-insensitive Unicode words from raw text.

Letters and internal apostrophes are retained. Numbers and underscores separate words. Markdown links, code and markup are not removed.

Parameters:

text – Text to analyze.

Returns:

Lowercase words in their original order.

analysis.analyze_text(text: str, top: int = 10) → dict[source]

Count words and select the most frequent ones.

Ties are sorted alphabetically for deterministic output. An empty text has zero words. Common words are included; no stop-word list is applied.

Parameters:

  • text – Raw input text, including any Markdown syntax.

  • top – Positive number of frequent words to include.

Returns:

Total count, unique count and a list of frequent words.

Raises:

ValueError – If top is not a positive integer.

analysis.analyze_file(path: Path, top: int = 10) → dict[source]

Read a UTF-8 document and attach its filename to the statistics.

Parameters:

  • path – Path of an existing UTF-8 text file.

  • top – Number of frequent words to include.

Returns:

A versioned record suitable for JSON serialization.

Raises:

  • OSError – If the file cannot be read.

  • UnicodeError – If the input is not UTF-8.

  • ValueError – If top is invalid.

Report

Build an offline HTML report from TextLab JSON records.

report.render_report(records: list[dict]) → str[source]

Render statistics as an HTML table and per-document bar charts.

Input must follow the schema produced by analyze_file. All textual values are escaped. Word totals include duplicates between documents.

Parameters:

records – Analysis records in the desired display order.

Returns:

A complete, self-contained HTML page.

report.write_report(input_dir: Path, output: Path) → int[source]

Load all JSON files in a directory and write an HTML report.

Parameters:

  • input_dir – Directory containing TextLab JSON files only.

  • output – Destination HTML file.

Returns:

Number of documents included.

Raises:

ValueError – If no JSON files exist or a schema version is unknown.