API reference

class openfst_python.pywrapfst.SymbolTable(name='<unspecified>')

Mutable SymbolTable class.

This class wraps the library SymbolTable and exposes both const (i.e., access) and non-const (i.e., mutation) methods of wrapped object.

Unlike other classes in the hierarchy, it has a working constructor and can be used to programmatically construct a SymbolTable in memory.

Args:

name: An optional string indicating the table’s name.

add_symbol(self, symbol, key=NO_SYMBOL)

Adds a symbol to the table and returns the index.

This method adds a symbol to the table. The caller can optionally specify a non-negative integer index for the key.

Args:

symbol: A symbol string. key: An index for the symbol; if not specified, the next index will be

used.

Returns:

The integer key of the new symbol.

add_table(self, syms)

Adds another SymbolTable to this table.

This method merges another symbol table into the current table. All key values will be offset by the current available key.

Args:

syms: A SymbolTable to be merged with the current table.

available_key(self)

Returns an integer indicating the next available key index in the table.

checksum(self)

Returns a bytestring indicating the label-independent MD5 checksum.

copy(self)

Returns a mutable copy of the SymbolTable.

find(self, key)

Given a symbol or index, finds the other one.

This method returns the index associated with a symbol key, or the symbol associated with a index key.

Args:

key: Either a string or an index.

Returns:

If the key is a string, the associated index or NO_LABEL if not found; if

the key is an integer, the associated symbol or an empty string if not found.

get_nth_key(self, pos)

Retrieves the integer index of the n-th key in the table.

Args:

pos: The n-th key to retrieve.

Returns:

The integer index of the n-th key, or NO_LABEL if not found.

labeled_checksum(self)

Returns a bytestring indicating the label-dependent MD5 checksum.

member(self, key)

Given a symbol or index, returns whether it is found in the table.

This method returns a boolean indicating whether the given symbol or index is present in the table. If one intends to perform subsequent lookup, it is better to simply call the find method, catching the KeyError.

Args:

key: Either a string or an index.

Returns:

Whether or not the key is present (as a string or a index) in the table.

name(self)

Returns the symbol table’s name.

num_symbols(self)

Returns the number of symbols in the symbol table.

read(filename)

Reads symbol table from binary file.

This class method creates a new SymbolTable from a symbol table binary file.

Args:

filename: The string location of the input binary file.

Returns:

A new SymbolTable instance.

See also: SymbolTable.read_fst, SymbolTable.read_text.

read_fst(filename, input_table)

Reads symbol table from an FST file without loading the corresponding FST.

This class method creates a new SymbolTable by reading either the input or output symbol table from an FST file, without loading the corresponding FST.

Args:

filename: The string location of the input FST file. input_table: Should the input table be read (True) or the output table

(False)?

Returns:

A new SymbolTable instance, or None if none can be read.

Raises:

FstIOError: Read failed.

See also: SymbolTable.read, SymbolTable.read_text.

read_text(filename)

Reads symbol table from text file.

This class method creates a new SymbolTable from a symbol table text file.

Args:

filename: The string location of the input text file. allow_negative_labels: Should negative labels be allowed? (Not

recommended; may cause conflicts).

Returns:

A new SymbolTable instance.

See also: SymbolTable.read, SymbolTable.read_fst.

write(self, filename)

Serializes symbol table to a file.

This methods writes the SymbolTable to a file in binary format.

Args:

filename: The string location of the output file.

Raises:

FstIOError: Write failed.

write_text(self, filename)

Writes symbol table to text file.

This method writes the SymbolTable to a file in human-readable format.

Args:

filename: The string location of the output file.

Raises:

FstIOError: Write failed.

write_to_string(self)

Serializes SymbolTable to a string.

Returns:

A bytestring.

Raises:

FstIOError: Write to string failed.

See also: read_from_string.

class openfst_python.pywrapfst.Arc(ilabel, olabel, weight, nextstate)

This class represents an arc while remaining agnostic about the underlying arc type. Attributes of the arc can be accessed or mutated, and the arc can be copied.

Attributes:

ilabel: The input label. olabel: The output label. weight: The arc weight. nextstate: The destination state for the arc.

