expansions — Expansion classes and functions module

This module contains classes for compiling and matching JSpeech Grammar Format rule expansions.

Classes

class jsgf.expansions.AlternativeSet(*expansions)

Class for a set of expansions, one of which can be spoken.

generate()

Generate a matching string for this alternative set.

Each alternative has an equal chance of being chosen for string generation.

If weights are set, then the probability of an alternative is its weight over the sum of all weights:

p = w / sum(weights)
set_weight(child, weight)

Set the weight of a child.

The weight determines how likely it is that an alternative was spoken.

Higher values are more likely, lower values are less likely. A value of 0 means that the alternative will never be matched. Negative weights are not allowed.

Note: weights are compiled as floating-point numbers accurate to 4 decimal places, e.g. 5.0001.

Parameters:
  • child (Expansion|int|str) – child/list index/compiled child to set the weight for.
  • weight (float|int) – weight value - must be >= 0
weights

The dictionary of alternatives to their weights.

Return type:dict
class jsgf.expansions.ChildList(expansion, seq=())

List wrapper class for expansion child lists.

The parent attribute of each child will be set appropriately when they added or removed from lists.

clear()

Remove all expansions from this list and unset their parent attributes.

orphan_children()

Set each child’s parent to None.

class jsgf.expansions.Expansion(children)

Expansion base class.

_make_matcher_element()

Method used by the matcher_element property to create ParserElements.

Subclasses should implement this method for speech matching functionality.

children

List of children.

Returns:ChildList
collect_leaves(order=0, shallow=False)

Collect all descendants of an expansion that have no children. This can include self if it has no children. RuleRefs are also counted as leaves.

Parameters:
  • order – tree traversal order (default 0: pre-order)
  • shallow – whether to not collect leaves from trees of referenced rules
Returns:

list

compiled_tag

Get the compiled tag for this expansion if it has one. The empty string is returned if there is no tag set.

Returns:str
copy(shallow=False)

Make a copy of this expansion. This returns a deep copy by default. Neither referenced rules or their expansions will be deep copied.

Parameters:shallow – whether to create a shallow copy (default: False)
Returns:Expansion
current_match

Currently matched speech value for this expansion.

If the expansion hasn’t been matched, this will be None (if required) or ‘’ (if optional).

Returns:str | None
generate()

Generate a string matching this expansion.

had_match

Whether this expansion has a current_match value that is not ‘’ or None. This will also check if this expansion was part of a complete repetition if it has a Repeat or KleeneStar ancestor.

Returns:bool
invalidate_calculations()

Invalidate calculations stored in the lookup tables that involve this expansion. This only effects mutually_exclusive_of and is_descendant_of, neither of which are used in compiling or matching rules.

This should be called if a child is added to an expansion or if an expansion’s parent is changed outside of what JointTreeContext does.

Some changes may also require invalidating descendants, the map_expansion function can be used with this method to accomplish that:

map_expansion(self, Expansion.invalidate_calculations)
invalidate_matcher()

Method to invalidate the parser element used for matching this expansion. This is method is called automatically when a parent is set or a ChildList is modified. The parser element will be recreated again when required.

This only needs to be called manually if modifying an expansion tree after matching with a Dictation expansion.

is_alternative

Whether or not this expansion has an AlternativeSet ancestor with more than one child.

Returns:bool
is_descendant_of(other)

Whether this expansion is a descendant of another expansion.

Parameters:other – Expansion
Returns:bool
is_optional

Whether or not this expansion has an optional ancestor.

Returns:bool
leaves

Collect all descendants of an expansion that have no children. This can include self if it has no children. RuleRefs are also counted as leaves.

Parameters:
  • order – tree traversal order (default 0: pre-order)
  • shallow – whether to not collect leaves from trees of referenced rules
Returns:

list

leaves_after

Generator function for leaves after this one (if any).

Returns:generator
static make_expansion(e)

