API Reference

A list of the full API reference of all public classes and functions is below.

Public members can (and should) be imported from graphtransliterator:

from graphtransliterator import GraphTransliterator

Bundled transliterators require that graphtransliterator.transliterators: be imported:

import graphtransliterator.transliterators
transliterators.iter_names()

Core Classes

class graphtransliterator.GraphTransliterator(*args: Any, **kwargs: Any)

static from_dict_file(dict_filename: str, **kwargs: Any) → GraphTransliterator

Alias or file loader for dictionary/json files.

static from_json(json_str: str, **kwargs: Any) → GraphTransliterator

Load a GraphTransliterator from a JSON string.

static from_json_file(json_filename: str, **kwargs: Any) → GraphTransliterator

Load a GraphTransliterator from a JSON file.

inject_subgraph(other: GraphTransliterator, prefix_tokens: list[str] | None = None) → GraphTransliterator

Injects another GraphTransliterator’s ruleset as a subgraph extension.

merge(other: GraphTransliterator) → GraphTransliterator

Merges another GraphTransliterator context cleanly into this one.

static merge_easyreading_configs(config1: EasyReadingDict, config2: EasyReadingDict) → EasyReadingDict

Combines two raw Easy Reading configurations together.

property settings: dict[str, Any]

Returns the structural dictionary of current state matching SettingsSchema.

class graphtransliterator.CoverageTransliterator(*args: Any, **kwargs: Any)

Subclass of GraphTransliterator logging graph and onmatch rule traversal.

Bundled Transliterators

graphtransliterator.transliterators

class graphtransliterator.transliterators.Any(*args, **kwargs)

Special type indicating an unconstrained type.

• Any is compatible with every type.

• Any assumed to have all methods.

• All values assumed to be instances of Any.

Note that all the above statements are true from the point of view of static type checkers. At runtime, Any should not be used with instance checks.

class graphtransliterator.transliterators.Bundled(*args: Any, **kwargs: Any)

Subclass of GraphTransliterator used for bundled Graph Transliterators.

property directory: str

Directory of bundled transliterator, used to load settings.

from_bundled_JSON(check_ambiguity: bool = False, coverage: bool = False, **kwargs: Any) → Bundled

Initialize from bundled JSON file (best for speed).

from_bundled_YAML(check_ambiguity: bool = True, coverage: bool = True, **kwargs: Any) → Bundled

Initialize from bundled YAML file (best for development).

generate_yaml_tests(file: Any | None = None) → str

Generates YAML tests with complete coverage.

load_yaml_tests() → dict[str, str]

Load YAML tests mapping.

property name: str

Name of bundled transliterator, e.g. ‘Example’

classmethod new(method: str = 'yaml', **kwargs: Any) → Bundled

Return a new class instance from method (json/yaml).

run_tests(transliteration_tests: dict[str, str]) → None

Run transliteration tests.

run_yaml_tests() → bool

Run YAML tests in MODULE/tests/MODULE_tests.yaml.

property yaml_tests_filen: str

Absolute path to the bundled YAML test file.

Type:

str

class graphtransliterator.transliterators.Example(*args: Any, **kwargs: Any)

Example Bundled Graph Transliterator.

class graphtransliterator.transliterators.ITRANSDevanagariToUnicode(*args: Any, **kwargs: Any)

ITRANS Devanagari to Unicode Transliterator.

class graphtransliterator.transliterators.MetadataSchema(*, only: Sequence[str] | AbstractSet[str] | None = None, exclude: Sequence[str] | AbstractSet[str] = (), many: bool | None = None, context: dict | None = None, load_only: Sequence[str] | AbstractSet[str] = (), dump_only: Sequence[str] | AbstractSet[str] = (), partial: bool | Sequence[str] | AbstractSet[str] | None = None, unknown: str | None = None)

Schema for Bundled metadata.

graphtransliterator.transliterators.iter_names() → Iterator[str]

Iterate through bundled bundled transliterator names.

graphtransliterator.transliterators.iter_transliterators(**kwds)

Yield instances of all bundled GraphTransliterator subclasses.

Graph Classes

class graphtransliterator.DirectedGraph(nodes: list[Node[T, N]] | None = None, edges: list[Edge[E]] | None = None)

A directed graph representation storing nodes and edges in a flat structure.

add_edge(source: int, target: int, data: E | None = None) → None

Add a directed edge connecting a source NodeId to a target NodeId.

add_node(data: N | None = None, token: Any = None, type: Any = None, label: str | None = None, **kwargs: Any) → int

Append a node to the graph and return its generated integer NodeId.

property edge_list: list[tuple[int, int]]

Return a list of all edge connection coordinates as (source, target) tuples.

get_edge(source: int, target: int) → dict[str, Any] | None

Return the edge payload or full edge structure connecting source and target.

Parameters:

• source – The source node identifier.

• target – The target node identifier.

Returns:

The edge’s data dictionary if it is a dict, or the full edge structure dict if data is not a dictionary. Returns None if no matching edge exists.

Note

For backward compatibility, if an edge’s data property contains a non-dict value (e.g., a primitive string), the method returns the full edge dictionary (including source, target, and data keys) rather than just the payload.

get_node(node_id: int) → Node[T, N] | None

Return node by numeric NodeId if present.

to_dict() → LoadedGraphDict[T, N, E]

Export graph layout as canonical flat dictionary matching TypeScript.

