milc¶
MILC Objects¶
class MILC(object)
MILC - An Opinionated Batteries Included Framework
__init__¶
def __init__(name, version, author, logger=None)
Initialize the MILC object.
echo¶
def echo(text, *args, **kwargs)
Print colorized text to stdout.
ANSI color strings (such as {fg_blue}) will be converted into ANSI escape sequences, and the ANSI reset sequence will be added to all strings.
If args or *kwargs are passed they will be used to %-format the strings.
run¶
def run(command,
capture_output=True,
combined_output=False,
text=True,
**kwargs)
Run a command using subprocess.run, but using some different defaults.
Unlike subprocess.run you must supply a sequence of arguments. You can use shlex.split() to build this from a string.
The **kwargs arguments get passed directly to subprocess.run.
Arguments:
command A sequence where the first item is the command to run, and any remaining items are arguments to pass.
capture_output
Set to False to have output written to the terminal instead of being available in the returned subprocess.CompletedProcess instance.
combined_output
When true STDERR will be written to STDOUT. Equivalent to the shell construct 2>&1.
text
Set to False to disable encoding and get bytes() from .stdout and .stderr.
initialize_argparse¶
def initialize_argparse()
Prepare to process arguments from sys.argv.
print_help¶
def print_help(*args, **kwargs)
Print a help message for the main program or subcommand, depending on context.
print_usage¶
def print_usage(*args, **kwargs)
Print brief description of how the main program or subcommand is invoked, depending on context.
log_deprecated_warning¶
def log_deprecated_warning(item_type, name, reason)
Logs a warning with a custom message if a argument or command is deprecated.
add_argument¶
def add_argument(*args, **kwargs)
Wrapper to add arguments and track whether they were passed on the command line.
initialize_logging¶
def initialize_logging(logger)
Prepare the defaults for the logging infrastructure.
acquire_lock¶
def acquire_lock(blocking=True)
Acquire the MILC lock for exclusive access to properties.
release_lock¶
def release_lock()
Release the MILC lock.
find_config_file¶
@lru_cache(maxsize=None)
def find_config_file()
Locate the config file.
argument¶
def argument(*args, **kwargs)
Decorator to call self.add_argument or self.
parse_args¶
def parse_args()
Parse the CLI args.
read_config_file¶
def read_config_file()
Read in the configuration file and return Configuration objects for it and the config_source.
initialize_config¶
def initialize_config()
Read in the configuration file and store it in self.config.
merge_args_into_config¶
def merge_args_into_config()
Merge CLI arguments into self.config to create the runtime configuration.
write_config_option¶
def write_config_option(section, option)
Save a single config option to the config file.
save_config¶
def save_config()
Save the current configuration to the config file.
__call__¶
def __call__()
Execute the entrypoint function.
entrypoint¶
def entrypoint(description, deprecated=None)
Decorator that marks the entrypoint used when a subcommand is not supplied.
Arguments:
description A one-line description to display in --help
deprecated Deprecation message. When set the subcommand will marked as deprecated and this message will be displayed in the help output.
add_subcommand¶
def add_subcommand(handler,
description,
hidden=False,
deprecated=None,
**kwargs)
Register a subcommand.
Arguments:
handler The function to exececute for this subcommand.
description A one-line description to display in --help
hidden When True don't display this command in --help
deprecated Deprecation message. When set the subcommand will be marked as deprecated and this message will be displayed in help output.
subcommand¶
def subcommand(description, hidden=False, **kwargs)
Decorator to register a subcommand.
Arguments:
description A one-line description to display in --help
hidden When True don't display this command in --help
setup_logging¶
def setup_logging()
Called by enter() to setup the logging configuration.
is_spinner¶
def is_spinner(name)
Returns true if name is a valid spinner.
add_spinner¶
def add_spinner(name, spinner)
Adds a new spinner to the list of spinners.
A spinner is a dictionary with two keys:
interval
An integer that sets how long (in ms) to wait between frames.
frames
A list of frames for this spinner
spinner¶
def spinner(text,
*args,
spinner=None,
animation='ellipsed',
placement='left',
color='blue',
interval=-1,
stream=sys.stdout,
enabled=True,
**kwargs)
Create a spinner object for showing activity to the user.
This uses halo https://github.com/ManrajGrover/halo behind the scenes, most of the arguments map to Halo objects 1:1.
There are 3 basic ways to use this:
- Instantiating a spinner and then using
.start()and.stop()on your object. - Using a context manager (
with cli.spinner(...):) - Decorate a function (
@cli.spinner(...))
Instantiating a spinner¶
spinner = cli.spinner(text='Loading', spinner='dots')
spinner.start()
# Do something here
spinner.stop()
Using a context manager¶
with cli.spinner(text='Loading', spinner='dots'):
# Do something here
Decorate a function¶
@cli.spinner(text='Loading', spinner='dots')
def long_running_function():
# Do something here
Arguments¶
text
The text to display next to the spinner. ANSI color strings
(such as {fg_blue}) will be converted into ANSI escape
sequences, and the ANSI reset sequence will be added to the
end of the string.
If *args or **kwargs are passed they will be used to
%-format the text.
spinner
The name of the spinner to use. Available names are here:
<https://raw.githubusercontent.com/sindresorhus/cli-spinners/dac4fc6571059bb9e9bc204711e9dfe8f72e5c6f/spinners.json>
animation
The animation to apply to the text if it doesn't fit the
terminal. One of `ellipsed`, `bounce`, `marquee`.
placement
Which side of the text to display the spinner on. One of
`left`, `right`.
color
Color of the spinner. One of `blue`, `grey`, `red`, `green`,
`yellow`, `magenta`, `cyan`, `white`
interval
How long in ms to wait between frames. Defaults to the spinner interval (recommended.)
stream
Stream to write the output. Defaults to sys.stdout.
enabled
Enable or disable the spinner. Defaults to `True`.