grascii package

Subpackages

Submodules

grascii.config module

Contains functions for working with a grascii configuration file. Acts as the entry point for the grascii config command.

This can be invoked as a standalone program: $ python -m grascii.config –help

class grascii.config.ConfigPreset(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

An enum for the available config presets.

ANNIVERSARY = 'anniversary'
PREANNIVERSARY = 'preanniversary'
grascii.config.build_argparser(argparser: ArgumentParser) → None

Configure an ArgumentParser parser to parse the config command-line options

Parse argparser:

A fresh ArgumentParser to configure.

grascii.config.cli_delete(args: Namespace) → int

Delete a configuration file using arguments parsed from the command line.

Parameters:

args – A namespace of parsed arguments.

Returns:

A CLI exit code

grascii.config.cli_init(args: Namespace) → int

Create a configuration file using arguments parsed from the command line.

Parameters:

args – A namespace of parsed arguments.

Returns:

A CLI exit code

grascii.config.cli_path(_: Namespace) → int

Print the path to the configuration file.

Returns:

A CLI exit code

grascii.config.config_exists() → bool

Check whether the user configuration file exists.

Returns:

True if the configuration file exists.

grascii.config.create_config(preset: ConfigPreset) → None

Create a configuration file with preset settings.

Parameters:

preset – The configuration to create.

grascii.config.delete_config() → None

Delete a configuration file.

grascii.config.get_config_file_path() → PurePath

Get a path object representing the location of the configuration file.

Returns:

A path object.

grascii.config.get_default_config() → str

Get the text of the default configuration file.

Returns:

A string containing the default configuration.

grascii.config.get_preset_config(preset: ConfigPreset)
grascii.config.main() → None

Run the config command using arguments from sys.argv.

grascii.defaults module

grascii.dephrase module

exception grascii.dephrase.NoWordFound

Bases: Exception

Exception thrown by PhraseFlattener when a Grascii search produces no results

class grascii.dephrase.PhraseFlattener

Bases: Transformer

A Lark transformer that converts a tree from a phrase grammar into a possible translation of the phrase.

DONT(token)
create_token(name: str, value: str = '')
make_opt(name)
optionals = {'opt_in': 'IN', 'opt_of': 'OF', 'opt_to': 'TO', 'opt_your': 'YOUR'}
short_to(children)
start(children)
word(tree)
class grascii.dephrase.StripNameSpace(namespace)

Bases: Transformer

A Lark transformer that removes a namespace prefix from rules

grascii.dephrase.build_argparser(argparser: ArgumentParser) → None

Configure an ArgumentParser parser to parse the dephrase command-line options.

Parameters:

argparser – A fresh ArgumentParser to configure.

grascii.dephrase.cli_dephrase(args: Namespace) → int

Run dephrase using arguments parsed from the command line.

Parameters:

args – A namespace of parsed arguments.

Returns:

A CLI exit code

grascii.dephrase.dephrase(phrase: str, aggressive: bool = False) → Iterable[str]

Decipher a shorthand phrase.

Parameters:

  • phrase – A Grascii string to dephrase.

  • aggressive – A flag enabling a more intense dephrasing strategy.

Returns:

A generator of possible dephrasings

grascii.dephrase.main() → None

Run dephrase using arguments retrieved from sys.argv.

grascii.grammar module

A collection of useful information about the Grascii grammar.

grascii.grammar.ALPHABET = {'&', "'", '(', ')', ',', '-', '.', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'R', 'S', 'T', 'U', 'V', 'X', 'Z', '\\', '^', '_', '|', '~'}

The set of valid characters in the Grascii language.

grascii.grammar.ANNOTATIONS: dict[str, list[tuple[str, ...]]] = {'A': [('~',), ('|',), ('.', ','), ('_',)], "A&'": [('~',), ('_',)], 'A&E': [('~',), ('_',)], 'AU': [('_',)], 'E': [('~',), ('|',), ('.', ','), ('_',)], 'EU': [('_',)], 'I': [('~',), ('|',), ('_',)], 'O': [('(',), ('.', ','), ('_',)], 'OE': [('_',)], 'S': [('(', ')'), (',',)], 'SH': [(',',)], 'SS': [('(', ')')], 'TH': [('(', ')'), (',',)], 'U': [(')',), ('.', ','), ('_',)], 'X': [('(', ')')], 'XS': [('(', ')')], 'Z': [('(', ')'), (',',)]}

A dictionary of annotatable strokes to a sequence of acceptable annotations on the corresponding stroke. The sequence contains tuples of annotations. The tuples are ordered in the same order they must appear in a strict Grascii string. The tuples contain mutually exclusive annotations. Ex: MEDIUM_SOUND and LONG_SOUND

grascii.grammar.ANNOTATION_CHARACTERS = {'(', ')', ',', '.', '_', '|', '~'}

The set of all characters that are annotations.

grascii.grammar.ASPIRATE = "'"

The character corresponding to the aspirate.

grascii.grammar.BOUNDARY = '-'

The character corresponding to a boundary.

grascii.grammar.CONSONANTS = {'B', 'CH', 'D', 'DD', 'DF', 'DM', 'DN', 'DT', 'DV', 'F', 'G', 'J', 'JND', 'JNT', 'K', 'L', 'LD', 'M', 'MD', 'MM', 'MN', 'MT', 'N', 'ND', 'NG', 'NK', 'NT', 'P', 'PND', 'PNT', 'R', 'S', 'SH', 'SS', 'T', 'TD', 'TH', 'TM', 'TN', 'TV', 'V', 'X', 'XS', 'Z'}

A set of all strokes that represent consonants.

grascii.grammar.DISJOINER = '^'

The character corresponding to a disjoiner.

grascii.grammar.HARD_CHARACTERS = {'A', 'B', 'C', 'D', 'E', 'F', 'G', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'R', 'S', 'T', 'U', 'V', 'X', 'Z'}

A set of all alphabetic characters that can appear as the first character in a stroke.

grascii.grammar.ING = "'"

The character corresponding to the -ing ending.

grascii.grammar.INTERSECTION = '\\'

The character corresponding to an intersection.

grascii.grammar.LEFT = '('

A character corresponding to a direction annotation.

grascii.grammar.LONG_SOUND = ','

The character corresponding to the long sound of a standard vowel.

grascii.grammar.LOOP = '|'

The character corresponding to the loop annotation.

grascii.grammar.MEDIUM_SOUND = '.'

The character corresponding to the medium sound of a standard vowel.

grascii.grammar.OBLIQUE = ','

The character corresponding to the oblique annotation.

grascii.grammar.REVERSE = '~'

The character corresponding to the reversing annotation.

grascii.grammar.RIGHT = ')'

A character corresponding to a direction annotation.

grascii.grammar.STROKES = {'A', "A&'", 'A&E', 'AU', 'B', 'CH', 'D', 'DD', 'DF', 'DM', 'DN', 'DT', 'DV', 'E', 'EU', 'F', 'G', 'I', 'J', 'JND', 'JNT', 'K', 'L', 'LD', 'M', 'MD', 'MM', 'MN', 'MT', 'N', 'ND', 'NG', 'NK', 'NT', 'O', 'OE', 'P', 'PND', 'PNT', 'R', 'S', 'SH', 'SS', 'T', 'TD', 'TH', 'TM', 'TN', 'TV', 'U', 'V', 'X', 'XS', 'Z'}

A set of all valid strokes.

grascii.grammar.VOWELS = {'A', "A&'", 'A&E', 'AU', 'E', 'EU', 'I', 'O', 'OE', 'U'}

A set of all strokes that represent vowels.

grascii.grammar.WUNDERBAR = '_'

The character corresponding to the underbar (W) annotation.

grascii.interactive module

Contains an implementation of an Interactive Searcher for an interactive cli experience.

class grascii.interactive.InteractiveSearcher(**kwargs: Unpack[SearcherOptions])

Bases: GrasciiSearcher

This subclass of GrasciiSearcher runs an interactive search experience for performing grascii searches with support for changing search parameters.

search(*, grascii: str | None = None, **kwargs: Unpack[GrasciiSearchOptions]) → None
Parameters:

grascii – Ignored

Parameters:

grascii – Ignored

grascii.interpret module

Acts as the main entry point for the grascii interpret command.

This can be invoked as a standalone program: $ python -m grascii.interpret --help

grascii.interpret.build_argparser(argparser: ArgumentParser) → None

Configure an ArgumentParser parser to parse the interpret command-line options.

Parameters:

argparser – A fresh ArgumentParser to configure.

grascii.interpret.cli_interpret(args: Namespace) → int

Run interpretation using arguments parsed from the command line.

Parameters:

args – A namespace of parsed arguments.

Returns:

A CLI exit code

grascii.interpret.main() → None

Run interpretation using arguments retrieved from sys.argv.

grascii.interpreter module

class grascii.interpreter.GrasciiInterpreter

Bases: object

Produces the canonical interpretation of Grascii strings.

GrasciiInterpreter.interpret is an alternative to GrasciiParser.interpret. Use GrasciiParser when interpretations beyond the canonical interpretation are required, or improved error messages for invalid Grascii strings are desired. Otherwise, use GrasciiInterpreter for better performance.

interpret(grascii: str, preserve_boundaries: bool = False) → list[str | list[str]] | None

Determine the canonical interpretation of the provided Grascii string.

Parameters:

  • grascii – A Grascii string to interpret

  • preserve_boundaries – When False, boundaries in the string (‘-‘) are not included in the resulting interpretation.

Returns:

The canonical interpretation or None if the string is not valid Grascii.

grascii.interpreter.Interpretation

Represents an interpretation of a Grascii string. An Interpretation is a list of strokes and annotation lists. Each stroke is its own element in the interpretation, while sequences of annotations are grouped into their own sublist.

alias of list[str | list[str]]

grascii.interpreter.interpretation_to_string(interpretation: list[str | list[str]]) → str

Generate a string representation of an Interpretation.

Parameters:

interpretation – An Interpretation to generate a string for.

Returns:

A string representation of an Interpretation

grascii.metrics module

Contains metrics for comparing search queries to regular expression matches.

class grascii.metrics.AnnotatedStroke(stroke, annotations)

Bases: NamedTuple

annotations: set[str]

Alias for field number 1

stroke: str

Alias for field number 0

grascii.metrics.determine_shortest_distance(matches: list[tuple[IT, Match[str]]], func: Callable[[IT, Match[str]], CT]) → CT

Determine the minimum value produced by a function on pairs of interpretations and matches. Utility for building metrics.

grascii.metrics.grascii_standard(result: SearchResult[Interpretation]) → tuple[int, int, int, int]

Compute the standard metric for a grascii search.

Parameters:

result – A SearchResult

Returns:

A comparable key representing the distance between an Interpretation and a Match

grascii.metrics.gsequence_distance(seq1: list[AnnotatedStroke], seq2: list[AnnotatedStroke]) → int

Compute a weighed Levenshtein distance between two sequences of annotated strokes.

Parameters:

  • seq1 – A GrasciiSequence

  • seq2 – A second GrasciiSequence

Returns:

A distance between seq1 and seq2.

grascii.metrics.interpretation_to_gsequence(interp: Interpretation) → GrasciiSequence

Convert an interpretation into a GrasciiSequence

Parameters:

interp – The interpretation to convert.

Returns:

A GrasciiSequence.

grascii.metrics.match_to_gsequence(match: Match[str]) → GrasciiSequence

Convert a match into a GrasciiSequence

Parameters:

match – The match to convert.

Returns:

A GrasciiSequence.

grascii.metrics.translation_standard(result: SearchResult[str]) → tuple[int, int]

Compute the standard metric for a reverse search.

Parameters:

result – A SearchResult

Returns:

A comparable key representing the distance between a translation and a Match

grascii.metrics.trivial(result: SearchResult[IT]) → int

The trivial metric.

Parameters:

result – A SearchResult

Returns:

0

grascii.outline module

class grascii.outline.Curve(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

CLOCKWISE = 2
COUNTER_CLOCKWISE = 3
LINE = 1
LOOP = 4
class grascii.outline.Direction(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

EAST = 'E'
NORTH = 'N'
NORTH_EAST = 'NE'
NORTH_WEST = 'NW'
SOUTH = 'S'
SOUTH_EAST = 'SE'
SOUTH_WEST = 'SW'
WEST = 'W'
class grascii.outline.Outline(interpretation: Interpretation)

Bases: object

An alternative to Interpretation as a representation of a Grascii string. It is structured as a linked list and is better for contextual processing of strokes. Outlines infer the directions of directional characters and explicitly add direction annotations.

to_interpretation() → Interpretation

Convert this Outline to an Interpretation

class grascii.outline.Stroke(stroke: str, head_direction: Direction | None = None, head_curve: Curve | None = None, tail_direction: Direction | None = None, tail_curve: Curve | None = None)

Bases: object

The building block of an Outline

add_annotation(annotation: str)
classmethod create(stroke: str) → Stroke
has_annotation(annotation: str) → bool
has_direction_annotation() → bool
class grascii.outline.StrokeType(direction, curve)

Bases: NamedTuple

curve: Curve | None

Alias for field number 1

direction: Direction | None

Alias for field number 0

grascii.parser module

class grascii.parser.GrasciiFlattener(preserve_boundaries: bool = False, start_rule: str = 'start')

Bases: Transformer

A Lark Transformer that converts a parsed Grascii string into an Interpretation.

class grascii.parser.GrasciiParser

Bases: object

Parses and interprets Grascii strings.

interpret(grascii: str, preserve_boundaries: bool = False) → Iterator[Interpretation]

Interpret a Grascii string.

Parameters:

  • grascii – A Grascii string to interpret

  • preserve_boundaries – When False, boundaries in the string (‘-‘) are not included in the resulting interpretations.

Returns:

An iterator over interpretations.

parse(grascii: str) → Tree

Parse the given string into a Tree.

Parameters:

grascii – A Grascii string to parse.

Returns:

An ambiguous parse tree of the Grascii string.

exception grascii.parser.InvalidGrascii(grascii: str, unexpected_input: UnexpectedInput)

Bases: Exception

Exception thrown by the GrasciiParser when provided an invalid string.

grascii.regen module

Contains RegexBuilder for generating regular expression to use in grascii searches.

class grascii.regen.RegexBuilder(**kwargs)

Bases: object

A class used for generating regular expressions used to search from a grascii string based on grascii search options.

Parameters:

  • uncertainty (int: 0, 1, or 2) – The uncertainty of the grascii string.

  • search_mode (str: one of regen.SearchMode values) – The search mode to use.

  • annotation_mode (one of regen.Strictness values) – How to handle annotations in the search.

  • aspirate_mode (one of regen.Strictness values) – How to handle annotations in the search.

  • disjoiner_mode (one of regen.Strictness values) – How to handle annotations in the search.

  • fix_first (bool) – Apply an uncertainty of 0 to the first token.

build_regex(interpretation: Interpretation) → str

Create a regular expression from a grascii interpretation based on the constructor search parameters.

Parameters:

interpretation – The interpretation for which to generate a regular expression.

Returns:

A regular expression.

generate_patterns_map(interpretations: list[Interpretation]) → list[tuple[Interpretation, Pattern]]

Generates a set of compiled regular expressions from a list of interpretations.

Parameters:

interpretations – A list of interpretations to generate patterns for.

Returns:

A list of Interpretations with their corresponding Patterns.

get_starting_letters(interpretations: list[Interpretation]) → set[str]

Get a set of starting letters based on the given interpretations factoring in uncertainty.

Parameters:

interpretations – A list of interpretations to generate starting letters for.

Returns:

A set of characters.

make_annotation_regex(stroke: str, annotations: Iterable[str]) → str

Create a regular expression that matches the stroke with the acceptable annotations and given annotations according to the search options.

Parameters:

  • stroke – The stroke for which to generate annotations.

  • annotations – A collection of annotations used in generating the regular expression.

Returns:

A regular expression.

make_uncertainty_regex(stroke: str, uncertainty: int, annotations: Iterable[str] = ()) → str

Create a regular expression that matches a stroke within a given uncertainty while applying provided annotations.

Parameters:

  • stroke – The stroke for which to generate alternatives.

  • uncertainty – The uncertainty to apply to the stroke.

  • annotations – A list of annotations to use in the generation.

Returns:

A regular expression.

class grascii.regen.SearchMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

An enum representing different search modes.

CONTAIN = 'contain'
END = 'end'
MATCH = 'match'
START = 'start'
class grascii.regen.Strictness(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

An enum representing different levels of strictness for handling annotations, aspirates, and disjoiners in grascii strings.

HIGH = 'strict'
LOW = 'discard'
MEDIUM = 'retain'

grascii.search module

Acts as the main entry point for the grascii search command.

This can be invoked as a standalone program: $ python -m grascii.search --help

class grascii.search.GrasciiSearchOptionsCombined

Bases: dict

annotation_mode: Strictness
aspirate_mode: Strictness
dictionaries: list[str]
disjoiner_mode: Strictness
fix_first: bool
interpretation: Literal['best', 'all']
search_mode: SearchMode
uncertainty: Literal[0, 1, 2]
grascii.search.build_argparser(argparser: ArgumentParser) → None

Configure an ArgumentParser parser to parse the search command-line options.

Parameters:

argparser – A fresh ArgumentParser to configure.

Run a search using arguments parsed from the command line.

Parameters:

args – A namespace of parsed arguments.

Returns:

A CLI exit code

grascii.search.main() → None

Run a search using arguments retrieved from sys.argv.

grascii.search.search(*, grascii: str, **kwargs: Unpack[GrasciiSearchOptionsCombined]) → Iterable[SearchResult]
grascii.search.search(*, interactive: bool, **kwargs: Unpack[SearcherOptions]) → Iterable[SearchResult]
grascii.search.search(*, reverse: str, **kwargs: Unpack[SearcherOptions]) → Iterable[SearchResult]
grascii.search.search(*, regexp: str, **kwargs: Unpack[SearcherOptions]) → Iterable[SearchResult]

Run a grascii dictionary search. Parameters can consist of any parameters used by the search method of any subclass of Searcher. One, and only one, of the parameters listed below is required.

Parameters:

  • grascii – A grascii string to use in a search.

  • interactive – A flag enabling an interactive search.

  • reverse – A word to search for in the dictionary.

  • regexp – A regular expression to use in a search.

Returns:

An iterable of search results, or None if run in interactive mode

grascii.searchers module

Contains the base class for Searchers as well as multiple concrete implementations of it.

class grascii.searchers.GrasciiSearchOptions

Bases: TypedDict

Options for GrasciiSearcher.search.

annotation_mode: Strictness

How to handle annotations in the search.

aspirate_mode: Strictness

How to handle aspirates in the search.

disjoiner_mode: Strictness

How to handle annotations in the search.

fix_first: bool

Apply an uncertainty of 0 to the first token.

interpretation: Literal['best', 'all']

How to handle ambiguous grascii strings.

search_mode: SearchMode

The search mode to use.

uncertainty: Literal[0, 1, 2]

The uncertainty of the grascii string.

class grascii.searchers.GrasciiSearcher(**kwargs: Unpack[SearcherOptions])

Bases: Searcher[list[str | list[str]]]

A subclass of Searcher that performs a search given a Grascii string.

search(*, grascii: str, **kwargs: Unpack[GrasciiSearchOptions]) → Iterable[SearchResult[Interpretation]] | None
Parameters:

grascii – The grascii string to use in the search.

Returns:

An iterable of search results.

Run a search with the given args and sort the search results by the given metric.

class grascii.searchers.RegexSearcher(**kwargs: Unpack[SearcherOptions])

Bases: Searcher[str]

A subclass of Searcher that searches a grascii dictionary given a raw regular expression.

search(*, regexp: str, **kwargs: Any) → Iterable[SearchResult[str]]
Parameters:

regexp – A regular expression to use in a search.

Returns:

An iterable of search results.

class grascii.searchers.ReverseSearcher(**kwargs: Unpack[SearcherOptions])

Bases: RegexSearcher

A subclass of RegexSearcher that searches a grascii dictionary given a word.

search(*, reverse: str, **kwargs: Any) → Iterable[SearchResult[str]]
Parameters:

reverse – A word to search for.

Returns:

An iterable of search results.

Run a search with the given args and sort the search results by the given metric.

class grascii.searchers.SearchResult(matches: list[tuple[IT, Match[str]]], entry: DictionaryEntry, dictionary: Dictionary)

Bases: Generic[IT]

class grascii.searchers.Searcher(**kwargs: Unpack[SearcherOptions])

Bases: ABC, Generic[IT]

An abstract base class for objects that search Grascii dictionaries.

Perform a search of a Grascii Dictionary.

Parameters:

  • patterns – An iterable of interpretations and corresponding compiled regular expression patterns.

  • starting_letters – A set of letters used to index the search in a Grascii Dictionary.

Returns:

An iterable of search results

abstract search(**kwargs) → Iterable[SearchResult[IT]] | None

An abstract method that runs a search with the given search options and returns the results.

Run a search with the given args and sort the search results by the given metric.

class grascii.searchers.SearcherOptions

Bases: TypedDict

Options for Searchers

dictionaries: list[str]

The dictionaries to search

grascii.similarities module

Contains methods for determining the similarity of grascii strokes.

grascii.similarities.get_node(stroke: str) → tuple[str, ...]

Get a tuple of all strokes equivalent to the given stroke.

grascii.similarities.get_similar(stroke: str, distance: int) → set[tuple]

Get a set of all strokes within a distance to the given node.

Parameters:

  • stroke – The stroke to get similars for.

  • distance – The maximum distance of similar strokes.

Returns:

A set of strokes grouped by equivalency.

grascii.validator module

class grascii.validator.GrasciiValidator(ignore_case: bool = False)

Bases: object

Validates Grascii strings.

Parameters:

ignore_case (bool) – Whether to ignore the case of the Grascii string. If False, the Grascii string must be uppercase.

validate(grascii: str) → bool

Check whether the given string is valid Grascii.

Parameters:

grascii – A string to check

Returns:

bool

grascii.validator.get_grascii_regex_str() → str

Get a string that can be compiled into a regular expression that matches Grascii strings.

Module contents

class grascii.BuildMessage(file_name, line, line_number, message, level)

Bases: NamedTuple

file_name: str

Alias for field number 0

level: int

Alias for field number 4

line: str

Alias for field number 1

line_number: int

Alias for field number 2

message: str

Alias for field number 3

class grascii.BuildSummary(time: float, duplicate_count: int, warnings: list[BuildMessage], errors: list[BuildMessage], output_dir: PathLike[str] | None, entry_counts: dict[str, int] | None)

Bases: object

Results of a dictionary build.

Parameters:

  • time (float) – The duration of the build in seconds.

  • duplicate_count (int) – The number of duplicate entries detected.

  • warnings (List[BuildMessage]) – A list of warnings that occurred during the build.

  • errors (List[BuildMessage]) – A list of errors that occurred during the build.

  • output_dir (Optional[os.PathLike]) – The output directory of the dictionary.

  • entry_counts (Optional[Dict[str, int]]) – A dictionary of file names in the output directory to the number of entries written to that file.

duplicate_count: int
entry_counts: dict[str, int] | None
errors: list[BuildMessage]
output_dir: PathLike[str] | None
time: float
warnings: list[BuildMessage]
exception grascii.CancelPipeline

Bases: Exception

An Exception that can be thrown from a pipeline function to cancel the entire pipeline for a given entry.

class grascii.Dictionary(path: Traversable, dtype: DictionaryType, name: str | None = None)

Bases: object

A class that represents a grascii dictionary and provides methods for reading entries from the dictionary.

dump() → list[DictionaryEntry]

Get all the entries in this dictionary.

Returns:

A list of all entries in this dictionary.

classmethod new(name: str | os.PathLike) → Dictionary

Create a new dictionary from its installed name or a file path.

Parameters:

name (Union[str, os.PathLike]) – The name of an installed dictionary (starting with ‘:’) or a path to a dictionary.

Returns:

A new Dictionary for the given name.

open(name: str) → IO[str]

Open a file from the dictionary with the given name for reading. The caller is responsible for closing the file.

Parameters:

name (str) – The name of the file to open.

Returns:

A text stream.

class grascii.DictionaryBuilder(**kwargs)

Bases: object

A class that runs the build process for a grascii dictionary.

Parameters:

  • pipeline (List[PipelineFunc]) – A list of pipeline functions used to process entries. (Optional)

  • count_words (bool) – Whether to enable word count validation. (Default: False)

  • dedup (bool) – Whether to enable duplicate entry prevention. (Default: True)

  • verbosity (int) – Increase the output verbosity. (Default: 0)

  • quiet (bool) – Suppress output. (Default: False)

build(infiles: Iterable[os.PathLike], output: DictionaryOutputOptions | None) → BuildSummary

Run the build based on the build settings given in the constructor.

Parameters:

  • infiles (Iterable[os.PathLike]) – A collection of file paths to dictionary source files.

  • output (Optional[DictionaryOutputOptions]) – Options for dictionary output.

Returns:

A BuildSummary

class grascii.DictionaryEntry(grascii, translation)

Bases: NamedTuple

grascii: str

Alias for field number 0

translation: str

Alias for field number 1

class grascii.DictionaryOutputOptions(output_dir: PathLike, clean: bool = False)

Bases: object

Options for dictionary build output.

Parameters:

  • output_dir (os.PathLike) – The directory where to output the dictionary files.

  • clean (bool) – Whether to delete all files in the output directory before building.

clean: bool = False
output_dir: PathLike
class grascii.DictionaryType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

BUILTIN = 0
INSTALLED = 1
LOCAL = 2
class grascii.GrasciiInterpreter

Bases: object

Produces the canonical interpretation of Grascii strings.

GrasciiInterpreter.interpret is an alternative to GrasciiParser.interpret. Use GrasciiParser when interpretations beyond the canonical interpretation are required, or improved error messages for invalid Grascii strings are desired. Otherwise, use GrasciiInterpreter for better performance.

interpret(grascii: str, preserve_boundaries: bool = False) → list[str | list[str]] | None

Determine the canonical interpretation of the provided Grascii string.

Parameters:

  • grascii – A Grascii string to interpret

  • preserve_boundaries – When False, boundaries in the string (‘-‘) are not included in the resulting interpretation.

Returns:

The canonical interpretation or None if the string is not valid Grascii.

class grascii.GrasciiParser

Bases: object

Parses and interprets Grascii strings.

interpret(grascii: str, preserve_boundaries: bool = False) → Iterator[Interpretation]

Interpret a Grascii string.

Parameters:

  • grascii – A Grascii string to interpret

  • preserve_boundaries – When False, boundaries in the string (‘-‘) are not included in the resulting interpretations.

Returns:

An iterator over interpretations.

parse(grascii: str) → Tree

Parse the given string into a Tree.

Parameters:

grascii – A Grascii string to parse.

Returns:

An ambiguous parse tree of the Grascii string.

class grascii.GrasciiSearchOptions

Bases: TypedDict

Options for GrasciiSearcher.search.

annotation_mode: Strictness

How to handle annotations in the search.

aspirate_mode: Strictness

How to handle aspirates in the search.

disjoiner_mode: Strictness

How to handle annotations in the search.

fix_first: bool

Apply an uncertainty of 0 to the first token.

interpretation: Literal['best', 'all']

How to handle ambiguous grascii strings.

search_mode: SearchMode

The search mode to use.

uncertainty: Literal[0, 1, 2]

The uncertainty of the grascii string.

class grascii.GrasciiSearcher(**kwargs: Unpack[SearcherOptions])

Bases: Searcher[list[str | list[str]]]

A subclass of Searcher that performs a search given a Grascii string.

search(*, grascii: str, **kwargs: Unpack[GrasciiSearchOptions]) → Iterable[SearchResult[Interpretation]] | None
Parameters:

grascii – The grascii string to use in the search.

Returns:

An iterable of search results.

Run a search with the given args and sort the search results by the given metric.

class grascii.GrasciiValidator(ignore_case: bool = False)

Bases: object

Validates Grascii strings.

Parameters:

ignore_case (bool) – Whether to ignore the case of the Grascii string. If False, the Grascii string must be uppercase.

validate(grascii: str) → bool

Check whether the given string is valid Grascii.

Parameters:

grascii – A string to check

Returns:

bool

exception grascii.InvalidGrascii(grascii: str, unexpected_input: UnexpectedInput)

Bases: Exception

Exception thrown by the GrasciiParser when provided an invalid string.

class grascii.RegexSearcher(**kwargs: Unpack[SearcherOptions])

Bases: Searcher[str]

A subclass of Searcher that searches a grascii dictionary given a raw regular expression.

search(*, regexp: str, **kwargs: Any) → Iterable[SearchResult[str]]
Parameters:

regexp – A regular expression to use in a search.

Returns:

An iterable of search results.

class grascii.ReverseSearcher(**kwargs: Unpack[SearcherOptions])

Bases: RegexSearcher

A subclass of RegexSearcher that searches a grascii dictionary given a word.

search(*, reverse: str, **kwargs: Any) → Iterable[SearchResult[str]]
Parameters:

reverse – A word to search for.

Returns:

An iterable of search results.

Run a search with the given args and sort the search results by the given metric.

class grascii.SearchMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

An enum representing different search modes.

CONTAIN = 'contain'
END = 'end'
MATCH = 'match'
START = 'start'
class grascii.SearchResult(matches: list[tuple[IT, Match[str]]], entry: DictionaryEntry, dictionary: Dictionary)

Bases: Generic[IT]

class grascii.Searcher(**kwargs: Unpack[SearcherOptions])

Bases: ABC, Generic[IT]

An abstract base class for objects that search Grascii dictionaries.

Perform a search of a Grascii Dictionary.

Parameters:

  • patterns – An iterable of interpretations and corresponding compiled regular expression patterns.

  • starting_letters – A set of letters used to index the search in a Grascii Dictionary.

Returns:

An iterable of search results

abstract search(**kwargs) → Iterable[SearchResult[IT]] | None

An abstract method that runs a search with the given search options and returns the results.

Run a search with the given args and sort the search results by the given metric.

class grascii.SearcherOptions

Bases: TypedDict

Options for Searchers

dictionaries: list[str]

The dictionaries to search

class grascii.Strictness(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

An enum representing different levels of strictness for handling annotations, aspirates, and disjoiners in grascii strings.

HIGH = 'strict'
LOW = 'discard'
MEDIUM = 'retain'
grascii.interpretation_to_string(interpretation: list[str | list[str]]) → str

Generate a string representation of an Interpretation.

Parameters:

interpretation – An Interpretation to generate a string for.

Returns:

A string representation of an Interpretation