API reference

Preparation

.. py:function:: prepare(text, *, language=’en’, config=None, annotations=None, nlp=None, protected_spans=None, use_spacy=None, spacy_model=None, expand_abbreviations=True, expand_structured=True, normalize_literals=False, expand_numbers=True, normalize_whitespace=True, normalize_unicode=True, strip_outer_whitespace=True, collapse_horizontal_whitespace=True, normalize_line_whitespace=True, collapse_blank_lines=True, number_policy=None, preserve_run_boundaries=False, model_punctuation=False, symbol_mode=’none’, keep_symbols=’’, generic_acronym_mode=’known_only’, generic_acronym_case=’upper’, long_number_mode=’preserve’, registered_acronym_mode=’expand’, context=True, strict=False) :module: spokenform

Convert one-language written text into a readable form intended for speech.

The caller selects the processing language. Language detection, mixed-language segmentation, and markup parsing belong outside spokenform.

Structured values run before lexical abbreviation expansion and generic numbers so each complete expression receives one semantic replacement.

.. py:function:: prepare_for_kokorog2p(text, language=’en’, *, config=None, **kwargs) :module: spokenform

Prepare one language with the kokorog2p-safe profile.

.. py:function:: normalize_spacing(text, *, normalize_unicode=True, strip_outer_whitespace=True, collapse_horizontal_whitespace=True, normalize_line_whitespace=True, collapse_blank_lines=True, number_policy=None) :module: spokenform

Apply independently configurable Unicode and whitespace policies.

number_policy remains accepted for 0.2.x compatibility. Numeric policy selection belongs to :func:prepare; spacing itself does not consume it.

normalize_unicode, strip_outer_whitespace, collapse_horizontal_whitespace, normalize_line_whitespace, and collapse_blank_lines are independent policy controls. normalize_whitespace=False remains the compatibility switch for skipping the whitespace stage entirely. normalize_literals=True opts into high-confidence URL, e-mail, semantic-version, and contextual Roman rendering; caller-protected spans always take precedence.

symbol_mode="none" is the backward-compatible default and applies no general residual-symbol filter. symbol_mode="remove" removes Unicode punctuation and symbol characters (P* and S*) left after semantic recognition. With symbol_mode="keep", keep_symbols is an exact-codepoint allowlist; it must not be empty. An allowlist is invalid in none or remove mode. The active filter is recorded as a symbols stage before whitespace normalization and never changes protected spans. Symbol deletions are included in stage and source/output mapping.

generic_acronym_case="upper" is the default. Set it to "lower" to lowercase only generic grapheme-spaced uppercase acronyms; lexical acronyms, preserved terms, known initialisms, identifiers, and mixed-case tokens keep their normal policies.

.. py:class:: PreparationConfig(language=’en’, use_spacy=None, spacy_model=None, expand_abbreviations=True, expand_structured=True, normalize_literals=False, expand_numbers=True, normalize_whitespace=True, normalize_unicode=True, strip_outer_whitespace=True, collapse_horizontal_whitespace=True, normalize_line_whitespace=True, collapse_blank_lines=True, number_policy=None, preserve_run_boundaries=False, model_punctuation=False, symbol_mode=’none’, keep_symbols=’’, generic_acronym_mode=’known_only’, generic_acronym_case=’upper’, long_number_mode=’preserve’, registered_acronym_mode=’expand’, context=True, strict=False) :module: spokenform :canonical: spokenform.config.PreparationConfig

Immutable options controlling single-language written-to-spoken preparation.

.. py:method:: PreparationConfig.for_kokorog2p(language) :module: spokenform :classmethod:

  Return a one-language profile safe for kokorog2p adapters.

Result models

.. py:class:: PreparedText(source_text, clean_text, spoken_text, language, stages=(), mapped_edits=(), source_replacements=(), protected_spans=(), reserved_spans=(), offset_map=None, warnings=()) :module: spokenform :canonical: spokenform.models.PreparedText

Readable spoken text with normalization provenance.

.. py:property:: PreparedText.changed :module: spokenform :type: bool

  Return whether preparation changed the source text.

.. py:property:: PreparedText.edits :module: spokenform :type: tuple[~spokenform.models.TextEdit, …]

  Return the ordered edits from every stage.

.. py:method:: PreparedText.map_output_span(start, end) :module: spokenform

  Map a final spoken-text span back to original source coordinates.

.. py:method:: PreparedText.map_source_span(start, end) :module: spokenform

  Map an original source span to final spoken-text coordinates.

.. py:method:: PreparedText.render_changes() :module: spokenform

  Render a compact, human-readable stage report.

.. py:property:: PreparedText.replacements :module: spokenform :type: tuple[~spokenform.models.SourceReplacement, …]

  Stable adapter alias for composed source replacements.

