characterProcessing module

class characterProcessing.LocaleDataMap(localeDataFactory: Callable[[str], _LocaleDataT])

Bases: Generic[_LocaleDataT], object

Allows access to locale-specific data objects, dynamically loading them if needed on request

@param localeDataFactory: the factory to create data objects for the requested locale.

fetchLocaleData(locale: str, fallback: bool = True) _LocaleDataT

Fetches a data object for the given locale. This may mean that the data object is first created and stored if it does not yet exist in the map. The locale is also simplified (country is dropped) if the fallback argument is True and the full locale can not be used to create a data object. @param locale: the locale of the data object requested @param fallback: if true and there is no data for the locale, then the country (if it exists) is stripped and just the language is tried. @return: the data object for the given locale

invalidateLocaleData(locale: str) None

Invalidate the data object (if any) for the given locale. This will cause a new data object to be created when this locale is next requested. @param locale: The locale for which the data object should be invalidated.

invalidateAllData()

Invalidate all data within this locale map. This will cause a new data object to be created for every locale that is next requested.

class characterProcessing.CharacterDescriptions(locale: str)

Bases: object

Represents a map of characters to one or more descriptions (examples) for that character. The data is loaded from a file from the requested locale.

@param locale: The characterDescriptions.dic file will be found by using this locale.

getCharacterDescription(character: str) List[str] | None

Looks up the given character and returns a list containing all the description strings found.

characterProcessing.getCharacterDescription(locale: str, character: str) List[str] | None

Finds a description or examples for the given character, which makes sense in the given locale. @param locale: the locale (language[_COUNTRY]) the description should be for. @param character: the character to fetch the description for. @return: the found description for the given character

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

Bases: IntEnum

The desired symbol level in a speech sequence or in configuration. Note: This enum has its counterpart in the NVDAController RPC interface (nvdaController.idl). Additions to this enum should also be reflected in nvdaController.idl.

NONE = 0
SOME = 100
MOST = 200
ALL = 300
CHAR = 1000
UNCHANGED = -1
class characterProcessing.SpeechSymbol(identifier, pattern=None, replacement=None, level=None, preserve=None, displayName=None)

Bases: object

identifier
pattern
replacement
level
preserve
displayName
class characterProcessing.SpeechSymbols

Bases: object

Contains raw information about the pronunciation of symbols. It does not handle inheritance of data from other sources, processing of text, etc. This is all handled by L{SpeechSymbolProcessor}.

Constructor.

load(fileName: str, allowComplexSymbols: bool = True) None

Load symbol information from a file. :param fileName: The name of the file from which to load symbol information. :param allowComplexSymbols: Whether to allow complex symbols. :raise IOError: If the file cannot be read.

_loadComplexSymbol(line: str) None
_loadSymbolField(input, inputMap=None)
IDENTIFIER_ESCAPES_INPUT = {'#': '#', '0': '\x00', '\\': '\\', 'f': '\x0c', 'n': '\n', 'r': '\r', 't': '\t', 'v': '\x0b'}
IDENTIFIER_ESCAPES_OUTPUT = {'\x00': '0', '\t': 't', '\n': 'n', '\x0b': 'v', '\x0c': 'f', '\r': 'r', '#': '#', '\\': '\\'}
LEVEL_INPUT = {'all': SymbolLevel.ALL, 'char': SymbolLevel.CHAR, 'most': SymbolLevel.MOST, 'none': SymbolLevel.NONE, 'some': SymbolLevel.SOME}
LEVEL_OUTPUT = {SymbolLevel.NONE: 'none', SymbolLevel.SOME: 'some', SymbolLevel.MOST: 'most', SymbolLevel.ALL: 'all', SymbolLevel.CHAR: 'char'}
PRESERVE_INPUT = {'always': 1, 'never': 0, 'norep': 2}
PRESERVE_OUTPUT = {0: 'never', 1: 'always', 2: 'norep'}
_loadSymbol(line)
save(fileName=None)

Save symbol information to a file. @param fileName: The name of the file to which to save symbol information,

C{None} to use the file name last passed to L{load} or L{save}.

@type fileName: str @raise IOError: If the file cannot be written. @raise ValueError: If C{fileName} is C{None}

and L{load} or L{save} has not been called.

_saveSymbolField(output, outputMap=None)
_saveSymbol(symbol)
characterProcessing._getSpeechSymbolsForLocale(locale: str) tuple[SpeechSymbols, SpeechSymbols, ...]
class characterProcessing.SpeechSymbolProcessor(locale: str)

Bases: object

Handles processing of symbol pronunciation for a locale. Pronunciation information is taken from one or more L{SpeechSymbols} instances.

Constructor. @param locale: The locale for which symbol pronunciation should be processed.