class graphtransliterator.VisitLoggingDirectedGraph(graph: DirectedGraph[T, N, E])

Subclass monitoring runtime traversal over nodes and edges.

check_coverage(raise_exception: bool = True) → bool

Validate if all edges in graph configuration were traversed.

clear_visited() → None

Reset tracked graph metadata.

visit_edge(source: int, target: int) → None

Log traversal of an edge connection.

visit_node(node_id: int) → None

Log traversal of a node.

Rule Classes

class graphtransliterator.TransliterationRule

A transliteration rule containing match conditions and cost.

class graphtransliterator.OnMatchRule

Rule adding text between specific combinations of matched rules.

class graphtransliterator.WhitespaceRule

Whitespace rule definition (renamed from WhitespaceRule for 1:1 parity).

Exceptions

exception graphtransliterator.GraphTransliteratorException

Base exception class. All Graph Transliterator-specific exceptions should subclass this class.

exception graphtransliterator.AmbiguousTransliterationRulesException

Raised when multiple transliteration rules can match the same pattern. Details of ambiguities are given in a logging.warning().

exception graphtransliterator.NoMatchingTransliterationRuleException

Raised when no transliteration rule can be matched at a particular location in the input string’s tokens. Details of the location are given in a logging.warning().

exception graphtransliterator.UnrecognizableInputTokenException

Raised when a character in the input string does not correspond to any tokens in the GraphTransliterator’s token settings. Details of the location are given in a logging.warning().

Schemas

class graphtransliterator.DirectedGraphSchema(*, only: Sequence[str] | AbstractSet[str] | None = None, exclude: Sequence[str] | AbstractSet[str] = (), many: bool | None = None, context: dict | None = None, load_only: Sequence[str] | AbstractSet[str] = (), dump_only: Sequence[str] | AbstractSet[str] = (), partial: bool | Sequence[str] | AbstractSet[str] | None = None, unknown: str | None = None)

Canonical schema for DirectedGraph matching TypeScript LoadedGraphDict.

class graphtransliterator.EasyReadingSettingsSchema(*, only: Sequence[str] | AbstractSet[str] | None = None, exclude: Sequence[str] | AbstractSet[str] = (), many: bool | None = None, context: dict | None = None, load_only: Sequence[str] | AbstractSet[str] = (), dump_only: Sequence[str] | AbstractSet[str] = (), partial: bool | Sequence[str] | AbstractSet[str] | None = None, unknown: str | None = None)

Schema for easy reading settings format.

class graphtransliterator.GraphTransliteratorSchema(*, only: Sequence[str] | AbstractSet[str] | None = None, exclude: Sequence[str] | AbstractSet[str] = (), many: bool | None = None, context: dict | None = None, load_only: Sequence[str] | AbstractSet[str] = (), dump_only: Sequence[str] | AbstractSet[str] = (), partial: bool | Sequence[str] | AbstractSet[str] | None = None, unknown: str | None = None)

Canonical Unified Schema for GraphTransliterator config & execution state.

class graphtransliterator.OnMatchRuleSchema(*, only: Sequence[str] | AbstractSet[str] | None = None, exclude: Sequence[str] | AbstractSet[str] = (), many: bool | None = None, context: dict | None = None, load_only: Sequence[str] | AbstractSet[str] = (), dump_only: Sequence[str] | AbstractSet[str] = (), partial: bool | Sequence[str] | AbstractSet[str] | None = None, unknown: str | None = None)

Schema for OnMatchRule.

class graphtransliterator.SettingsSchema(*, only: Sequence[str] | AbstractSet[str] | None = None, exclude: Sequence[str] | AbstractSet[str] = (), many: bool | None = None, context: dict | None = None, load_only: Sequence[str] | AbstractSet[str] = (), dump_only: Sequence[str] | AbstractSet[str] = (), partial: bool | Sequence[str] | AbstractSet[str] | None = None, unknown: str | None = None)

Schema for full transliterator settings.

class graphtransliterator.TransliterationRuleSchema(*, only: Sequence[str] | AbstractSet[str] | None = None, exclude: Sequence[str] | AbstractSet[str] = (), many: bool | None = None, context: dict | None = None, load_only: Sequence[str] | AbstractSet[str] = (), dump_only: Sequence[str] | AbstractSet[str] = (), partial: bool | Sequence[str] | AbstractSet[str] | None = None, unknown: str | None = None)

class graphtransliterator.WhitespaceDictSettingsSchema(*, only: Sequence[str] | AbstractSet[str] | None = None, exclude: Sequence[str] | AbstractSet[str] = (), many: bool | None = None, context: dict | None = None, load_only: Sequence[str] | AbstractSet[str] = (), dump_only: Sequence[str] | AbstractSet[str] = (), partial: bool | Sequence[str] | AbstractSet[str] | None = None, unknown: str | None = None)

Schema for Whitespace definition as a dict.

class graphtransliterator.WhitespaceSettingsSchema(*, only: Sequence[str] | AbstractSet[str] | None = None, exclude: Sequence[str] | AbstractSet[str] = (), many: bool | None = None, context: dict | None = None, load_only: Sequence[str] | AbstractSet[str] = (), dump_only: Sequence[str] | AbstractSet[str] = (), partial: bool | Sequence[str] | AbstractSet[str] | None = None, unknown: str | None = None)

Schema for Whitespace definition that loads as a WhitespaceRule.