class openfst_python.pywrapfst._MutableFst

(No constructor.)

Mutable FST class, wrapping MutableFstClass.

This class extends _Fst by adding mutation operations.

add_arc(self, state, arc)

Adds a new arc to the FST and return self.

Args:

state: The integer index of the source state. arc: The arc to add.

Returns:

self.

Raises:

FstIndexError: State index out of range. FstOpdexError: Incompatible or invalid weight type.

See also: add_state.

add_state(self)

Adds a new state to the FST and returns the state ID.

Returns:

The integer index of the new state.

See also: add_arc, set_start, set_final.

add_states(self, n)

Adds n new states to the FST.

Args:

n: The number of states to add.

arc_type(self)

Returns a string indicating the arc type.

arcs(self, state)

Returns an iterator over arcs leaving the specified state.

Args:

state: The source state ID.

Returns:

An ArcIterator.

See also: mutable_arcs, states.

arcsort(self, sort_type='ilabel')

Sorts arcs leaving each state of the FST.

This operation destructively sorts arcs leaving each state using either input or output labels.

Args:

sort_type: Either “ilabel” (sort arcs according to input labels) or

“olabel” (sort arcs according to output labels).

Returns:

self.

Raises:

FstArgError: Unknown sort type.

closure(self, closure_plus=False)

Computes concatenative closure.

This operation destructively converts the FST to its concatenative closure. If A transduces string x to y with weight a, then the closure transduces x to y with weight a, xx to yy with weight a otimes a, xxx to yyy with weight a otimes a otimes a, and so on. The empty string is also transduced to itself with semiring One if closure_plus is False.

Args:

closure_plus: If False, do not accept the empty string.

Returns:

self.

concat(self, ifst)

Computes the concatenation (product) of two FSTs.

This operation destructively concatenates the FST with a second FST. If A transduces string x to y with weight a and B transduces string w to v with weight b, then their concatenation transduces string xw to yv with weight a otimes b.

Args:

ifst: The second input FST.

Returns:

self.

connect(self)

Removes unsuccessful paths.

This operation destructively trims the FST, removing states and arcs that are not part of any successful path.

Returns:

self.

copy(self)

Makes a copy of the FST.

decode(self, encoder)

Decodes encoded labels and/or weights.

This operation reverses the encoding performed by encode.

Args:

encoder: An EncodeMapper object used to encode the FST.

Returns:

self.

See also: encode.

delete_arcs(self, state, n=0)

Deletes arcs leaving a particular state.

Args:

state: The integer index of a state. n: An optional argument indicating how many arcs to be deleted. If this

argument is omitted or passed as zero, all arcs from this state are deleted.

Returns:

self.

Raises:

FstIndexError: State index out of range.

See also: delete_states.

delete_states(self, states=None)

Deletes states.

Args:

states: An optional iterable of integer indices of the states to be

deleted. If this argument is omitted, all states are deleted.

Returns:

self.

Raises:

FstIndexError: State index out of range.

See also: delete_arcs.

draw()

draw(self, filename, isymbols=None, osymbols=None, ssymbols=None,

acceptor=False, title=””, width=8.5, height=11, portrait=False, vertical=False, ranksep=0.4, nodesep=0.25, fontsize=14, precision=5, float_format=”g”, show_weight_one=False):

Writes out the FST in Graphviz text format.

This method writes out the FST in the dot graph description language. The graph can be rendered using the dot executable provided by Graphviz.

Args:

filename: The string location of the output dot/Graphviz file. isymbols: An optional symbol table used to label input symbols. osymbols: An optional symbol table used to label output symbols. ssymbols: An optional symbol table used to label states. acceptor: Should the figure be rendered in acceptor format if possible? title: An optional string indicating the figure title. width: The figure width, in inches. height: The figure height, in inches. portrait: Should the figure be rendered in portrait rather than

landscape?

vertical: Should the figure be rendered bottom-to-top rather than

left-to-right?

