Application reference¶

Application ¶

This class is never imported directly. Instead, use the dda.cli.base.pass_app decorator to pass an instance of this class to your command.

from __future__ import annotations

from typing import TYPE_CHECKING

from dda.cli.base import dynamic_command, pass_app

if TYPE_CHECKING:
    from dda.cli.application import Application


@dynamic_command(short_help="Some command")
@pass_app
def cmd(app: Application) -> None:
    """
    Long description of the command.
    """
    app.display_waiting("Running some command")

config ¶

config: RootConfig

subprocess ¶

subprocess: SubprocessRunner

http ¶

http: HTTPClientManager

tools ¶

tools: Tools

telemetry ¶

telemetry: TelemetryManager

last_error ¶

last_error: str

The last recorded error message which will be collected as telemetry. This can be overwritten like so:

app.last_error = "An error occurred"

Alternatively, you can append to it:

app.last_error += "\nExtra information or context"

abort ¶

abort(text: str = '', code: int = 1) -> NoReturn

Gracefully terminate the application with an optional error message. The message is appended to the last error message.

Parameters:

Name	Type	Description	Default
`text`	`str`	The error message to display.	`''`
`code`	`int`	The exit code to use.	`1`

display ¶

display(text: str = '', **kwargs: Any) -> None

Output text to stdout using the info style regardless of the configured verbosity level.

Parameters:

Name	Type	Description	Default
`text`	`str`	The text to output.	`''`

Other Parameters:

Name	Type	Description
`**kwargs`	`Any`	Additional keyword arguments to pass to the `Console.print` method.

display_critical ¶

display_critical(text: str = '', **kwargs: Any) -> None

Output text to stderr using the error style regardless of the configured verbosity level.

Parameters:

Name	Type	Description	Default
`text`	`str`	The text to output.	`''`

Other Parameters:

Name	Type	Description
`**kwargs`	`Any`	Additional keyword arguments to pass to the `Console.print` method.

display_error ¶

display_error(
    text: str = "", *, stderr: bool = True, **kwargs: Any
) -> None

Output text using the error style if the configured verbosity level is at least Verbosity.ERROR.

Parameters:

Name	Type	Description	Default
`text`	`str`	The text to output.	`''`
`stderr`	`bool`	Whether to output to stderr.	`True`

Other Parameters:

Name	Type	Description
`**kwargs`	`Any`	Additional keyword arguments to pass to the `Console.print` method.

display_warning ¶

display_warning(
    text: str = "", *, stderr: bool = True, **kwargs: Any
) -> None

Output text using the warning style if the configured verbosity level is at least Verbosity.WARNING.

Parameters:

Name	Type	Description	Default
`text`	`str`	The text to output.	`''`
`stderr`	`bool`	Whether to output to stderr.	`True`

Other Parameters:

Name	Type	Description
`**kwargs`	`Any`	Additional keyword arguments to pass to the `Console.print` method.

display_info ¶

display_info(
    text: str = "", *, stderr: bool = True, **kwargs: Any
) -> None

Output text using the info style if the configured verbosity level is at least Verbosity.INFO.

Parameters:

Name	Type	Description	Default
`text`	`str`	The text to output.	`''`
`stderr`	`bool`	Whether to output to stderr.	`True`

Other Parameters:

Name	Type	Description
`**kwargs`	`Any`	Additional keyword arguments to pass to the `Console.print` method.

display_success ¶

display_success(
    text: str = "", *, stderr: bool = True, **kwargs: Any
) -> None

Output text using the success style if the configured verbosity level is at least Verbosity.INFO.

Parameters:

Name	Type	Description	Default
`text`	`str`	The text to output.	`''`
`stderr`	`bool`	Whether to output to stderr.	`True`

Other Parameters:

Name	Type	Description
`**kwargs`	`Any`	Additional keyword arguments to pass to the `Console.print` method.

display_waiting ¶

display_waiting(
    text: str = "", *, stderr: bool = True, **kwargs: Any
) -> None