localeSymbols: LocaleDataMap[tuple[SpeechSymbols, SpeechSymbols, ...]] = <characterProcessing.LocaleDataMap object>

Caches symbol data for locales.

sources: list[SpeechSymbols]
_replaceGroups(m: Match, string: str) str

Replace matching group references (1, 2, …) with the corresponding matched groups. Also replace \ with and reject other escapes, for escaping coherency. @param m: The currently-matched group @param string: The match replacement string which may contain group references

_regexpRepl(m)
processText(text: str, level: SymbolLevel) str
updateSymbol(newSymbol)

Update information for a symbol if it has changed. If there is a change, the changed information will be added to the user’s symbol data. These changes do not take effect until the symbol processor is reinitialised. @param newSymbol: The symbol to update. @type newSymbol: L{SpeechSymbol} @return: Whether there was a change. @rtype: bool

deleteSymbol(symbol)

Delete a user defined symbol. If the symbol does not exist, this method simply does nothing. These changes do not take effect until the symbol processor is reinitialised. @param symbol: The symbol to delete. @type symbol: L{SpeechSymbol}

isBuiltin(symbolIdentifier: str) bool

Determine whether a symbol is built in. @param symbolIdentifier: The identifier of the symbol in question. @return: C{True} if the symbol is built in,

C{False} if it was added by the user.

characterProcessing.processSpeechSymbols(locale: str, text: str, level: SymbolLevel)

Process some text, converting symbols according to desired pronunciation. @param locale: The locale of the text. @param text: The text to process. @param level: The symbol level to use.

characterProcessing.processSpeechSymbol(locale, symbol)

Process a single symbol according to desired pronunciation. @param locale: The locale of the symbol. @type locale: str @param symbol: The symbol. @type symbol: str

characterProcessing.clearSpeechSymbols()

Clears the symbol data cached by the locale speech symbol processors. This will cause new data to be fetched for the next request to pronounce symbols.

characterProcessing.handlePostConfigProfileSwitch(prevConf=None)
class characterProcessing._SymbolDefinitionSource(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

BUILTIN = 'builtin'

The name of the builtin definition source

USER = 'user'

The source for user dictionaries

class characterProcessing.SymbolDictionaryDefinition(*, name: str, path: str, source: str = <_SymbolDefinitionSource.BUILTIN: 'builtin'>, displayName: str | None = None, allowComplexSymbols: bool = False, mandatory: bool = False)

Bases: object

name: str

The name of the dictionary.

path: str

The path to the dictionary. This should be a formattable string, where {locale} is replaced by the locale to fetch a dictionary for.

source: str = 'builtin'

The source of the definition.

displayName: str | None = None

The translatable name of the dictionary. When not provided, the dictionary can not be visible to the end user.

allowComplexSymbols: bool = False

Whether this dictionary allows complex symbols.

mandatory: bool = False

Whether this dictionary is mandatory. Mandatory dictionaries are always enabled.

symbols: LocaleDataMap[SpeechSymbols]
property userVisible: bool

Whether this dictionary is visible to end users (i.e. in the GUI). Mandatory dictionaries are hidden.

property enabled: bool
getSymbols(locale: str) SpeechSymbols

Gets the symbols for a given locale. :param locale: The locale to get symbols for. :raises FileNotFoundError: When this is not a user dictionary and the locale wasn’t found.

_initSymbols(locale: str) SpeechSymbols
property availableLocales: dict[str, str]

Gets dictionary paths for all available locales.

characterProcessing._symbolDictionaryDefinitions: list[SymbolDictionaryDefinition] = []

A list of available symbol dictionary definitions. These definitions are used to load symbol dictionaries for various locales. The list is filled with definitions from core and from add-ons using _addSymbolDefinitions. With listAvailableSymbolDictionaryDefinitions, there is a public interface to retrieve the definitions.

characterProcessing.listAvailableSymbolDictionaryDefinitions() list[SymbolDictionaryDefinition]

Get available symbol dictionary definitions as initialized in core or in add-ons.

characterProcessing._addSymbolDefinitions()

Adds symbol dictionary definitions to the global _symbolDictionaryDefinitions list.

This function is responsible for initializing the available symbol dictionaries that can be used for various locales. It adds definitions for the built-in symbol dictionaries, as well as any symbol dictionaries defined in enabled add-ons.

The built-in symbol dictionaries include: - “cldr”: Unicode Consortium data (including emoji) - “builtin”: Built-in symbol dictionary with support for complex symbols

For each installed add-on, the function checks the add-on’s manifest for any defined symbol dictionaries, and adds those to the _symbolDictionaryDefinitions list as well.

Finally, a “user” symbol dictionary definition is added.

characterProcessing.initialize()
characterProcessing.terminate()