voca package — voca version = release = version = release = 0.1.4 documentation

# voca package

## Subpackages

- voca.plugins package
  - Submodules
  - voca.plugins.basic module
  - voca.plugins.math module
  - voca.plugins.no module
  - voca.plugins.python module
  - voca.plugins.stopstart module
  - voca.plugins.terminator module
  - voca.plugins.turtle_context module
  - voca.plugins.yes module
  - Module contents

## Submodules

## voca.app module

`voca.app.` `main`(should_log: bool) → None

  Set up the app execution environment.

  Parameters

    should_log – Enable or disable logging.

## voca.caster_adapter module

class `voca.caster_adapter.` `ActionSequence`(actions: List[AsyncActionType])

  Bases: `object`

  `execute`(arg=None)

class `voca.caster_adapter.` `AsyncActionType`(*args, **kwargs)

  Bases: `typing_extensions.Protocol`

  `execute`(arg=None) → None

class `voca.caster_adapter.` `AttributeHaver`

  Bases: `object`

class `voca.caster_adapter.` `CCRMerger`

  Bases: `object`

  `CORE` = 1

class `voca.caster_adapter.` `CasterTransformer`

  Bases: `lark.visitors.Transformer`

  `n`(arg)

class `voca.caster_adapter.` `Choice`(name: str, mapping: dict)

  Bases: `object`

  `make_definitions`()

class `voca.caster_adapter.` `ConditionalAction`(condition: types.FunctionType, action: RegisteredAction)

  Bases: `object`

  `execute`(arg=None)

class `voca.caster_adapter.` `DelayAction`(duration: float)

  Bases: `object`

  `execute`(arg=None)

class `voca.caster_adapter.` `Dictation`(name: str)

  Bases: `object`

  `make_definitions`()

class `voca.caster_adapter.` `FunctionAction`(callable: types.FunctionType, positional_arguments: tuple, keyword_arguments: dict)

  Bases: `object`

  `execute`(arg)

class `voca.caster_adapter.` `Grammar`(name: str, context: AppContext)

  Bases: `object`

class `voca.caster_adapter.` `IntegerRefST`(name: str, start: int, end: int)

  Bases: `object`

  `make_definitions`()

`voca.caster_adapter.` `Key`(text)

class `voca.caster_adapter.` `KeyAction`(name: str)

  Bases: `object`

  `execute`(arg=None)

class `voca.caster_adapter.` `LazyLoader`

  Bases: `object`

class `voca.caster_adapter.` `MergeRule`

  Bases: `object`

class `voca.caster_adapter.` `MyRepeat`(extra: str)

  Bases: `object`

class `voca.caster_adapter.` `Patch`(module: types.ModuleType, name: str, new: object)

  Bases: `object`

class `voca.caster_adapter.` `Placeholder`

  Bases: `object`

`voca.caster_adapter.` `R`

  alias of `voca.caster_adapter.RegisteredAction`

class `voca.caster_adapter.` `RegisteredAction`(instruction: AsyncActionType, rdescript: Optional[str] = None)

  Bases: `object`

  `execute`(arg=None) → None

class `voca.caster_adapter.` `RepeatedAction`(action: AsyncActionType, extra: str)

  Bases: `object`

  `execute`(arg=None)

class `voca.caster_adapter.` `Settings`

  Bases: `object`

class `voca.caster_adapter.` `SpecTransformer`

  Bases: `lark.visitors.Transformer`

  `angled_name`(args)
  `component`(args)
  `group`(args)
  `literal_name`(args)
  `name`(args)
  `optional_component`(args)
  `phrase_component`(args)
  `spec`(args)

`voca.caster_adapter.` `Text`(name)

class `voca.caster_adapter.` `TextAction`(text: str)

  Bases: `object`

  `execute`(arg=None) → None

class `voca.caster_adapter.` `VirtualModule`(**kwargs)

  Bases: `object`

class `voca.caster_adapter.` `VirtualPackage`(path, contents)

  Bases: `object`

`voca.caster_adapter.` `adapt_AppContext`(title=None, executable=None)

`voca.caster_adapter.` `adapt_Dictation`(text)

`voca.caster_adapter.` `adapt_Key`(text)

`voca.caster_adapter.` `adapt_Text`(name)

`voca.caster_adapter.` `add_to_registry`(mapping, registry)

`voca.caster_adapter.` `add_wrapper`(module)

`voca.caster_adapter.` `convert_key_name`(name)

`voca.caster_adapter.` `convert_spec`(spec)

`voca.caster_adapter.` `find_merge_rule_classes`(module)

`voca.caster_adapter.` `monkeypatch`(module, name, new)

`voca.caster_adapter.` `monkeypatch_each`(patches)

`voca.caster_adapter.` `patch_all`()

`voca.caster_adapter.` `transform_tree`(tree)

## voca.cli module