Take an object, turn it into an Expansion if it isn’t one and return it.

Parameters:e – str | Expansion
Returns:Expansion
matchable_leaves_after

Generator function yielding all leaves after self that are not mutually exclusive of it.

Returns:generator
matcher_element

Lazily initialised pyparsing ParserElement used to match speech to expansions. It will also set current_match values.

Returns:pyparsing.ParserElement
matches(speech)

Match speech with this expansion, set current_match to the first matched substring and return the remainder of the string.

Matching ambiguous rule expansions is not supported because it not worth the performance hit. Ambiguous rule expansions are defined as some optional literal x followed by a required literal x. For example, successfully matching 'test' for the following rule is not supported:

<rule> = [test] test;
Parameters:speech – str
Returns:str
matching_slice

Slice of the last speech string matched. This will be None initially.

Return type:slice
mutually_exclusive_of(other)

Whether this expansion cannot be spoken with another expansion.

Parameters:other – Expansion
Returns:bool
parent

This expansion’s parent, if it has one.

Setting the parent will call Expansion.invalidate_matcher as necessary on the new and old parents.

Returns:Expansion | None
repetition_ancestor

This expansion’s closest Repeat or KleeneStar ancestor, if it has one.

Returns:Expansion
reset_for_new_match()

Call reset_match_data for this expansion and all of its descendants.

reset_match_data()

Reset any members or properties this expansion uses for matching speech, i.e. current_match values.

This does not invalidate matcher_element.

root_expansion

Traverse to the root expansion r and return it.

Returns:Expansion
tag

JSGF tag for this expansion.

Returns:str
validate_compilable()

Check that the expansion is compilable. If it isn’t, this method should raise a CompilationError.

Raises:CompilationError
class jsgf.expansions.JointTreeContext(root_expansion)

Class that temporarily joins an expansion tree with the expansion trees of all referenced rules by setting the parent relationships.

This is useful when it is necessary to view an expansion tree and the expansion trees of referenced rules as one larger tree. E.g. when determining mutual exclusivity of two expansions, if an expansion is optional or used for repetition in the context of other trees, etc.

Note: this class will reduce the matching performance if used, but will only be noticeable with larger grammars.

On __exit__, the trees will be detached recursively.

This class can be used with Python’s with statement.

static detach_tree(x)

If x is a NamedRuleRef, detach its referenced rule’s expansion from this tree.

Parameters:x – Expansion
static join_tree(x)

If x is a NamedRuleRef, join its referenced rule’s expansion to this tree.

Parameters:x – Expansion
class jsgf.expansions.KleeneStar(expansion)

JSGF Kleene star operator for allowing zero or more repeats of an expansion.

For example:

<kleene> = (please)* don't crash;
generate()

Generate a string matching this expansion.

This method can generate zero or more repetitions of the child expansion, zero repetitions meaning the empty string (“”) will be returned.

Return type:str
class jsgf.expansions.Literal(text, case_sensitive=False)

Expansion class for literals.

case_sensitive

Case sensitivity used when matching and compiling Literal rule expansions.

This property can be True or False. Matching and compilation will be case-sensitive if True and case-insensitive if False. The default value is False.

Return type:bool
Returns:literal case sensitivity
generate()

Generate a string matching this expansion’s text.

This will just return the value of text.

Return type:str
matching_regex_pattern

A regex pattern for matching this expansion.

This property has been left in for backwards compatibility. The Expansion.matches method now uses the matcher_element property instead.

Returns:regex pattern object
text

Text to match/compile.

This will return lowercase text if case_sensitive is not True.

Return type:str
Returns:text
validate_compilable()

Check that the expansion is compilable. If it isn’t, this method should raise a CompilationError.

Raises:CompilationError
class jsgf.expansions.NamedRuleRef(name)

Class used to reference rules by name.

generate()

Generate a string matching the referenced rule’s expansion.

