wizard.install

This module deals with marshalling information from the user to the install process for an application. We divide this process into two parts: this module addresses the specification of what fields the application is requesting, and submodules implement controller logic for actually getting this information from the user. Common logic between controllers is stored in this module.

ArgSchema is composed of two orthogonal components: a dictionary of Arg objects (which may be organized using ArgSet) and a list of Strategy objects. An Arg contains information about a given argument, and specified at compile-time by an application, while a Strategy contains a possible procedure for automatically determining what the contents of some argument are, and is specified at run-time by the user (this is not quite true yet, but will be soon). Some arguments are most commonly used together, so we group them together as an ArgSet and allow applications to refer to them as a single name.

Classes

class wizard.install.Strategy(schema, application, dir, web_stub_path)

Represents a strategy for calculating arg values without user input.

Under many circumstances, making some assumptions about the server environment means that we don’t actually have to ask the user for values such as the host or the path: these tend to be side effect free strategies. Furthermore, we may have utility scripts present that can automatically configure a new database for a user when one is necessary: these are side effectful computations.

Note for an implementor: it is perfectly acceptable to calculate preliminary results in prepare(), store them as underscore prefixed variables, and refer to them from execute().

application = None

The wizard.app.Application being installed.

dir = None

The directory we are being installed to.

execute(options)

Performs effectful computations associated with this strategy, and mutates options with the new values. Behavior is undefined if prepare() was not called first. If this method throws an exception, it should be treated as fatal.

prepare()

Performs all side-effectless computation associated with this strategy. It also detects if computation is possible, and raises StrategyFailed if it isn’t.

provides = frozenset([])

Arguments that this strategy provides

schema = None

The ArgSchema being created

side_effects = False

Whether or not this strategy has side effects.

web_stub_path = None

The directory web stub files are being installed to.

class wizard.install.Arg(name, **kwargs)

Represent a required, named argument for installation.

callback = None

Callback that this argument wants to get run on options after finished

envname

Name of the environment variable containing this arg.

help = None

Help string

name = None

Attribute name of the argument

password = False

If true, is a password

prompt = None

String to display if prompting a user for a value

type = None

String “type” of the argument, used for metavar

class wizard.install.ArgSet

Represents a set of named installation arguments that are required for an installation to complete successfully. Arguments in a set should share a common prefix and be related in functionality (the litmus test is if you need one of these arguments, you should need all of them). Register them in preloads().

args = None

The Arg objects that compose this argument set.

class wizard.install.ArgSchema(*args)

Schema container for arguments.

Valid identifiers for subclasses of ArgSet are:

• db, which populates the option dsn, which is a SQLAlchemy database source name, with properties for drivername, username, password, host, port, database and query.
• admin, which populates the options admin_name and admin_password.
• email, which populates the option email.
• title, which populates the option title.

The options web_path and web_host are automatically required.

Example:

parser = ArgHandler("db", "admin", "email")
parser.add(Arg("title", help="Title of the new application"))

add(arg)

Adds an argument to our schema.

args = None

Dictionary of argument names to Arg objects in schema.

commit(application, dir, web_stub_path)

Populates strategies and provides

fill(options)

Fills an object with all arguments pre-set to None.

load(options)

Load values from strategy. Must be called after commit(). We omit strategies whose provided variables are completely specified already. Will raise MissingRequiredParam if strategies aren’t sufficient to fill all options. It will then run any callbacks on arguments.

provides = None

Set of arguments that are already provided by strategies.

strategies = None

List of Strategy objects in schema.

Predefined classes

class wizard.install.WebArgSet

Bases: wizard.install.ArgSet

Common arguments for any application that lives on the web.

class wizard.install.DbArgSet

Bases: wizard.install.ArgSet

Common arguments for applications that use a database.

class wizard.install.AdminArgSet

Bases: wizard.install.ArgSet

Common arguments when an admin account is to be created.

class wizard.install.EmailArgSet

Bases: wizard.install.ArgSet

Common arguments when an administrative email is required.

class wizard.install.TitleArgSet

Bases: wizard.install.ArgSet

Common arguments when a title is required.

class wizard.install.EnvironmentStrategy(*args)

Bases: wizard.install.Strategy

Fills in values from environment variables, based off of Arg.envname from schema.

execute(options)

Sets undefined options to their environment variables.

prepare()

This strategy is always available.

class wizard.install.WebStrategy(schema, application, dir, web_stub_path)

Bases: wizard.install.Strategy

Performs guesses for web variables using the URL hook.

execute(options)

No-op.

prepare()

Uses deploy.web().

Functions

wizard.install.fetch(options, path, post=None)

Fetches a web page from the autoinstall, usually to perform database installation. path is the path of the file to retrieve, relative to the autoinstall base (options.web_path), not the web root. post is a dictionary to post. options is the options object generated by OptionParser.

wizard.install.preloads()

Retrieves a dictionary of string names to precanned ArgSet objects.

wizard.install.dsn_callback(options)

Exceptions

exception wizard.install.Error

Base error class for this module.

exception wizard.install.StrategyFailed

Bases: wizard.install.Error

Strategy couldn’t figure out values.

exception wizard.install.UnrecognizedPreloads(preloads)

Bases: wizard.install.Error

You passed a preload that was not recognized.

preloads = None

The preloads that were not recognized.

exception wizard.install.MissingRequiredParam(args)

Bases: wizard.install.Error

You missed a required argument, and we couldn’t generate it. Controllers should catch this exception and provide better behavior.

args = None

The names of the arguments that were not specified.