# `utopya_runscript` module

The `utopya_runscript` module provides access to UTOPyA’s run script classes. Note that all entities could be imported directly from the main `utopya` module too.

Two classes are provided:

- The `UtopyaRunScript` class could be used for a standard script without specific arguments.

- The `UtopyaRunScriptRc` class requires the name of an rcfile with settings as command line argument, and settings could be read directly from this class.

## Class hierarchy

The classes are defined according to following hierarchy:

- `UtopyaBase`

  - `UtopyaRunScript`

- `UtopyaRc`

  - `UtopyaRunScriptRc`

## Classes

class utopya_runscript.UtopyaRunScript

  Bases: `UtopyaBase`

  Base class for script object, to be used in user defined scripts to quickly perform some common tasks:

  - setup logging to put out informative messages;

  - define some default arguments;

  - parse the arguments.

  Example script:

      #! /usr/bin/env python

      # modules:
      import logging

      # tools:
      import utopya

      # setup logging:
      logging.basicConfig( stream=sys.stdout, level=logging.INFO,
                             format='[%(levelname)-8s] %(message)s' )

      # init script:
      utos = utopya.UtopyaRunScript()

      # setup default command line arguments:
      utos.ArgumentsSetup( description='UTOPyA test script' )

      # evaluate known arguments, store the other ;
      # might show help text and exit:
      args,xargs = utos.ArgumentsParse()

      # do something:
      logging.info( 'boe!')

  ArgumentsSetup(description=None)

    Defines data object ‘parser’ of class `argparse.ArgumentParser` . The parser is populated with default arguments for:

    - verbose option to shout not only info but also debug messages.

  ArgumentsAdd(*args, **kwargs)

    Add a new command line argument.

    The arguments provided to this routine are passed directly to the `argparse.ArgumentParser.add_argument()` routine of the ‘parser’ object that was defined by the ‘SetupArguments’ routine. See the documentation of this underlying method for useful arguments.

    Examples:

        # argument with value:
        ArgumentsAdd( '-n', '--name', help='name used for something',
                               action='store', dest='name' )
        # flag:
        ArgumentsAdd( '-f', '--flag', help='enable something',
                               action='store_true', dest='flag' )

    After the call to `ArgumentsParse()`, the arguments are available through:

        # parse arguments, return known and extra:
        args,xargs = ArgumentsParse()
        # show:
        print( 'name = ', args.name )
        print( 'flag = ', args.flag )

  ArgumentsParse()

    Parse known arguments.

    The optional verbose setting is evaluated, and if necessary, the logging level is changed.

    In case the arguments included the ‘-h’ or ‘–help’ flag, an automatically created help tekst is displayed and the program is terminated. Otherwise, the method returns with the following arguments:

    - args : namespace with defined arguments and values

    - xargs : extra arguments

class utopya_runscript.UtopyaRunScriptRc

  Bases: `UtopyaRc`

  Base class for script object, to be used in user defined scripts that need a rcfile argument. The following tasks are performed by the class:

  - setup logging to put out informative messages;

  - define default arguments including rcfile name;

  - parse the arguments, and read the settings from the rcfile.

  Example script:

      #! /usr/bin/env python

      # modules:
      import logging

      # tools:
      import utopya

      # init script, pass default rcfile settings:
      utos = utopya.UtopyaRunScriptRc()

      # setup default command line arguments:
      utos.ArgumentsSetup( description='UTOPyA test script',
                            rcfile='test.rc', rcbase='appl' )

      # evaluate known arguments, store the other ;
      # might show help text and exit:
      args,xargs = utos.ArgumentsParse()

      # do something:
      logging.info( 'boe!')

  ArgumentsSetup(description=None, rcfile=None, rcbase='')

    Defines data object ‘parser’ of class `argparse.ArgumentParser` . The parser is populated with default arguments for:

    - verbose option to shout not only info but also debug messages;

    - name of the rcfile with settings (default to optional argument ‘rcfile’);

    - base key for relevant rcfile settings (default to optional argument ‘rcbase’).

  ArgumentsAdd(*args, **kwargs)

    Add a new command line argument.

    The arguments provided to this routine are passed directly to the `argparse.ArgumentParser.add_argument()` routine of the ‘parser’ object that was defined by the ‘SetupArguments’ routine. See the documentation of this underlying method for useful arguments.

    Examples:

        # argument with value:
        ArgumentsAdd( '-n', '--name', help='name used for something',
                               action='store', dest='name' )
        # flag:
        ArgumentsAdd( '-f', '--flag', help='enable something',
                               action='store_true', dest='flag' )

    After the call to `ArgumentsParse()`, the arguments are available through:

        # parse arguments, return known and extra:
        args,xargs = ArgumentsParse()
        # show:
        print( 'name = ', args.name )
        print( 'flag = ', args.flag )

  ArgumentsParse(env={})

    Parse known command line arguments.

    In case the arguments included the ‘-h’ or ‘–help’ flag, an automatically created help tekst is displayed and the program is terminated. Otherwise, the method returns with the following arguments:

    - args : namespace with defined arguments and values

    - xargs : extra arguments

    The ‘rcfile’ and ‘rcbase’ passed as command line arguments, and eventually the optional ‘env’ dictionairy passed to this method, are used to initalize the `RcFile` base class. The following optional settings are read from the ‘rcfile’ immediately to setup the logging:

    > <rcbase>.logging.format : [%(levelname)-8s] %(message)s <rcbase>.logging.level : info

    Note that instead of an ‘rcbase’ the settings could also start with an asterix ‘*’. The logging level is changed to ‘debug’ if case the ‘verbose’ flag is enabled in the arguments passed to the script.