ranksep: The minimum separation separation between ranks, in inches. nodesep: The minimum separation between nodes, in inches. fontsize: Font size, in points. precision: Numeric precision for floats, in number of chars. float_format: One of: ‘e’, ‘f’ or ‘g’. show_weight_one: Should weights equivalent to semiring One be printed?

See also: text.

encode(self, encoder)

Encodes labels and/or weights.

This operation allows for the representation of a weighted transducer as a weighted acceptor, an unweighted transducer, or an unweighted acceptor by considering the pair (input label, output label), the pair (input label, weight), or the triple (input label, output label, weight) as a single label. Applying this operation mutates the EncodeMapper argument, which can then be used to decode.

Args:

encoder: An EncodeMapper object to be used as the encoder.

Returns:

self.

See also: decode.

final(self, state)

Returns the final weight of a state.

Args:

state: The integer index of a state.

Returns:

The final Weight of that state.

Raises:

FstIndexError: State index out of range.

fst_type(self)

Returns a string indicating the FST type.

input_symbols(self)

Returns the FST’s input symbol table, or None if none is present.

See also: input_symbols.

invert(self)

Inverts the FST’s transduction.

This operation destructively inverts the FST’s transduction by exchanging input and output labels.

Returns:

self.

minimize(self, delta=1e-06, allow_nondet=False)

Minimizes the FST.

This operation destructively performs the minimization of deterministic weighted automata and transducers. If the input FST A is an acceptor, this operation produces the minimal acceptor B equivalent to A, i.e. the acceptor with a minimal number of states that is equivalent to A. If the input FST A is a transducer, this operation internally builds an equivalent transducer with a minimal number of states. However, this minimality is obtained by allowing transition having strings of symbols as output labels, this known in the litterature as a real-time transducer. Such transducers are not directly supported by the library. This function will convert such transducer by expanding each string-labeled transition into a sequence of transitions. This will results in the creation of new states, hence losing the minimality property.

Args:

delta: Comparison/quantization delta. allow_nondet: Attempt minimization of non-deterministic FST?

Returns:

self.

mutable_arcs(self, state)

Returns a mutable iterator over arcs leaving the specified state.

Args:

state: The source state ID.

Returns:

A MutableArcIterator.

See also: arcs, states.

mutable_input_symbols(self)

Returns the FST’s (mutable) input symbol table, or None if none is present.

mutable_output_symbols(self)

Returns the FST’s (mutable) output symbol table, or None if none is present.

num_arcs(self, state)

Returns the number of arcs leaving a state.

Args:

state: The integer index of a state.

Returns:

The number of arcs leaving that state.

Raises:

FstIndexError: State index out of range.

See also: num_states.

num_input_epsilons(self, state)

Returns the number of arcs with epsilon input labels leaving a state.

Args:

state: The integer index of a state.

Returns:

The number of epsilon-input-labeled arcs leaving that state.

Raises:

FstIndexError: State index out of range.

See also: num_output_epsilons.

num_output_epsilons(self, state)

Returns the number of arcs with epsilon output labels leaving a state.

Args:

state: The integer index of a state.

Returns:

The number of epsilon-output-labeled arcs leaving that state.

Raises:

FstIndexError: State index out of range.

See also: num_input_epsilons.

num_states(self)

Returns the number of states.

output_symbols(self)

Returns the FST’s output symbol table, or None if none is present.

See also: input_symbols.

project(self, project_output=False)

Converts the FST to an acceptor using input or output labels.

This operation destructively projects an FST onto its domain or range by either copying each arc’s input label to its output label (the default) or vice versa.

Args:

project_output: Should the output labels be projected?

Returns:

self.

See also: decode, encode, relabel_pairs, relabel_symbols.

properties(self, mask, test)

Provides property bits.

This method provides user access to the properties attributes for the FST. The resulting value is a long integer, but when it is cast to a boolean, it represents whether or not the FST has the mask property.

Args:

mask: The property mask to be compared to the FST’s properties. test: Should any unknown values be computed before comparing against

the mask?

Returns:

A 64-bit bitmask representing the requested properties.

prune(self, delta=0.0009765625, nstate=NO_STATE_ID, weight=None)

Removes paths with weights below a certain threshold.

