Python API

The supported public API is exported from the top-level phonodist package. The package version is available as phonodist.__version__.

Core functions

`pronunciation_distance`

Computes the normalized feature-align/1 distance.

phonodist.pronunciation_distance(source, target, *, language=None, ignore_stress=None, explain=False)[source]

Compute normalized feature-align/1 distance between IPA values.

Parameters:

source (str) – IPA pronunciations to compare.
target (str) – IPA pronunciations to compare.
language (str or None) – Language-profile tag; None selects universal mode without language-specific profile rules.
ignore_stress (bool or None) – Stress policy passed to IPA parsing. None uses the selected profile’s default, or ignores stress in universal mode. Explicit False is unsupported by feature-align/1 and raises NotImplementedError.
explain (bool) – If true, include the deterministic segment-alignment traceback in DistanceResult.operations. The default score-only path returns an empty operations tuple.

Returns:

Normalized distance, raw alignment cost, denominator, parsed inputs, optional operations, and metric/profile/backend provenance.

Return type:

DistanceResult

Raises:

InvalidIPAError – If an input cannot be normalized into parseable IPA.
UnknownLanguageProfileError – If language does not resolve to a bundled profile.
UnknownSegmentError – If the selected feature backend cannot represent an input segment.
NotImplementedError – If ignore_stress=False requests unimplemented stress-sensitive scoring.

Notes

The score is bounded to [0, 1] and is not a calibrated human perceptual distance. Score-only and traceback modes are intended to produce the same score; explain=True adds operation detail. Stress is ignored by this metric. Use compare_pronunciations() for structural stress diagnostics.

`compare_pronunciations`

Returns an ipa-compare/1 structural comparison with an embedded segmental distance result.

phonodist.compare_pronunciations(source, target, *, language=None, explain=False)[source]

Classify structural differences between two IPA pronunciations.

Parameters:

source (str) – IPA pronunciations to compare.
target (str) – IPA pronunciations to compare.
language (str or None) – Optional language-profile tag for notation aliases and sequence equivalences; None uses universal rules.
explain (bool) – If true, include segment-alignment and stress-operation details.

Returns:

ipa-compare/1 classification, canonical sides, anchored stress events, and an embedded stress-free feature-align/1 result.

Return type:

PronunciationComparison

Raises:

InvalidIPAError – If an input contains no parseable IPA content.
UnknownLanguageProfileError – If language does not resolve to a bundled profile.
UnknownSegmentError – If the feature backend cannot represent an input segment.

Notes

Stress anchors count canonical segments preceding each stress mark. The classification is structural, not a calibrated stress-distance model or a judgment about which pronunciation is correct. The profile is optional.

`parse_ipa`

Normalizes and parses IPA into a public parsed-pronunciation result.

phonodist.parse_ipa(value, *, language=None, ignore_stress=None)[source]

Normalize IPA text and split it into IPA units.

Parameters:

value (str) – IPA string to normalize. Matching outer /.../ or [...] delimiters and surrounding whitespace are stripped.
language (str or None) – Bundled language-profile tag used for profile defaults and notation aliases. None selects universal parsing. Aliases include de, de-DE, and de_de for the German profile.
ignore_stress (bool or None) – Whether to remove primary/secondary stress markers. None uses the selected profile’s default; in universal mode it defaults to True.

Returns:

Original and normalized text, canonical segment units, and diagnostics.

Return type:

ParsedPronunciation

Raises:

InvalidIPAError – If value is not a string or a non-empty value normalizes to no parseable content.
UnknownLanguageProfileError – If language does not resolve to a bundled profile.

Notes

Normalization applies NFC, ignores internal whitespace and Unicode format characters, and canonicalizes supported tie-bar variants. It does not check whether every segment is supported by the metric’s feature backend.

`segment_distance`

Returns a feature distance for two IPA segments.

phonodist.segment_distance(left, right)[source]

Return normalized PanPhon feature distance for two IPA segments.

Parameters:

left (str) – IPA segments to compare. Each value must be recognized as exactly one segment by the PanPhon backend.
right (str) – IPA segments to compare. Each value must be recognized as exactly one segment by the PanPhon backend.

Returns:

Unweighted feature difference normalized to [0, 1].

Return type:

float

Raises:

UnknownSegmentError – If either input is not a supported single segment or their feature vectors are incompatible.

Profiles

phonodist.available_profiles()[source]

Return identifiers of the profiles bundled in this package.

Returns:: Canonical IDs for profiles currently bundled with this package. The current set is ("de-DE",); this is not dynamic profile discovery.
Return type:: tuple of str

phonodist.get_profile(language)[source]

Load a bundled language profile by ID or supported alias.

Parameters:

language (str) – Profile identifier. For the bundled German profile, de, de-DE, and de_de resolve to canonical ID de-DE (case-insensitively).

Returns:

Immutable profile metadata and sparse rules.

Return type:

LanguageProfile

