Language packs

What a third-party language pack must implement, and how it tells the library what it can do.

denckring.core.protocol.LanguagePack

Bases: Protocol

Per-language behaviour.

A pack implements every method here, but one whose capability it does not declare must raise MissingCapability rather than approximate. word_spans, alphabet, vowels, ascenders and descenders go beyond the original four-method sketch: violations need character offsets, and the prisoner's constraint needs glyph shapes.

capabilities class-attribute

capabilities: frozenset[str]

lang class-attribute

lang: Lang

word_re class-attribute

word_re: Pattern[str]

alphabet

alphabet() -> str

ascenders

ascenders() -> frozenset[str]

descenders

descenders() -> frozenset[str]

exceeds_x_height

exceeds_x_height(ch: str) -> bool

fold_diacritics

fold_diacritics(ch: str) -> str

glosses

glosses(word: str) -> Sequence[str]

graded_words

graded_words() -> Mapping[str, int]

is_vowel_phoneme

is_vowel_phoneme(phoneme: str) -> bool

is_word

is_word(word: str) -> bool

line_syllables

line_syllables(line: str) -> tuple[int, int]

noun_index

noun_index(word: str) -> int | None

nouns

nouns() -> Sequence[str]

phonemes

phonemes(word: str) -> list[str]

pos_tags

pos_tags(words: Sequence[str]) -> list[PosTag]

rhyme_key

rhyme_key(word: str) -> str

rhyme_keys

rhyme_keys(word: str) -> list[str]

stress_pattern

stress_pattern(word: str) -> str

stress_patterns

stress_patterns(word: str) -> list[str]

syllable_count

syllable_count(word: str) -> tuple[int, bool]

syllables

syllables(word: str) -> list[str]

tokenize

tokenize(text: str) -> list[str]

vowel_inventory

vowel_inventory() -> frozenset[str]

vowels

vowels() -> frozenset[str]

word_spans

word_spans(text: str) -> list[tuple[int, str]]

denckring.core.protocol.Constructive

Bases: Protocol

A procedure that can generate, not merely validate.

apply is optional by ADR 0002, so it is not on BaseProcedure. This protocol is how callers ask whether a given procedure has one, and it narrows the type at the same time.

seed was an explicit keyword here and is now an ordinary parameter on SeedParams, carried by the ten procedures that draw. A keyword named in this signature binds before **params and so can never be validated, which is what made seed unvalidatable for all 27.

produce joined apply here for the same reason: runtime_checkable makes isinstance check method presence only, and every ConstructiveProcedure inherits both from the base class, so the set of procedures this protocol matches is unchanged by adding the second name.

apply

apply(
    text: str, *, lang: Lang = "en", **params: Any
) -> str

produce

produce(
    text: str, *, lang: Lang = "en", **params: Any
) -> Production

Capabilities

A pack does not declare a language "supported" or not — it declares a capabilities set, built from string constants defined in denckring.lang.base: TOKENS, ALPHABET, FOLD_DIACRITICS, LETTER_SHAPES, SYLLABLES, SYLLABLES_HEURISTIC, SYLLABLES_DICTIONARY, WORDS, NOUNS, GLOSSES, PHONEMES and STRESS. A procedure, in turn, declares a requires list of the same strings on its catalogue entry. BaseProcedure.check compares the two before running anything: if the pack's capabilities do not cover everything the procedure requires, it raises MissingCapability naming the procedure, the language and the missing capability, rather than falling back to an approximation. Adding a language pack is a matter of implementing LanguagePack and declaring which of these strings it can honestly back — nothing more.