This operation deletes states and arcs in the input FST that do not belong to a successful path whose weight is no more (w.r.t the natural semiring order) than the threshold t otimes-times the weight of the shortest path in the input FST. Weights must be commutative and have the path property.

Args:

delta: Comparison/quantization delta. nstate: State number threshold. weight: A Weight or weight string indicating the desired weight threshold

below which paths are pruned; if omitted, no paths are pruned.

Returns:

self.

See also: The constructive variant.

push(self, delta=0.0009765625, remove_total_weight=False, to_final=False)

Pushes weights towards the initial or final states.

This operation destructively produces an equivalent transducer by pushing the weights towards the initial state or toward the final states. When pushing weights towards the initial state, the sum of the weight of the outgoing transitions and final weight at any non-initial state is equal to one in the resulting machine. When pushing weights towards the final states, the sum of the weight of the incoming transitions at any state is equal to one. Weights need to be left distributive when pushing towards the initial state and right distributive when pushing towards the final states.

Args:

delta: Comparison/quantization delta. remove_total_weight: If pushing weights, should the total weight be

removed?

to_final: Push towards final states?

Returns:

self.

See also: The constructive variant, which also supports label pushing.

relabel_pairs(self, ipairs=None, opairs=None)

Replaces input and/or output labels using pairs of labels.

This operation destructively relabels the input and/or output labels of the FST using pairs of the form (old_ID, new_ID); omitted indices are identity-mapped.

Args:

ipairs: An iterable containing (older index, newer index) integer pairs. opairs: An iterable containing (older index, newer index) integer pairs.

Returns:

self.

Raises:

FstArgError: No relabeling pairs specified.

See also: decode, encode, project, relabel_tables.

relabel_tables()

relabel_tables(self, old_isymbols=None, new_isymbols=None,

unknown_isymbol=””, attach_new_isymbols=True, old_osymbols=None, new_osymbols=None, unknown_osymbol=””, attach_new_osymbols=True)

Replaces input and/or output labels using SymbolTables.

This operation destructively relabels the input and/or output labels of the FST using user-specified symbol tables; omitted symbols are identity-mapped.

Args:

old_isymbols: The old SymbolTable for input labels, defaulting to the

FST’s input symbol table.

new_isymbols: A SymbolTable used to relabel the input labels unknown_isymbol: Input symbol to use to relabel OOVs (if empty,

OOVs raise an exception)

attach_new_isymbols: Should new_isymbols be made the FST’s input symbol

table?

old_osymbols: The old SymbolTable for output labels, defaulting to the

FST’s output symbol table.

new_osymbols: A SymbolTable used to relabel the output labels. unknown_osymbol: Outnput symbol to use to relabel OOVs (if empty,

OOVs raise an exception)

attach_new_isymbols: Should new_osymbols be made the FST’s output symbol

table?

Returns:

self.

Raises:

FstArgError: No SymbolTable specified.

See also: decode, encode, project, relabel_pairs.

reserve_arcs(self, state, n)

Reserve n arcs at a particular state (best effort).

Args:

state: The integer index of a state. n: The number of arcs to reserve.

Returns:

self.

Raises:

FstIndexError: State index out of range.

See also: reserve_states.

reserve_states(self, n)

Reserve n states (best effort).

Args:

n: The number of states to reserve.

Returns:

self.

See also: reserve_arcs.

reweight(self, potentials, to_final=False)

Reweights an FST using an iterable of potentials.

This operation destructively reweights an FST according to the potentials and in the direction specified by the user. An arc of weight w, with an origin state of potential p and destination state of potential q, is reweighted by p^{-1} otimes (w otimes q) when reweighting towards the initial state, and by (p otimes w) otimes q^{-1} when reweighting towards the final states. The weights must be left distributive when reweighting towards the initial state and right distributive when reweighting towards the final states (e.g., TropicalWeight and LogWeight).

Args:

potentials: An iterable of Weight or weight strings. to_final: Push towards final states?

Returns:

self.

rmepsilon()

rmepsilon(self, queue_type=”auto”, connect=True, weight=None,

nstate=NO_STATE_ID, delta=1e-6):

Removes epsilon transitions.

