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)

Bases: object

The core class of almanac, wrapping everything together.

This class should be your main entrypoint into all of the functionality provided by this framework. The main method of customizing the state of an application is via different decorators.

add_completers_for_type(_type: Type, *completers: prompt_toolkit.completion.base.Completer) → None

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

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

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

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

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

Context manager to dispatch hooks for exceptions in wrapped code.

async eval_line(line: str) → int

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]

Change the app’s current input/output context.

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

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]]

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

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

promoter_for(*types: Type[_T]) → Callable[[almanac.hooks.types.PromoterFunction[_T]], almanac.hooks.types.PromoterFunction[_T]]

A decorator for specifying inline promotion callbacks.

async prompt() → int

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]]]

A decorator for specifying an application’s prompt.

quit() → None

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]

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]

Run all of the registered on-exit callbacks.

async run_on_init_callbacks() → List[Any]

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)

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]

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

• document – Document instance.

• complete_event – CompleteEvent instance.

class CommandEngine(app: Application, *commands_to_register: FrozenCommand)

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

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

Register a callback for execution before a command.

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

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

Get a FrozenCommand by its name or alias.

Returns

The mapped FrozenCommand 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, …]

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, …]

Get a tuple of all registered command names and aliases.

register(command: almanac.commands.frozen_command.FrozenCommand) → None

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

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

Bases: object

A simple proxy for providing argument-mutating decorators.

class CommandDecoratorProxy(app: Application)

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]

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]

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.