main

New in version 1.1.0.

Configuration parameters

smisk.emergency_logfile

In case an application running with help from handle_errors_wrapper() (if running using main() with handle_errors=True) raises an exception outside of serving a HTTP transaction, Smisk will write (append) backtrace and error info to this file.

If not specified, the following path is used:

1. env[“SMISK_LOG_DIR”] + “/error.log” if SMISK_LOG_DIR is set in environ (not set by default)
2. env[“SMISK_APP_DIR”] + “/error.log” if SMISK_APP_DIR is set in environ (by default, smisk tries to deduce and set this if not already set)
3. “./error.log” as a last resort, if neigher smisk.emergency_logfile, SMISK_LOG_DIR or SMISK_APP_DIR is present.

Type:string Default:None

Functions

smisk.util.main.absapp(application, default_app_type=smisk.core.Application, *args, **kwargs)

Returns an application instance.

application can be None, a subclass of smisk.core.Application or an instance of some kind of smisk.core.Application.

• If application is None... * ...and there is already a global application instance, smisk.core.Application.current is returned. * ...and there is no global application instance, a new instance of default_app_type is created. *args and **kwargs are passed to the constructor.
• If application is a subclass of smisk.core.Application, an instance of that type will be created. *args and **kwargs are passed to the constructor.
• If application is already an instance of some kind of smisk.core.Application, application is returned untouched.

Raises ValueError:  if not possible. Return type:smisk.core.Application

smisk.util.main.setup_appdir(appdir=None)

Assures the SMISK_APP_DIR environment variable is set and points to the application directory.

If appdir is None, this function uses the following strategy for guessing the application directory:

appdir = os.path.dirname(sys.modules['__main__'].__file__)

smisk.util.main.main_cli_filter(appdir=None, bind=None, forks=None)

Command Line Interface parser.

For instance, it’s used by smisk.mvc.main().

Command line arguments:

--appdir PATH, --bind ADDR, --debug, --forks N, --help

When running as a program.

smisk.util.main.handle_errors_wrapper(fnc, error_cb=sys.exit, abort_cb=None, *args, **kwargs)

Call fnc catching any errors and writing information to error.log.

error.log will be written to, or appended to if it aldready exists, ENV["SMISK_LOG_DIR"]/error.log. If SMISK_LOG_DIR is not set, the file will be written to ENV["SMISK_APP_DIR"]/error.log. As a last resort ./error.log is used, in the case ENV["SMISK_APP_DIR"] is not present.

• KeyboardInterrupt is discarded/passed, causing a call to abort_cb, if set, without any arguments.
• SystemExit is passed on to Python and in normal cases causes a program termination, thus this function will not return.
• Any other exception causes error.log to be written to and finally a call to error_cb with a single argument; exit status code.

SMISK_LOG_DIR

Custom directory in which to write the error.log file.

Parameters:

• error_cb (callable) – Called after an exception was caught and info has been written to error.log. Receives a single argument: Status code as an integer. Defaults to sys.exit causing normal program termination. The returned value of this callable will be returned by handle_errors_wrapper itself.
• abort_cb (callable) – Like error_cb but instead called when KeyboardInterrupt was raised.

Return type:

object

smisk.util.main.main(application=None, appdir=None, bind=None, forks=None, handle_errors=True, cli=True, config=None, *args, **kwargs) → object

Helper for setting up and running an application.

This function handles command line options, calls Application.setup() to set up the application, and then calls Application.run(), entering the runloop.

This is normally what you do in your top module __init__:

from smisk.mvc import main
if __name__ == '__main__':
  main()

Your module is now a runnable program which automatically configures and runs your application.

Excessive arguments and keyword arguments are passed to Application.__init__(). If application is already an instance, these extra arguments and keyword arguments have no effect.

This function is not a true function, but rather an instance of Main.

Parameters:

• application – An application type or instance.
• appdir – Path to the applications base directory.
• bind – Bind to address (and port). Note that this overrides SMISK_BIND.
• forks – Number of child processes to spawn.
• handle_errors – Handle any errors by wrapping calls in smisk.util.main.handle_errors_wrapper()
• cli – Act as a Command Line Interface, parsing command line arguments and options.

Returns:

Anything returned by Main.run()

See:

Main.setup(), Main.run()

Classes

class smisk.util.main.Main(object)

Normally used through the common instance main().

default_app_type

__call__(application=None, appdir=None, bind=None, forks=None, handle_errors=True, cli=True, *args, **kwargs)

Helper for setting up and running an application.

See documentation of main()

setup(self, application=None, appdir=None, *args, **kwargs)

Helper for setting up an application.

*args and **kwargs are passed to absapp()

This function can only be called once. Successive calls simply returns the current application without making any modifications. If you want to update the application state, see Application.setup() instead, which can be called multiple times.

appdir

The application directory is the physical path in which your application module resides in the file system. Smisk need to know this and tries to automatically figure it out. However, there are cases where you need to explicitly define your application directory. For instance, if you’r calling main() or setup() from a sub-module of your application.

There are currently two ways of manually setting the application directory:

1. If appdir is specified, the environment variable SMISK_APP_DIR will be set to it’s value, effectively overwriting any previous value.
2. If appdir is not specified the application directory path will be aquired by dirname(<__main__ module>.__file__).

Environment variables

SMISK_APP_DIR

The physical location of the application. If not set, the value will be calculated like abspath(appdir) if the appdir argument is not None. In the case appdir is None, the value is calculated like this: dirname(<__main__ module>.__file__).

SMISK_ENVIRONMENT

Name of the current environment. If not set, this will be set to the default value returned by ‘environment()’.

Parameters:

• application – An application type or instance.
• appdir – Path to the applications base directory. Setting this will overwrite any previous value of environment variable SMISK_APP_DIR.

Returns:

The application

Return type:

Application

See:

main(), absapp(), setup_appdir(), run()

run(self, bind=None, application=None, forks=None, handle_errors=False)

Helper for running an application.

Note that because of the nature of libfcgi an application can not be started, stopped and then started again. That said, you can only start your application once per process. (Details: OS_ShutdownPending sets a process-wide flag causing any call to accept to bail out)

Environment variables

SMISK_BIND

If set and not empty, a call to smisk.core.bind will occur, passing the value to bind, effectively starting a stand-alone process.

Parameters:

• bind – Bind to address (and port). Note that this overrides SMISK_BIND.
• application – An application type or instance.
• forks – Number of child processes to spawn.
• handle_errors – Handle any errors by wrapping calls in smisk.util.main.handle_errors_wrapper()

Returns:

Anything returned by application.run()

Return type:

object

See:

main(), setup()