Output text using the waiting style if the configured verbosity level is at least Verbosity.INFO.

Parameters:

Name	Type	Description	Default
`text`	`str`	The text to output.	`''`
`stderr`	`bool`	Whether to output to stderr.	`True`

Other Parameters:

Name	Type	Description
`**kwargs`	`Any`	Additional keyword arguments to pass to the `Console.print` method.

display_debug ¶

display_debug(
    text: str = "",
    level: int = VERBOSE,
    *,
    stderr: bool = True,
    **kwargs: Any,
) -> None

Output text using the debug style if the configured verbosity level is between Verbosity.VERBOSE and Verbosity.TRACE (inclusive).

Parameters:

Name	Type	Description	Default
`text`	`str`	The text to output.	`''`
`level`	`int`	The verbosity level.	`VERBOSE`
`stderr`	`bool`	Whether to output to stderr.	`True`

Other Parameters:

Name	Type	Description
`**kwargs`	`Any`	Additional keyword arguments to pass to the `Console.print` method.

display_header ¶

display_header(title: str) -> None

Display a horizontal rule with an embedded title using the success style.

Parameters:

Name	Type	Description	Default
`title`	`str`	The title to display.	required

display_table ¶

display_table(data: dict[str, Any]) -> None

Display a table with the given data using the success style for the keys.

The following data:

{
    "key1": {
        "nested1": {
            "str": "text",
            "int": 1,
            "float": 1.0,
            "bool": True,
            "list": ["foo", 2, "bar"],
        },
    },
}

would be displayed as:

┌──────┬─────────────────────────────────────────────┐
│ key1 │ ┌─────────┬───────────────────────────────┐ │
│      │ │ nested1 │ ┌───────┬───────────────────┐ │ │
│      │ │         │ │ str   │ text              │ │ │
│      │ │         │ │ int   │ 1                 │ │ │
│      │ │         │ │ float │ 1.0               │ │ │
│      │ │         │ │ bool  │ True              │ │ │
│      │ │         │ │ list  │ ['foo', 2, 'bar'] │ │ │
│      │ │         │ └───────┴───────────────────┘ │ │
│      │ └─────────┴───────────────────────────────┘ │
└──────┴─────────────────────────────────────────────┘

Parameters:

Name	Type	Description	Default
`data`	`dict[str, Any]`	The data to display.	required

display_syntax ¶

display_syntax(*args: Any, **kwargs: Any) -> None

Display a syntax-highlighted block of text.

Parameters:

Name	Type	Description	Default
`*args`	`Any`	Additional arguments to pass to the `Syntax` constructor.	`()`
`**kwargs`	`Any`	Additional keyword arguments to pass to the `Syntax` constructor.	`{}`

status ¶

status(*args: Any, **kwargs: Any) -> Status

Display a status indicator with the configured spinner. If the session is not interactive, the status indicator will be displayed as a waiting message.

The returned object must be used as a context manager.

Parameters:

Name	Type	Description	Default
`*args`	`Any`	Additional arguments to pass to the `Console.status` method.	`()`
`**kwargs`	`Any`	Additional keyword arguments to pass to the `Console.status` method.	`{}`

prompt ¶

prompt(*args: Any, **kwargs: Any) -> str

Prompt the user for input.

Parameters:

Name	Type	Description	Default
`*args`	`Any`	Additional arguments to pass to the `click.prompt` function.	`()`
`**kwargs`	`Any`	Additional keyword arguments to pass to the `click.prompt` function.	`{}`

Returns:

Type	Description
`str`	The user's input.

confirm ¶

confirm(*args: Any, **kwargs: Any) -> bool

Prompt the user for confirmation.

Parameters:

Name	Type	Description	Default
`*args`	`Any`	Additional arguments to pass to the `click.confirm` function.	`()`
`**kwargs`	`Any`	Additional keyword arguments to pass to the `click.confirm` function.	`{}`

Returns:

Type	Description
`bool`	Whether the user confirmed the action.