This operation destructively removes epsilon transitions, i.e., those where both input and output labels are epsilon) from an FST.

Args:

queue_type: A string matching a known queue type; one of: “auto”, “fifo”,

“lifo”, “shortest”, “state”, “top”.

connect: Should output be trimmed? weight: A Weight or weight string indicating the desired weight threshold

below which paths are pruned; if omitted, no paths are pruned.

nstate: State number threshold. delta: Comparison/quantization delta.

Returns:

self.

set_final(self, state, weight)

Sets the final weight for a state.

Args:

state: The integer index of a state. weight: A Weight or weight string indicating the desired final weight; if

omitted, it is set to semiring One.

Returns:

self.

Raises:

FstIndexError: State index out of range. FstOpError: Incompatible or invalid weight.

See also: set_start.

set_input_symbols(self, syms)

Sets the input symbol table.

Passing None as a value will delete the input symbol table.

Args:

syms: A SymbolTable.

Returns:

self.

See also: set_output_symbols.

set_output_symbols(self, syms)

Sets the output symbol table.

Passing None as a value will delete the output symbol table.

Args:

syms: A SymbolTable.

Returns:

self.

See also: set_input_symbols.

set_properties(self, props, mask)

Sets the properties bits.

Args:

props: The properties to be set. mask: A mask to be applied to the props argument before setting the

FST’s properties.

Returns:

self.

set_start(self, state)

Sets a state to be the initial state state.

Args:

state: The integer index of a state.

Returns:

self.

Raises:

FstIndexError: State index out of range.

See also: set_final.

start(self)

Returns the start state.

states(self)

Returns an iterator over all states in the FST.

Returns:

A StateIterator object for the FST.

See also: arcs, mutable_arcs.

text()

text(self, isymbols=None, osymbols=None, ssymbols=None, acceptor=False,

show_weight_one=False, missing_sym=””)

Produces a human-readable string representation of the FST.

This method generates a human-readable string representation of the FST. The caller may optionally specify SymbolTables used to label input labels, output labels, or state labels, respectively.

Args:

isymbols: An optional symbol table used to label input symbols. osymbols: An optional symbol table used to label output symbols. ssymbols: An optional symbol table used to label states. acceptor: Should the FST be rendered in acceptor format if possible? show_weight_one: Should weights equivalent to semiring One be printed? missing_symbol: The string to be printed when symbol table lookup fails.

Returns:

A formatted string representing the machine.

topsort(self)

Sorts transitions by state IDs.

This operation destructively topologically sorts the FST, if it is acyclic; otherwise it remains unchanged. Once sorted, all transitions are from lower state IDs to higher state IDs

Returns:

self.

union(self, ifst)

Computes the union (sum) of two FSTs.

This operation computes the union (sum) of two FSTs. If A transduces string x to y with weight a and B transduces string w to v with weight b, then their union transduces x to y with weight a and w to v with weight b.

Args:

ifst: The second input FST.

Returns:

self.

verify(self)

Verifies that an FST’s contents are sane.

Returns:

True if the contents are sane, False otherwise.

weight_type(self)

Provides the FST’s weight type.

Returns:

A string representing the weight type.

write(self, filename)

Serializes FST to a file.

This method writes the FST to a file in a binary format.

Args:

filename: The string location of the output file.

Raises:

FstIOError: Write failed.

write_to_string(self)

Serializes FST to a string.

Returns:

A bytestring.

Raises:

FstIOError: Write to string failed.

See also: read_from_string.

class openfst_python.pywrapfst.Weight(weight_type, weight_string)

FST weight class.

This class represents an FST weight. When passed as an argument to an FST operation, it should have the weight type of the input FST(s) to said operation.

Args:

weight_type: A string indicating the weight type. weight_string: A string indicating the underlying weight.

Raises:

FstArgError: Weight type not found. FstBadWeightError: Invalid weight.

NoWeight(weight_type)

Constructs a non-member weight in the semiring.

One(weight_type)

Constructs semiring One.

Zero(weight_type)

Constructs semiring zero.

copy(self)

Returns a copy of the Weight.

type(self)

Returns a string indicating the weight type.