Raises:

UnknownLanguageProfileError – If no bundled profile matches the normalized identifier.
ProfileValidationError – If the profile data is invalid.

Profile names and aliases are described in Language profiles.

Distance results

class phonodist.DistanceResult(distance, raw_cost, denominator, source, target, operations, metric, metric_version, language, profile_version, backend, backend_version, feature_set)[source]

Bases: object

Score, optional traceback, and provenance for feature-align/1.

distance is normalized to [0, 1] as raw_cost / denominator; it is zero when both segment sequences are empty. A zero score can result from canonicalization or a zero-cost profile equivalence, not only identical original strings.

Parameters:

distance (float)
raw_cost (float)
denominator (float)
source (ParsedPronunciation)
target (ParsedPronunciation)
operations (tuple[AlignmentOperation, ...])
metric (str)
metric_version (str)
language (str | None)
profile_version (str | None)
backend (str)
backend_version (str)
feature_set (str)

distance

Normalized feature distance in [0, 1].

Type:: float

raw_cost

Unnormalized sum of alignment operation costs.

Type:: float

denominator

Maximum of source and target segment counts, represented as a float.

Type:: float

source, target

Parsed inputs used for scoring.

Type:: ParsedPronunciation

operations

Deterministic traceback when explain=True; otherwise an empty tuple.

Type:: tuple of AlignmentOperation

metric

Metric identifier, currently feature-align.

Type:: str

metric_version

Metric semantics version.

Type:: str

language

Normalized selected profile tag, or None in universal mode.

Type:: str or None

profile_version

Selected profile version, or None without a profile.

Type:: str or None

backend

Feature backend name.

Type:: str

backend_version

Resolved feature backend version.

Type:: str

feature_set

Backend feature set used for the calculation.

Type:: str

class phonodist.AlignmentOperation(source, target, kind, cost, reason)[source]

Bases: object

One operation in a segment alignment traceback.

Parameters:

source (tuple[str, ...])
target (tuple[str, ...])
kind (Literal['match', 'substitute', 'insert', 'delete', 'sequence_equivalence'])
cost (float)
reason (str)

source

Source-side segment sequence; empty for an insertion.

Type:: tuple of str

target

Target-side segment sequence; empty for a deletion.

Type:: tuple of str

kind

Operation kind: match, substitute, insert, delete, or sequence equivalence.

Type:: str

cost

Unnormalized operation cost in the metric’s alignment units. Costs are between zero and one per operation; insertion/deletion cost one.

Type:: float

reason

Explanation code or profile-rule rationale for the operation.

Type:: str

class phonodist.ParsedPronunciation(original, normalized, segments, diagnostics=())[source]

Bases: object

Normalized IPA input and its segment-level representation.

Parameters:

original (str)
normalized (str)
segments (tuple[str, ...])
diagnostics (tuple[ParseDiagnostic, ...])

original

Input value before normalization.

Type:: str

normalized

NFC-normalized IPA after whitespace/format handling, stress policy, and any selected profile aliases.

Type:: str

segments

Canonical IPA units produced from the normalized text.

Type:: tuple of str

diagnostics

Normalization observations; offsets refer to the normalized working input rather than necessarily to the original string.

Type:: tuple of ParseDiagnostic

class phonodist.ParseDiagnostic(offset, text, codepoint, category, action, reason)[source]

Bases: object

A normalization observation made while preparing IPA input.

Parameters:

offset (int)
text (str)
codepoint (str)
category (str)
action (Literal['ignored', 'normalized', 'unknown'])
reason (str)

offset

Unicode codepoint offset in the normalized working input, after outer delimiters and surrounding whitespace have been removed; this is not necessarily an offset into ParsedPronunciation.original.

Type:: int

text

Character or text observed.

Type:: str

codepoint

Unicode codepoint notation for the observed text.

Type:: str

category

Unicode general category or categories.

Type:: str

action

Normalization action, such as ignored or normalized.

Type:: str

reason

Machine-readable explanation of the action.

Type:: str

Structural comparison results

class phonodist.PronunciationComparison(classification, source, target, raw_equal, canonical_equal, segment_equal, stress_equal, segment_relation, segmental, stress_operations, metric, metric_version)[source]

Bases: object

Structural ipa-compare/1 result with an embedded segmental score.

Parameters:

classification (Literal['exact', 'notation_only', 'stress_only', 'phonetic_equivalent', 'stress_and_phonetic_equivalent', 'segmental', 'stress_and_segmental'])
source (ComparisonPronunciation)
target (ComparisonPronunciation)
raw_equal (bool)
canonical_equal (bool)
segment_equal (bool)
stress_equal (bool)
segment_relation (Literal['exact', 'equivalent', 'different'])
segmental (DistanceResult)
stress_operations (tuple[StressOperation, ...])
metric (str)
metric_version (str)

classification

Structural classification; see ComparisonKind.

Type:: str