Module that contains the command line app.

Why does this file exist, and why not put this in __main__?

> You might be tempted to import things from __main__ later, but that will cause problems: the code will get executed twice:

> - When you run python -mvoca python will execute `__main__.py` as a script. That means there won’t be any `voca.__main__` in `sys.modules`.

> - When you import __main__ it will get executed again (as a module) because there’s no `voca.__main__` in `sys.modules`.

> Also see (1) from http://click.pocoo.org/5/setuptools/#setuptools-integration

`voca.cli.` `log_cli_call`(f)

## voca.config module

`voca.config.` `get_config_dir`() → pathlib.Path

  Get the location of voca user config directory.

## voca.context module

class `voca.context.` `AlwaysContext`

  Bases: `object`

  `check`(data=None) → bool

    Always True.

class `voca.context.` `NeverContext`

  Bases: `object`

  `check`(data=None) → bool

    Always False.

class `voca.context.` `WindowContext`(title: str)

  Bases: `object`

  `check`(data=None) → bool

    Check whether the required name occurs within the current window title.

`voca.context.` `filter_wrappers`(wrapper_group: utils.WrapperGroup, data: dict) → utils.WrapperGroup

  Exclude wrappers that fail to match the current context.

`voca.context.` `get_current_window_title`()

  Get the title of the current window.

## voca.listen module

class `voca.listen.` `MyClient`(url, mic=1, protocols=None, extensions=None, heartbeat_freq=None, byterate=16000, show_hypotheses=True, save_adaptation_state_filename=None, send_adaptation_state_filename=None, audio_gate=0)

  Bases: `ws4py.client.threadedclient.WebSocketClient`

  `closed`(code, reason=None)

    Called when the websocket stream and connection are finally closed. The provided `code` is status set by the other point and `reason` is a human readable message.

    See also

    Defined Status Codes http://tools.ietf.org/html/rfc6455#section-7.4.1

  `opened`()

    Called by the server when the upgrade handshake has succeeded.

  `received_message`(m)

    Called whenever a complete `message`, binary or text, is received and ready for application’s processing.

    The passed message is an instance of `messaging.TextMessage` or `messaging.BinaryMessage`.

    Note

    You should override this method in your subclass.

  `send_data`(data)

`voca.listen.` `main`()

`voca.listen.` `run`(args, content_type, path)

`voca.listen.` `setup`()

## voca.log module

`voca.log.` `json_to_file`(file: Optional[_io.TextIOWrapper] = None) → Callable

  Serialize to json and print into a file, defaulting to stdout.

`voca.log.` `log_async_call`(wrapped_function: Optional[Callable] = None, action_type: Optional[str] = None, include_args: Optional[Iterable[str]] = None, include_result: bool = True) → Callable

  Decorator/decorator factory that logs inputs and the return result. If used with inputs (i.e. as a decorator factory), it accepts the following parameters: @param action_type: The action type to use. If not given the function name

  > will be used.

  @param include_args: If given, should be a list of strings, the arguments to log. @param include_result: True by default. If False, the return result isn’t logged.

`voca.log.` `log_call`(wrapped_function: Optional[Callable] = None, action_type: Optional[str] = None, include_args: Optional[Iterable[str]] = None, include_result: bool = True) → Callable

  Decorator/decorator factory that logs inputs and the return result. If used with inputs (i.e. as a decorator factory), it accepts the following parameters: @param action_type: The action type to use. If not given the function name

  > will be used.

  @param include_args: If given, should be a list of strings, the arguments to log. @param include_result: True by default. If False, the return result isn’t logged.

`voca.log.` `summarize_exception`(exc: BaseException) → Dict[str, dict]

  Combine exception data with traceback into a dict for logging.

`voca.log.` `to_serializable`(obj: Any) → Union[str, list, dict, int, float]

## voca.manager module

class `voca.manager.` `Pool`(num_workers: int = 1, should_log: bool = True, module_names: List[str] = NOTHING, processes: Set[trio.Process] = NOTHING)

  Bases: `object`

  `add_new_process`() → None

    Start a new process and add it to the pool.

  `get_process`() → trio.Process

    Pop an process outof the pool and return it.

  `start`() → None

    Start a new process.

`voca.manager.` `async_main`(should_log, module_names: Optional[List[str]], num_workers: int)

  Read newline-separated inputs on stdin, and process them.

`voca.manager.` `delegate_task`(data: Dict, worker: trio.Process, state: dict, action: eliot.Action)

  Send input data to worker process over std streams.

`voca.manager.` `handle_unexpected_worker_bytes`(message: bytes)

`voca.manager.` `main`(should_log: bool, module_names: Optional[List[str]], num_workers: int)

  Start the event loop.

`voca.manager.` `process_stream`(receiver, num_workers: int, should_log: bool, module_names: Optional[List[str]])

  Handle all the commands coming in by delegating them to workers.

