dump_fonts¶

This module discovers installed fonts on the host system and extracts raw, low-level metadata using fontTools and (optionally) FontConfig.

It produces the canonical raw font inventory consumed by the rest of the Fontshow pipeline.

Responsibilities¶

Discover installed font files (Linux / Windows)
Extract per-face metadata
Handle TrueType Collections (TTC)
Cache expensive fontTools operations
Persist LuaLaTeX loadability metadata by default
Serialize results to JSON

Loadability Persistence¶

dump-fonts now performs LuaLaTeX loadability probing by default and persists the results in the generated inventory.

Behavior:

candidate fonts are probed in deterministic serial batches
per-font results are stored under loadability.lualatex
inventory-level runtime metadata is stored under metadata.validation.lualatex
the runtime fingerprint allows downstream stages to detect stale persisted results

To disable probing explicitly:

python -m fontshow.cli.dump_fonts --no-loadability

When --no-loadability is used:

no LuaLaTeX probing is performed
metadata.validation.lualatex.attempted remains false
per-font loadability fields remain in their non-attempted state

--include-fc-charset¶

When enabled, this option instructs Fontshow to query Fontconfig for declared Unicode charset information and include it in the generated inventory.

python -m fontshow.cli.dump_fonts --include-fc-charset

The resulting data is stored in the optional charset field of each font entry.

Fontconfig charset extraction is best-effort and depends on the availability and behavior of fc-query on the host system. On some distributions, fc-query cannot reliably be used to inspect individual font faces, resulting in empty charset data.

Scope and non-responsibilities¶

The dump-fonts stage is responsible for discovering fonts and extracting raw metadata from the system.

It is intentionally limited to data collection and does not perform:

semantic validation
language normalization
charset interpretation
inventory consistency checks
catalog generation

In particular:

No assumptions are made about the correctness of extracted metadata
No normalization or enrichment is applied
No validation errors are raised at this stage

The persisted LuaLaTeX loadability state is an exception to the "metadata only" baseline: it is an optional deterministic runtime assessment stored directly in the raw inventory so later stages can reuse it instead of recomputing it.

All semantic interpretation and validation are delegated to the inventory parsing stage.

This separation ensures that:

font discovery remains environment-specific
metadata extraction stays lossless
higher-level logic remains centralized and testable

API reference¶

fontshow.cli.dump_fonts ¶

Fontshow dump-fonts CLI command.

This module implements the inventory discovery stage of the Fontshow pipeline and produces a raw inventory describing fonts available on the system.

Responsibilities¶

Discover fonts using platform-specific mechanisms (Fontconfig or equivalent tools).
Extract raw font metadata from system sources.
Serialize discovered font information into the initial inventory format used by subsequent pipeline stages.

Design principles¶

This stage performs no semantic interpretation of font metadata. All extracted information is preserved as-is so that later stages (parse-inventory, validation, and catalog generation) can perform analysis and enrichment deterministically.

Architectural role¶

This module belongs to the CLI interface layer and implements the font discovery stage that generates the initial Fontshow inventory.

build_parser ¶

build_parser(parser: ArgumentParser) -> None

Register dump-fonts CLI arguments on an existing parser.

Parameters¶

parser : argparse.ArgumentParser Parser instance to configure.

Returns¶

None

main ¶

main(args) -> int

CLI wrapper for dump-fonts.

Parameters¶

args : argparse.Namespace Parsed CLI arguments.

Returns¶

int Process exit code.

Notes¶

Unexpected TypeError exceptions are treated as non-fatal to preserve the command's legacy wrapper semantics.

Shared CLI quiet/verbose mode is configured before invoking the injectable runner.

register_cli ¶

register_cli(parser) -> None

Register dump-fonts CLI on a parser.

Parameters¶

parser : argparse.ArgumentParser Parser instance to configure.

Returns¶

None

Notes¶

Used by the top-level CLI dispatcher to bind the dump-fonts command to main.

run_dump_fonts ¶

run_dump_fonts(args) -> int

Execute the dump-fonts pipeline.

Parameters¶

args : argparse.Namespace Parsed CLI arguments.

Returns¶

int Process exit code (0 for success, non-zero for failure).

Raises¶

OSError May propagate from filesystem writes such as cache directory creation or final inventory output.

Notes¶

This function performs the full dump pipeline and returns an exit code. It MUST NOT call sys.exit() and SHOULD NOT print directly. It orchestrates the full dump pipeline:

Discover installed font files for the current platform.
Extract per-face metadata using fontTools.
Optionally enrich metadata using FontConfig (Linux only).
Build canonical font descriptors.
Write the resulting JSON inventory to disk.

All heavy lifting is delegated to dedicated helpers; this function is intentionally linear and side-effect driven (filesystem I/O). Best-effort Fontconfig enrichment failures are logged and downgraded to an empty enrichment map instead of aborting the command.