determine_configuration_directory(mainname='DOPAL Scripts', subname=None, create_dir=True, preserve_case=False)

Determines an appropriate directory to store application data into.

This function will look at environmental settings and registry settings to determine an appropriate directory.

• The user's home, as defined by the home environment setting.
• The user's application directory, as determined by the win32com library.
• The user's application directory, as determine by the _winreg library.
• The user's application directory, as defined by the appdata environment setting.
• The user's home, as defined by the homepath environment setting (and if it exists, the homedrive environment setting.
• The user's home, as defined by the os.path.expanduser function.
• The current working directory.

(Note: this order may change between releases.)

If an existing directory can be found, that will be returned. If no existing directory is found, then this function will try to create the directory in the most preferred location (based on the order of preference). If that fails - no existing directory was found and no directory could be created, then an OSError will be raised. If create_dir is False and no existing directory can be found, then the most preferred candidate directory will be returned.

The main argument taken by this function is mainname. This should be a directory name which is suitable for a Windows application directory (e.g. "DOPAL Scripts"), as opposed to something which resembles more Unix-based conventions (e.g. ".dopal_scripts"). This function will convert the mainname argument into a Unix-style filename automatically in some cases (read below). You can set the preserve_case argument to True if you want to prevent automatic name conversation of this argument to take place.

The subname argument is the subdirectory which gets created in the main directory. This name will be used literally - no translation of the directory name will occur.

Parameters:

mainname - The main directory name to store data in - the default is "DOPAL Scripts". This value cannot be None.

subname - The subdirectory to create in the main directory - this may be None.

create_dir - Boolean value indicating whether we should create the directory if it doesn't already exist (default is True).

preserve_case - Indicates whether the value given in mainname should be taken literally, or whether name translation can be performed. Default is False.

Returns:

A directory which matches the specification given. This directory is guaranteed to exist, unless this function was called with create_dir being False.

Raises:

OSError - If create_dir is True, and no appropriate directory could be created.

ext_run(name, function, connection=None, make_connection=True, timeout=15, use_repeatable_remote_notification=None, use_own_log_channel=False, remote_notify_on_run=False, remote_notify_on_error=True, logger=None, setup_logging=None, log_to_file=False, log_level=None, log_file=None, silent_on_connection_error=False, pause_on_exit=0, print_error_on_pause=1)

Prepares a ScriptEnvironment object based on the settings here, and executes the passed function.

Parameters:

name - The name of the script - used for storing data, log files and so on.

function - The callable object to invoke. Must take one argument, which will be the ScriptEnvironment instance.

connection - The AzureusObjectConnection object to use - if None is provided, one will be automatically determined for you.

make_connection - Determines whether the scripting module should attempt to create a connection based on the default connection details or not. Only has an effect if the connection parameter is None.

timeout - Defines how long socket operations should wait before timing out for (in seconds). Specify 0 to disable timeouts, the default is 15. Specifying None will resort to using the default timeout value specified in the connection details.

use_repeatable_remote_notification - Determines whether the alert method should use repeatable notification by default or not (see ScriptEnvironment.alert).

use_own_log_channel - Determines what log channel to use. The default behaviour is to use a log channel called "DOPAL Scripts". Passing a string value will result in logging output being sent to a channel with the given name. Passing True will result in a channel being used which has the same name as the script.

remote_notify_on_run - Determines whether to send alert calls when the script starts and ends. Normally, this is only desired when testing that the script is working.

remote_notify_on_error - Determines whether to send an alert to the Azureus connection if an error has occurred during the script's execution.

logger - The logging.Logger instance to log to - the root logger will be used by default. Will be None if the logging module is not available on the system.

setup_logging - Determines whether automatically set up logging with the logging.Logger module. If True, logging.basicConfig will be called. If False, dopal.logutils.noConfig will be called. If None (default), then this module will look for file named log.ini, firstly in the script's data directory and then in the global DOPAL scripts directory. If such a file can be found, then logging.fileConfig will be invoked, otherwise dopal.logutils.noConfig will be called instead.

log_to_file - If True, then a RotatingFileHandler will log to a file in the script's data directory.

log_level - The logging level assigned to any logger or handlers created by this function.

log_file - If log_to_file is True, this parameter specifies determines which file to log to (default is that the script will determine a path automatically).

silent_on_connection_error - If True, this function will silently exit if a connection cannot be established with the stored connection object. Otherwise, the original error will be raised.

pause_on_exit - If set to 0 (default), then after execution of the script has occurred, the function will immediately return. If 1, the script will wait for keyboard input before terminating. If 2, the script will wait for keyboard input only if an error has occurred.

print_error_on_pause - If pause_on_exit is enabled, this flag determines whether any traceback should be printed. If 0, no traceback will be printed. If 1 (default), any error which occurs inside this function will be printed. If 2, only tracebacks which have occurred in the script will be printed. If 3, only tracebacks which have occurred outside of the script's invocation will be printed.

Raises:

ScriptFunctionError - Any exception which occurs in the function passed in will be wrapped in this exception.

Note: If passing additional arguments, you must use named arguments, and not rely on the position of the arguments, as these arguments may be moved or even completely removed in later releases.

run(name, function)

Main entry point for script functions to be executed in a preconfigured environment.

This function wraps up the majority of the functionality offered by ext_run, except it allows it to be configured through command line arguments.

This function requires the logging and optparse (or optik) modules to be present - if they are not (which is the case for a standard Python 2.2 distribution), then a lot of the configurability which is normally provided will not be available.

You can find all the configuration options that are available by running this function and passing the --help command line option.

There are several options available which will affect how the script is executed, as well as other options which will do something different other than executing the script (such as configuring the default connection).

This script can be passed None as the function value - this will force all the command line handling and so on to take place, without requiring a script to be executed. This is useful if you want to know whether calling this function will actually result in your script being executed - for example, you might want to print the text "Running script...", but only if your script is actually going to executed.

This function does not return a value - if this method returns cleanly, then it means the script has been executed (without any problems). This function will raise SystemExit instances if it thinks it is appropriate to do so - this is always done if the script actually fails to be executed.

   0 - Exit generated by optparse (normally when running with C{--help}).
   2 - Required module is missing.
   3 - No default connection stored.
   4 - Error parsing command line arguments.
   5 - Connection not established.
  16 - Script not executed (command line options resulted in some other behaviour to occur).

If an exception occurs inside the script, it will be passed back to the caller of this function, but it will be wrapped in a ScriptFunctionError instance.

Note: sys.excepthook may be modified by this function to ensure that an exception is only printed once to the user with the most appopriate information.