`voca.manager.` `replay_child_messages`(child: trio.Process) → None

  Log the child’s messages to the parent’s stdout.

`voca.manager.` `run_worker`(data: dict, state: dict, pool: Pool)

  Get a process from the pool, send a job to it. Replace that worker when it quits.

`voca.manager.` `set_state`(data: Dict[str, dict], state: Dict[str, dict])

  Handle switching between `eager` and `strict` mode.

`voca.manager.` `worker_cli`(should_log, module_names: Optional[List[str]] = None) → List[str]

  Build the list of strings for invoking a worker subprocess.

## voca.mic module

Plot the live microphone signal(s) with matplotlib.

Matplotlib and NumPy have to be installed.

This module is from the sounddevice docs.

`voca.mic.` `audio_callback`(indata, frames, time, status)

  This is called (from a separate thread) for each audio block.

`voca.mic.` `int_or_str`(text)

  Helper function for argument parsing.

`voca.mic.` `update_plot`(frame)

  This is called by matplotlib for each plot update.

  Typically, audio callbacks happen more frequently than plot updates, therefore the queue tends to contain multiple blocks of audio data.

## voca.parsing module

class `voca.parsing.` `Transformer`

  Bases: `lark.visitors.Transformer`

  `chord`(arg)
  `key`(arg)
  `text`

    alias of `builtins.list`

`voca.parsing.` `build_grammar`(registry: utils.Registry, rules: List[utils.Rule]) → str

  Build a lark grammar string by combining rules and definitions in the registry.

`voca.parsing.` `build_rules`(registry: utils.Registry) → List[utils.Rule]

  Build a list of rules and attach human-readable names.

`voca.parsing.` `combine_modules`(modules: Iterable[utils.PluginModule]) → utils.WrapperGroup

  Combine the wrappers of multiple modules into a single WrapperGroup.

`voca.parsing.` `combine_registries`(registries)

  Combine several registries together into a single registry.

`voca.parsing.` `extract`(tree: lark.Tree) → Tuple[str, List]

  Transform the parse tree to extract node type and children.

`voca.parsing.` `extract_commands`(tree: lark.Tree) → Tuple[str, List]

  Transform the parse tree to extract the node’s children.

`voca.parsing.` `normalize_pattern`(text)

  Create a human-readable ascii-lowercase form of the rule.

## voca.patching module

class `voca.patching.` `PathFinder`(modules_to_handle: List[str], fullname_to_vars: Dict[str, Dict[str, Any]])

  Bases: `object`

  `find_spec`(fullname: str, path: Optional[str], target=typing.Union[module, NoneType]) → voca.patching.Spec

    Build a spec for modules in `self.modules_to_handle`, behave normally otherwise.

class `voca.patching.` `PathLoader`(namespace: dict, fullname: str, path: Optional[str], target: types.ModuleType)

  Bases: `object`

  `create_module`(spec: _frozen_importlib.ModuleSpec) → module

    Create a module with the name and namespace.

  `exec_module`(module)

    No-op to match the Loader interface.

class `voca.patching.` `Spec`(name, loader, submodule_search_locations=NOTHING, has_location=True, cached=False, origin=None)

  Bases: `object`

`voca.patching.` `ancestors`(items: List[T]) → Generator[T, List[T], None]

`voca.patching.` `finder_patch`(finder: importlib.abc.MetaPathFinder) → Generator

  Context manager for importing modules with `finder` on `sys.meta_path`.

`voca.patching.` `get_package_map`(strings: List[str]) → Dict[str, List[str]]

  Return a dict mapping packages to the modules they contain.

`voca.patching.` `make_finder`(mapping: Dict[str, Dict[str, Any]]) → voca.patching.PathFinder

  Build a Finder that handles modules in `mapping`.

`voca.patching.` `skipping_finder`(finder: importlib.abc.MetaPathFinder) → Generator

  Context manager for importing modules while excluding the `finder` from `sys.meta_path`.

`voca.patching.` `skipping_module_in_sys_modules`(module_name: star) → Generator

  Context manager for importing modules while skipping any cached entry in `sys.modules`.

## voca.platforms module

class `voca.platforms.` `System`

  Bases: `enum.Enum`

  An enumeration.

  `DARWIN` = 3
  `LINUX` = 1
  `WINDOWS` = 2

`voca.platforms.` `implementation`(*which) → Callable

  Decorator for functions that provide a platform-specific functionality.

## voca.streaming module

class `voca.streaming.` `TerminatedFrameReceiver`(stream: trio.abc.ReceiveStream, terminator: bytes, max_frame_length: int = 1048576)

  Bases: `object`

  Parse frames out of a Trio stream, where each frame is terminated by a

    fixed byte sequence.

    For example, you can parse newline-terminated lines by setting the terminator to b”

  “.

  > This uses some tricks to protect against denial of service attacks:

  > - It puts a limit on the maximum frame size, to avoid memory overflow; you

  > might want to adjust the limit for your situation.

  > - It uses some algorithmic trickiness to avoid “slow loris” attacks. All algorithms are amortized O(n) in the length of the input.

  `receive`() → bytearray