source, target

Parsed sides, including canonical segments and anchored stress events.

Type:: ComparisonPronunciation

raw_equal

Whether the original input strings are identical.

Type:: bool

canonical_equal

Whether both canonical segment sequences and stress events are equal.

Type:: bool

segment_equal

Whether the canonical segment sequences are equal.

Type:: bool

stress_equal

Whether the anchored stress events are equal.

Type:: bool

segment_relation

exact, equivalent, or different segment relation.

Type:: str

segmental

Embedded stress-free feature-align/1 result.

Type:: DistanceResult

stress_operations

Deterministic event insertions, deletions, and replacements.

Type:: tuple of StressOperation

metric

Structural metric identifier.

Type:: str

metric_version

Structural metric version.

Type:: str

class phonodist.ComparisonPronunciation(original, normalized, segments, stress, diagnostics=())[source]

Bases: object

A normalized pronunciation split into canonical segments and stress.

Parameters:

original (str)
normalized (str)
segments (tuple[str, ...])
stress (tuple[StressEvent, ...])
diagnostics (tuple[ParseDiagnostic, ...])

original

Input IPA string before normalization.

Type:: str

normalized

NFC-normalized IPA after supported format/spacing normalization and profile aliases; stress markers are retained.

Type:: str

segments

Canonical stress-free segment sequence. Entries are segment strings, not codepoint offsets.

Type:: tuple of str

stress

Primary and secondary events anchored by the number of preceding canonical segments.

Type:: tuple of StressEvent

diagnostics

Normalization observations associated with this pronunciation.

Type:: tuple of ParseDiagnostic

class phonodist.StressEvent(kind, anchor)[source]

Bases: object

A primary or secondary stress mark in an IPA comparison.

Parameters:

kind (Literal['primary', 'secondary'])
anchor (int)

kind

Stress kind, either primary or secondary.

Type:: str

anchor

Number of canonical segments before the stress mark. Zero means before the first segment; the segment count means after the final segment.

Type:: int

class phonodist.StressOperation(kind, source, target)[source]

Bases: object

One insertion, deletion, or kind replacement in aligned stress events.

Parameters:

kind (Literal['insert', 'delete', 'replace'])
source (StressEvent | None)
target (StressEvent | None)

kind

Operation kind: insert, delete, or replace.

Type:: str

source

Source-side event, or None when inserted.

Type:: StressEvent or None

target

Target-side event, or None when deleted.

Type:: StressEvent or None

ComparisonKind is one of exact, notation_only, stress_only, phonetic_equivalent, stress_and_phonetic_equivalent, segmental, or stress_and_segmental. SegmentRelation is exact, equivalent, or different. Their structural meanings are explained in Structural IPA comparison.

Language profiles

class phonodist.LanguageProfile(id, version, name, default_ignore_stress, inventory, aliases, sequence_equivalences, sources)[source]

Bases: object

Bundled language-specific defaults and sparse IPA comparison rules.

inventory is descriptive metadata, not an exhaustive segment rejection list; metric v1 uses PanPhon as the authority for feature availability.

Parameters:

id (str)
version (str)
name (str)
default_ignore_stress (bool)
inventory (tuple[str, ...])
aliases (tuple[AliasRule, ...])
sequence_equivalences (tuple[SequenceEquivalence, ...])
sources (tuple[str, ...])

id

Canonical profile identifier.

Type:: str

version

Profile data version, recorded in distance provenance.

Type:: str

name

Human-readable profile name.

Type:: str

default_ignore_stress

Default stress policy used when parsing with this profile.

Type:: bool

inventory

Descriptive inventory metadata; not an exhaustive accepted-segment set.

Type:: tuple of str

aliases

Representation-level notation aliases.

Type:: tuple

sequence_equivalences

Profile-specific segment-sequence equivalences and their costs.

Type:: tuple

sources

Provenance references for the profile rules.

Type:: tuple of str

Profile inventory is descriptive metadata; it is not an exhaustive list of segments accepted by the metric. See Language profiles.

Exceptions

All package domain exceptions inherit from PhonodistError.

exception phonodist.PhonodistError[source]

Bases: Exception

Base class for phonodist errors.

exception phonodist.InvalidIPAError[source]

Bases: PhonodistError

Raised when an IPA value cannot be normalized or parsed.

exception phonodist.UnknownSegmentError[source]

Bases: PhonodistError

Raised when the feature backend cannot represent an IPA segment.

exception phonodist.UnknownLanguageProfileError[source]

Bases: PhonodistError

Raised when a requested language profile is unavailable.

exception phonodist.ProfileValidationError[source]

Bases: PhonodistError

Raised when bundled or supplied profile data is invalid.

InvalidIPAError reports malformed or invalid input. UnknownSegmentError reports IPA segments unsupported by the configured feature backend. UnknownLanguageProfileError reports a language tag without a bundled profile; ProfileValidationError reports invalid profile data.