.. py:property:: PreparedText.source_edits :module: spokenform :type: tuple[~spokenform.models.SourceReplacement, …]

  Return edits in the documented source-to-final coordinate space.

.. py:property:: PreparedText.stage_report :module: spokenform :type: str

  Return the diagnostic stage report for adapter logging.

.. py:property:: PreparedText.text :module: spokenform :type: str

  Alias for :attr:`spoken_text`.

.. py:method:: PreparedText.to_adapter_dict() :module: spokenform

  Return the stable kokorog2p-facing result projection.

.. py:method:: PreparedText.to_dict() :module: spokenform

  Return a JSON-serializable representation.

All public source offsets refer to the original string passed to prepare(); final offsets refer to PreparedText.spoken_text; stage-local offsets remain available only under each PreparationStage. PreparedText.to_adapter_dict() is the stable JSON-ready projection for a kokorog2p adapter.

prepare_for_kokorog2p() requires an explicit language and performs no language detection, tokenization, G2P, or model-punctuation rewriting. Its default profile preserves run boundary whitespace. Pass caller-owned protected_spans to prevent semantic replacements; partial overlap is handled fail-closed by protecting the complete recognized quantity expression. Use source_replacements and the offset helpers to rebase downstream token and override coordinates.

The preferred downstream surface is PreparationConfig.for_kokorog2p(), prepare_for_kokorog2p(), PreparedText.source_replacements, PreparedText.offset_map, and NumberPolicy. The lower-level mapping and stage helpers are advanced exports rather than requirements for a normal adapter.

Export classification

The stable application-facing surface is prepare(), prepare_for_kokorog2p(), prepare_text, PreparationConfig, NumberPolicy, PreparedText, ProtectedSpan, ProtectionError, TokenAnnotation, and __version__. number_policy_for_language() and normalize_numbers() are stable locale-policy helpers. The annotation adapters, spaCy model helpers, structured-stage helpers, StageResult, and mapping/replacement classes and conversion functions are advanced public APIs: they remain exported for compatibility and diagnostics, but downstream integrations should prefer the high-level preparation surface. No exported symbol is removed in 0.2.2.

.. py:class:: PreparationStage(name, before, after, edits=(), mapped_edits=(), reserved=()) :module: spokenform :canonical: spokenform.models.PreparationStage

The before/after text and edits produced by one stage.

.. py:property:: PreparationStage.changed :module: spokenform :type: bool

  Return whether this stage changed the text.

.. py:class:: TextEdit(start, end, source, replacement, stage) :module: spokenform :canonical: spokenform.models.TextEdit

One edit in a normalization stage.

Offsets are relative to the input of that stage. This keeps every edit exact without pretending that all stages still share the original coordinate space.

.. py:class:: MappedEdit(source_start, source_end, output_start, output_end, source, replacement, stage, language=None, kind=’replacement’, rule=None) :module: spokenform :canonical: spokenform.models.MappedEdit

A replacement with source and output coordinates.

Annotation adapters

.. py:class:: TokenAnnotation(start, end, text=None, pos=None, tag=None, lemma=None, language=None) :module: spokenform :canonical: spokenform.models.TokenAnnotation

Provider-neutral lexical annotation aligned to one input text.

.. py:function:: annotations_from_spacy(doc) :module: spokenform

Convert a spaCy-like Doc into source-aligned annotations.

The adapter imports no spaCy modules and can therefore be used with compatible providers or simple test doubles.

.. py:function:: spacy_annotations(text, nlp) :module: spokenform

Run an existing spaCy-compatible pipeline and convert its tokens.

.. py:function:: validate_annotations(text, annotations) :module: spokenform

Validate and materialize source-aligned annotations.

Annotation spans must be ordered, non-overlapping, inside text, and match annotation.text when that optional value is supplied.

Number normalization

The Czech normalize_numbers(language="cs") path delegates to the reviewed structured and structured-safe plain-number grammar. It verbalizes ordinary numbers, validated dates, quantities, temperatures, and canonical currencies; colon-time candidates remain unchanged for caller-managed handling.

.. py:function:: normalize_numbers(text, *, language) :module: spokenform

Verbalize common dates, times, currencies, ordinals, and numbers.

URLs, email addresses, and semantic-version-like values are protected. The implementation is intentionally conservative and is an MVP, not a complete locale grammar.

.. py:function:: normalize_structured(text, *, language, protected_ranges=(), promote_literals=False, generic_acronym_mode=’known_only’, generic_acronym_case=’upper’) :module: spokenform

Normalize structured values and return exact semantic provenance.

.. py:function:: iter_structured_replacements(text, *, language, protected_ranges=(), promote_literals=False, generic_acronym_mode=’known_only’, generic_acronym_case=’upper’) :module: spokenform

Return exact, non-overlapping semantic replacements for one language.