almanac.core

class Application(*, with_completion: bool = True, with_style: bool = True, style: prompt_toolkit.styles.style.Style = <prompt_toolkit.styles.style.Style object>, io_context_cls: Type[almanac.io.abstract_io_context.AbstractIoContext] = <class 'almanac.io.standard_console_io_context.StandardConsoleIoContext'>, propagate_runtime_exceptions: bool = False, print_all_exception_tracebacks: bool = False, print_unknown_exception_tracebacks: bool = True)[source]

Bases: object

The core class of almanac, wrapping everything together.

add_completers_for_type(_type: Type, *completers: prompt_toolkit.completion.base.Completer)None[source]

Register a completer for all arguments of a specified type (globally).

add_promoter_for_type(_type: Type[_T], promoter_callable: almanac.hooks.types.PromoterFunction[_T])None[source]

Register a promotion callable for a specific argument type.

property arg

The interface for argument-mutating decorators.

property bag

A mutable container for storing data for global access.

async call_as_current_app_async(coro: Callable[[…], Awaitable[_T]], *args: Any, **kwargs: Any) → _T[source]

Call a coroutine with the current app set to this instance.

call_as_current_app_sync(func: Callable[[…], _T], *args: Any, **kwargs: Any) → _T[source]

Call a synchronous function with the current app set to this instance.

property cmd

The interface for command-mutating decorators.

property command_engine

The CommandEngine powering this app’s command lookup.

property current_path

Shorthand for a getting the application’s current path.

property current_prompt_str

The current prompt string.

dispatch_exception_hooks() → AsyncIterator[source]

Context manager to dispatch hooks for exceptions in wrapped code.

async eval_line(line: str)int[source]

Evaluate a line passed to the application by the user.

property hook

The top-level interface for registering hooks on different events.

property io

The application’s top-level input/output context.

io_context(new_io_context: almanac.io.abstract_io_context.AbstractIoContext) → Iterator[almanac.io.abstract_io_context.AbstractIoContext][source]

Change the app’s current input/output context.

on_exit() → Callable[[almanac.hooks.types.AsyncNoArgsCallback[Any]], almanac.hooks.types.AsyncNoArgsCallback[Any]][source]

A decorator for specifying a callback to be executed when the app exits.

These callbacks will only be implicitly executed at the end of prompt() execution. Otherwise, the programmer must manually call run_on_init_callbacks().

property on_exit_callbacks

Registered coroutines to be executed on application exit.

on_init() → Callable[[almanac.hooks.types.AsyncNoArgsCallback[Any]], almanac.hooks.types.AsyncNoArgsCallback[Any]][source]

A decorator for specifying a callback to be executed when the prompt begins.

These callbacks will only be implicitly executed at the beginning of prompt() execution. Otherwise, the programmer must manually call run_on_init_callbacks().

property on_init_callbacks

Registered coroutines to be executed on application prompt initialization.

property page_navigator

The PageNavigator powering this app’s navigation.

print_command_suggestions(name_or_alias: str)None[source]

Print command recommendations for a misspelled attempt.

It is assumed that lookup has already been attempted and that no matching command exists.

print_exception_info(exc: Exception, unknown=False)None[source]
promoter_for(*types: Type[_T]) → Callable[[almanac.hooks.types.PromoterFunction[_T]], almanac.hooks.types.PromoterFunction[_T]][source]

A decorator for specifying inline promotion callbacks.

async prompt()int[source]

Run the application’s interactive prompt.

This method will fire all registered on-init callbacks when it first begins, and fire all registered on-exit callbacks when it completes execution.

Returns

The exit code of the application’s execution.

prompt_text() → Callable[[almanac.hooks.types.SyncNoArgsCallback[Union[str, prompt_toolkit.formatted_text.base.FormattedText]]], almanac.hooks.types.SyncNoArgsCallback[Union[str, prompt_toolkit.formatted_text.base.FormattedText]]][source]

A decorator for specifying an application’s prompt.

quit()None[source]

Cause this application to cleanly stop running.

async run_async_callbacks(async_callbacks: Iterable[almanac.hooks.types.AsyncNoArgsCallback[_T]], *args: Any, **kwargs: Any) → List[_T][source]

Run a collection of asynchronous callbacks with the specified arguments.

Returns

The return value of each of the registered callbacks, in the order that they were registed.