`voca.streaming.` `handle_stream`(handle_message: Callable, stream: trio.abc.ReceiveStream)

  Handle each line as a separate task.

## voca.utils module

class `voca.utils.` `Context`(*args, **kwargs)

  Bases: `typing_extensions.Protocol`

  `check`(data=None) → bool

class `voca.utils.` `Handler`(registry: voca.utils.Registry, parser: lark.lark.Lark, rule_name_to_function: dict)

  Bases: `object`

class `voca.utils.` `HandlerGroup`(handlers: List[voca.utils.Handler])

  Bases: `object`

  `pick_handler`(data: dict) → voca.utils.Handler

    Select the first handler.

class `voca.utils.` `KeyChord`(modifiers: List[voca.utils.KeyModifier], name: str)

  Bases: `object`

class `voca.utils.` `KeyModifier`(name: str)

  Bases: `object`

class `voca.utils.` `ModuleLazyRaise`(owner_name: str, exc: Exception)

  Bases: `object`

class `voca.utils.` `PluginModule`(wrapper: voca.utils.Wrapper)

  Bases: `typing_extensions.Protocol`

class `voca.utils.` `Registry`(pattern_to_function: MutableMapping[str, Callable] = NOTHING, patterns: MutableMapping[KT, VT] = NOTHING)

  Bases: `object`

  `define`(patterns: Optional[Mapping[str, str]] = None, **kwargs)

    Define a rule to map to a combination of other known rules.

  `register`(pattern: str) → Callable

    Decorator registering a pattern to map to a function.

class `voca.utils.` `Rule`(name: str, pattern: str, function: Callable)

  Bases: `object`

class `voca.utils.` `SimpleKey`(name: str)

  Bases: `object`

class `voca.utils.` `Wrapper`(registry: voca.utils.Registry, context: voca.utils.Context = <class 'voca.context.AlwaysContext'>)

  Bases: `object`

class `voca.utils.` `WrapperGroup`(wrappers: List[voca.utils.Wrapper] = NOTHING)

  Bases: `object`

`voca.utils.` `async_runner`(async_function: Callable)

`voca.utils.` `plugin_module_paths`() → List[str]

  Get the import paths of the plugin modules.

`voca.utils.` `pronunciation_to_value`() → MutableMapping[str, Any]

  Return a dict of pronunciation to value.

`voca.utils.` `quote`(word: str) → str

  Format a word in single or double quotation marks for lark.

`voca.utils.` `regex`(word: str) → str

  Format a word in slashes for lark.

`voca.utils.` `replace`(message: str) → str

  Replace pronunciation with its value.

`voca.utils.` `run_subprocess`(command: List[str], *, input=None, capture_output=False, **options)

  Run a subprocess an wait for it to exit.

`voca.utils.` `transform_module`(module: module) → module

  Call each function in MODULE_TRANSFORMERS on the module.

`voca.utils.` `value_to_pronunciation`() → Dict[Any, str]

  Return a dict of value to pronunciation.

## voca.worker module

`voca.worker.` `async_main`(wrapper_group: voca.utils.WrapperGroup)

  Process input commands as newline-separated json on stdin.

`voca.worker.` `collect_modules`(import_paths: Iterable[str], use_backup_modules: bool) → List[module]

  Collect modules from import paths, optionally defaulting to backup modules on failure.

`voca.worker.` `combine_registries`(registries: voca.utils.Registry) → voca.utils.Registry

  Combine multiple registries into a single one.

`voca.worker.` `get_backup_module`(import_path: str, backup_dir: pathlib.Path) → module

  Import a module from the backup directory.

`voca.worker.` `get_module`(import_path: str, backup_dir: pathlib.Path, use_backup_modules: bool) → module

  Import module and cache it in backup_dir, returning backup on failure.

`voca.worker.` `handle_message`(wrapper_group: voca.utils.WrapperGroup, data: dict)

  Execute the command in `data` with the `wrapper_group` containing the grammar.

`voca.worker.` `load_from_path`(import_path: str, filename: str) → module

  Load a module from a filesystem path.

`voca.worker.` `main`(import_paths: Tuple[str], use_backup_modules: bool)

  Get the wrapper group and start the event loop.

`voca.worker.` `make_specific_handler`(wrapper_group: voca.utils.WrapperGroup, data: dict)

  Build the command handler for the specific context.

`voca.worker.` `save_backup_module`(module: module, import_path: str, backup_dir: pathlib.Path) → None

  Save a module in the backup directory.

## Module contents