main¶

argdeco.main – the main function

This module provides Main, which can be used to create main functions.

For ease it provides common arguments like debug, verbosity and quiet which control whether you want to print stacktraces, and how verbose the logging is. These arguments will not be passed to command handlers or main function handler.

Usually you will import the global main instance provided in argdeco:

from argdeco import main

In this case, main.command is also provided as global symbol:

from argdeco import main, command

@main.command(...)
def cmd(...):
    ...

# is equivalent to
@command(...)
def cmd(...):
    ...

Bug you can also create an own instance:

from argdeco.main import Main
main = Main()

@main.command('foo', ...)
def my_cmd(...):
    ...

If you want to make use of the predefined (global) args:

if __name__ == '__main__':
    main(verbosity=True, debug=True, quiet=True)

class argdeco.main.Main(debug=False, verbosity=False, quiet=False, compile=None, compiler_factory=None, command=None, log_format='%(name)-20.20s %(levelname)-10.10s %(message)s', error_handler=<built-in function exit>, error_code=1, catch_exceptions=(<type 'exceptions.SystemError'>, <type 'exceptions.AssertionError'>, <class 'argdeco.main.ArgParseExit'>), **kwargs)[source]¶

Main function provider

An instance of this class can be used as main function for your program. It provides a :py:attribute:

Parameters:

debug –
Set True if you want main to manage the debug arg. (default: False).

Set global logging levels to DEBUG and print out full exception stack traces.
verbosity –
Control global logging log levels (default: False)

If this is turned on, default log level will be set to ERROR and following argument are provided:

-v, --verbose¶

set log level to level WARNING

-vv, -v -v, --verbose --verbose¶

Set log level to level INFO

-vvv, -v -v -v¶

Set log level to level DEBUG
quiet –
If you set this to True, argument --quiet will be added:

--quiet¶

If this option is passed, global log level will be set to CRITICAL.
command – CommandDecorator instance to use. This defaults to None, and for each main instance there will be created a CommandDecorator instance.
compile – This parameter is passed CommandDecorator instance and controls, if arguments passed to handlers are compiled in some way.
compiler_factory –
This parameter is passed CommandDecorator instance and defines a factory function, which returns a compile function.

You may either use compile or compiler_factory.
log_format – This parameter is passed to logging.basicConfig() to define log output. (default: "%(name)s %(levelname)s %(message)s")
error_code – This is the error code to be returned on an exception (default: 1).
error_handler –
Pass a function, which handles errors. This function will get the error code returned from a command (or main) function and do something with it. Default is sys.exit().

If you do not want to exit the program after running the main funtion you have to set error_handler to None.

If you want to access the managed arguments (quiet, verbosity, debug), you can access them as attributes of the main instance:

if not main.quiet:
    print("be loud")

if main.debug:
    print("debug is on")

__call__(*args, **kwargs)[source]¶

You can call Main instance in various ways. As function or as decorator. As long you did not have decorated a function with this Main instance, you can invoke it as function for confiugration.

As soon there is defined some action, invoking the instance, will execute the actions.

Configure some global arguments:

main(
    arg('--global', '-g', help="a global argument"),
)

Decorate a function to be called as main function:

@main
def my_main():
    return 0

if __name__ == "__main__":
    main()

Decorate a function to be main function and define arguments of it:

@main(
    arg('--first', '-f', help="first argument"),
    arg('--second', '-s', help="second argument"),
)
def main(first, second):
    return 0   # successful

if __name__ == "__main__":
    main(debug=True)

Parameters:

*args –
All arguments of type arg are filtered out and added as global argument to underlying CommandDecorator instance.

All other arguments are collected – if any to be argv. If there are any other parameters, this function switches into regular main mode and will execute the main function passing argv. If there are no arguments defined, sys.argv is used as default.

**kwargs –

You can pass various keyword arguments to tweak behaviour of the main function.

compiler_factory:
argv:	You can set explicitly the `argv` vector. This becomes handy, if you want to pass an empty `argv` list and do not want to use the default sys.argv.
debug:	Turn on debug argument, see `Main` for more info.
verbosity:	Turn on verbose argument, see `Main` for more info.
quiet:	Turn on quiet argument, see `Main` for more info.
error_handler:	Tweak the error handler. This will be only local to this call.
compile:	Set compile for this call.
	Set compiler_factory for this call.

Returns:

Decorator mode:	Returns the instance itself, to be invoked as decorator.
Run mode:	Returns whatever error_handler returns, when getting the return value of the invoked action function

add_arguments(*args)[source]¶

Explicitely add arguments:

main.add_arguments( arg('--first'), arg('--second') )

This function wraps argdeco.command_decorator.C()

Parameters:	*args – arguments to be added.

configure(debug=None, quiet=None, verbosity=None, traceback=None, compile=None, compiler_factory=None, catch_exceptions=None, **kwargs)[source]¶: configure behaviour of main, e.g. managed args

install_bash_completion(script_name=None, dest='~/.bashrc')[source]¶

add line to activate bash_completion for given script_name into dest

You can use this for letting the user install bash_completion:

from argdeco import command, main

@command("install-bash-completion",
    arg('--dest', help="destination", default="~/.bashrc")
)
def install_bash_completion(dest):
    main.install_bash_completion(dest=dest)

uninstall_bash_completion(script_name=None, dest='~/.bashrc')[source]¶

remove line to activate bash_completion for given script_name from given dest

You can use this for letting the user uninstall bash_completion:

from argdeco import command, main

@command("uninstall-bash-completion",
    arg('--dest', help="destination", default="~/.bashrc")
)
def uninstall_bash_completion(dest):
    main.uninstall_bash_completion(dest=dest)

main¶

argdeco

Navigation

Related Topics