async run_on_exit_callbacks() → List[Any][source]

Run all of the registered on-exit callbacks.

async run_on_init_callbacks() → List[Any][source]

Run all of the registered on-init callbacks.

property type_completer_mapping

A mapping of types to registered global completers.

property type_promoter_mapping

A mapping of types to callables that convert raw arguments to those types.

class CommandCompleter(app: Application)[source]

Bases: prompt_toolkit.completion.base.Completer

A completer that provides command argument completion for an application.

get_completions(document: prompt_toolkit.document.Document, complete_event: prompt_toolkit.completion.base.CompleteEvent) → Iterable[prompt_toolkit.completion.base.Completion][source]

This should be a generator that yields Completion instances.

If the generation of completions is something expensive (that takes a lot of time), consider wrapping this Completer class in a ThreadedCompleter. In that case, the completer algorithm runs in a background thread and completions will be displayed as soon as they arrive.

Parameters
  • documentDocument instance.

  • complete_eventCompleteEvent instance.

class CommandEngine(app: Application, *commands_to_register: FrozenCommand)[source]

Bases: object

A command lookup and management engine.

add_after_command_callback(name_or_command: Union[str, almanac.commands.frozen_command.FrozenCommand], callback: Callable[[…], Coroutine[Any, Any, Any]])None[source]

Register a callback for execution after a command.

add_before_command_callback(name_or_command: Union[str, almanac.commands.frozen_command.FrozenCommand], callback: Callable[[…], Coroutine[Any, Any, Any]])None[source]

Register a callback for execution before a command.

add_promoter_for_type(_type: Type[_T], promoter_callable: almanac.hooks.types.PromoterFunction[_T])None[source]

Register a promotion callable for a specific argument type.

property app

The application that this engine manages.

get(name_or_alias: str)almanac.commands.frozen_command.FrozenCommand[source]

Get a Command by its name or alias.

Returns

The mapped Command instance.

Raises

NoSuchCommandError – If the specified name_or_alias is not contained within this instance.

get_suggestions(name_or_alias: str, max_suggestions: int = 3) → Tuple[str, …][source]

Find the closest matching names/aliases to the specified string.

Returns

A possibly-empty tuple of Command`s that most closely match the specified `name_or_alias field.

keys() → Tuple[str, …][source]

Get a tuple of all registered command names and aliases.

register(command: almanac.commands.frozen_command.FrozenCommand)None[source]

Register a command on this class.

Raises

CommandNameCollisionError – If the name or one of the aliases on the specified FrozenCommand conflicts with an entry already stored in this CommandEngine.

property registered_commands

The FrozenCommand instances registered on this engine.

async run(name_or_alias: str, parsed_args: pyparsing.ParseResults)int[source]

Run a command, validating the specified arguments.

In the event of coroutine-binding failure, this method will do quite a bit of signature introspection to determine why a binding of user-specified arguments to the coroutine signature might fail.

property type_promoter_mapping

A mapping of types to callables that convert raw arguments to those types.

class ArgumentDecoratorProxy[source]

Bases: object

A simple proxy for providing argument-mutating decorators.

class CommandDecoratorProxy(app: Application)[source]

Bases: object

A simple proxy for providing command-mutating decorators.

compose(*decorators: Callable[[Union[almanac.commands.mutable_command.MutableCommand, Callable[[…], Coroutine[Any, Any, int]]]], almanac.commands.mutable_command.MutableCommand]) → Callable[[Union[almanac.commands.mutable_command.MutableCommand, Callable[[…], Coroutine[Any, Any, int]]]], almanac.commands.mutable_command.MutableCommand][source]

Compose several command decorators into one.

register(*decorators: Callable[[Union[almanac.commands.mutable_command.MutableCommand, Callable[[…], Coroutine[Any, Any, int]]]], almanac.commands.mutable_command.MutableCommand]) → Callable[[Union[almanac.commands.mutable_command.MutableCommand, Callable[[…], Coroutine[Any, Any, int]]]], almanac.commands.frozen_command.FrozenCommand][source]

A decorator for registering a command on an application.

This should always be the top-most (i.e., lowest line number) decorator in a stack on top of the coroutine you want to register as a command.

Optionally, a series of other command- or argument-mutating decorators may be provided. This will result in a function being returned from this method that both applies any of these mutations and registers the command.