Return type:str
referenced_rule

Find and return the rule this expansion references in the grammar.

This raises an error if the referenced rule cannot be found using self.rule.grammar or if there is no link to a grammar.

Raises:GrammarError
Returns:Rule
class jsgf.expansions.NullRef

Reference expansion for the special NULL rule.

The NULL rule always matches speech. If this reference is used by a rule, that part of the rule expansion requires no speech substring to match.

class jsgf.expansions.OptionalGrouping(expansion)

Class for expansions that can be optionally spoken in a rule.

generate()

Generate a string matching this expansion.

class jsgf.expansions.Repeat(expansion)

JSGF plus operator for allowing one or more repeats of an expansion.

For example:

<repeat> = (please)+ don't crash;
generate()

Generate a string matching this expansion.

This method can generate one or more repetitions of the child expansion.

Return type:str
get_expansion_matches(e)

Get a list of an expansion’s current_match values for each repetition.

Returns:list
get_expansion_slices(e)

Get a list of an expansion’s matching_slice values for each repetition.

Returns:list
repetitions_matched

The number of repetitions last matched.

Returns:int
reset_match_data()

Reset any members or properties this expansion uses for matching speech, i.e. current_match values.

This does not invalidate matcher_element.

class jsgf.expansions.RequiredGrouping(*expansions)

Subclass of Sequence for wrapping multiple expansions in parenthesises.

class jsgf.expansions.RuleRef(referenced_rule)

Subclass of NamedRuleRef for referencing another rule with a Rule object.

Parameters:referenced_rule
class jsgf.expansions.Sequence(*expansions)

Class for expansions to be spoken in sequence.

class jsgf.expansions.VoidRef

Reference expansion for the special VOID rule.

The VOID rule can never be spoken. If this reference is used by a rule, then it will not match unless the reference it is optional.

Functions

jsgf.expansions.filter_expansion(e, func=<function <lambda>>, order=0, shallow=False)

Find all expansions in an expansion tree for which func(x) == True.

Parameters:
  • e – Expansion
  • func – callable (default: the identity function, f(x)->x)
  • order – int
  • shallow – whether to not process trees of referenced rules (default False)
Returns:

list

jsgf.expansions.find_expansion(e, func=<function <lambda>>, order=0, shallow=False)

Find the first expansion in an expansion tree for which func(x) is True and return it. Otherwise return None.

This function will stop searching once a matching expansion is found, unlike the other top-level functions in this module.

Parameters:
  • e – Expansion
  • func – callable (default: the identity function, f(x)->x)
  • order – int
  • shallow – whether to not process trees of referenced rules (default False)
Returns:

Expansion | None

jsgf.expansions.flat_map_expansion(e, func=<function <lambda>>, order=0, shallow=False)

Call map_expansion with the arguments and return a single flat list.

Parameters:
  • e – Expansion
  • func – callable (default: the identity function, f(x)->x)
  • order – int
  • shallow – whether to not process trees of referenced rules (default False)
Returns:

list

jsgf.expansions.map_expansion(e, func=<function <lambda>>, order=0, shallow=False)

Traverse an expansion tree and call func on each expansion returning a tuple structure with the results.

Parameters:
  • e – Expansion
  • func – callable (default: the identity function, f(x)->x)
  • order – int
  • shallow – whether to not process trees of referenced rules (default False)
Returns:

tuple

jsgf.expansions.matches_overlap(m1, m2)

Check whether two regex matches overlap.

Returns:bool
jsgf.expansions.restore_current_matches(e, values, override_none=True)

Traverse an expansion tree and restore matched data using the values dictionary.

Parameters:
  • e – Expansion
  • values – dict
  • override_none – bool
jsgf.expansions.save_current_matches(e)

Traverse an expansion tree and return a dictionary populated with each descendant Expansion and its match data.

This will also include e.

Parameters:e – Expansion
Returns:dict