absl.app module

Generic entry point for Abseil Python applications.

To use this module, define a main function with a single argv argument and call app.run(main). For example:

def main(argv):
  if len(argv) > 1:
    raise app.UsageError('Too many command-line arguments.')

if __name__ == '__main__':
  app.run(main)

exception absl.app.Error

Bases: Exception

class absl.app.ExceptionHandler

Bases: object

Base exception handler from which other may inherit.

handle(exc)

Do something with the current exception.

Parameters:

exc – Exception, the current exception

This method must be overridden.

wants(exc)

Returns whether this handler wants to handle the exception or not.

This base class returns True for all exceptions by default. Override in subclass if it wants to be more selective.

Parameters:

exc – Exception, the current exception.

class absl.app.HelpFlag

Bases: BooleanFlag

Special boolean flag that displays usage and raises SystemExit.

NAME = 'help'

SHORT_NAME = '?'

default: _T | None

default_as_str: str | None

default_unparsed: _T | None | str

parse(arg)

Parses string and sets flag value.

Parameters:

argument – str or the correct flag value type, argument to be parsed.

class absl.app.HelpXMLFlag

Bases: BooleanFlag

Similar to HelpfullFlag, but generates output in XML format.

default: _T | None

default_as_str: str | None

default_unparsed: _T | None | str

parse(arg)

Parses string and sets flag value.

Parameters:

argument – str or the correct flag value type, argument to be parsed.

class absl.app.HelpfullFlag

Bases: BooleanFlag

Display help for flags in the main module and all dependent modules.

default: _T | None

default_as_str: str | None

default_unparsed: _T | None | str

parse(arg)

Parses string and sets flag value.

Parameters:

argument – str or the correct flag value type, argument to be parsed.

class absl.app.HelpshortFlag

Bases: HelpFlag

–helpshort is an alias for –help.

NAME = 'helpshort'

SHORT_NAME = None

default: _T | None

default_as_str: str | None

default_unparsed: _T | None | str

exception absl.app.UsageError(message, exitcode=1)

Bases: Error

Exception raised when the arguments supplied by the user are invalid.

Raise this when the arguments supplied are invalid from the point of view of the application. For example when two mutually exclusive flags have been supplied or when there are not enough non-flag arguments. It is distinct from flags.Error which covers the lower level of parsing and validating individual flags.

absl.app.call_after_init(callback)

Calls the given callback only once ABSL has finished initialization.

If ABSL has already finished initialization when call_after_init is called then the callback is executed immediately, otherwise callback is stored to be executed after app.run has finished initializing (aka. just before the main function is called).

If called after app.run, this is equivalent to calling callback() in the caller thread. If called before app.run, callbacks are run sequentially (in an undefined order) in the same thread as app.run.

Parameters:

callback – a callable to be called once ABSL has finished initialization. This may be immediate if initialization has already finished. It takes no arguments and returns nothing.

absl.app.define_help_flags()

Registers help flags. Idempotent.

absl.app.install_exception_handler(handler)

Installs an exception handler.

Parameters:

handler – ExceptionHandler, the exception handler to install.

Raises:

TypeError – Raised when the handler was not of the correct type.

All installed exception handlers will be called if main() exits via an abnormal exception, i.e. not one of SystemExit, KeyboardInterrupt, FlagsError or UsageError.

absl.app.parse_flags_with_usage(args)

Tries to parse the flags, print usage, and exit if unparsable.

Parameters:

args – [str], a non-empty list of the command line arguments including program name.

Returns:

[str], a non-empty list of remaining command line arguments after parsing flags, including program name.

absl.app.run(main, argv=None, flags_parser=<function parse_flags_with_usage>)

Begins executing the program.

Parameters:

• main – The main function to execute. It takes an single argument “argv”, which is a list of command line arguments with parsed flags removed. The return value is passed to sys.exit, and so for example a return value of 0 or None results in a successful termination, whereas a return value of 1 results in abnormal termination. For more details, see https://docs.python.org/3/library/sys#sys.exit

• argv – A non-empty list of the command line arguments including program name, sys.argv is used if None.

• flags_parser – Callable[[List[Text]], Any], the function used to parse flags. The return value of this function is passed to main untouched. It must guarantee FLAGS is parsed after this function is called. Should be passed as a keyword-only arg which will become mandatory in a future release.

• Parses command line flags with the flag module.

• If there are any errors, prints usage().

• Calls main() with the remaining arguments.

• If main() raises a UsageError, prints usage and the error message.

absl.app.usage(shorthelp=False, writeto_stdout=False, detailed_error=None, exitcode=None)

Writes __main__’s docstring to stderr with some help text.

Parameters:

• shorthelp – bool, if True, prints only flags from the main module, rather than all flags.

• writeto_stdout – bool, if True, writes help message to stdout, rather than to stderr.

• detailed_error – str, additional detail about why usage info was presented.

• exitcode – optional integer, if set, exits with this status code after writing help.