wuttjamaican.install

Install Handler

class wuttjamaican.install.InstallHandler(config, **kwargs)

Base class and default implementation for the install handler.

See also get_install_handler().

The installer runs interactively via command line, prompting the user for various config settings etc.

If installation completes okay the exit code is 0, but if not:

• exit code 1 indicates user canceled

• exit code 2 indicates sanity check failed

• other codes possible if errors occur

Usually an app will define e.g. poser install command which would invoke the install handler’s run() method:

app = config.get_app()
install = app.get_install_handler(pkg_name='poser')
install.run()

Note that these first 4 attributes may be specified via constructor kwargs:

pkg_name

Python package name for the app, e.g. poser.

app_title

Display title for the app, e.g. “Poser”.

pypi_name

Package distribution name, e.g. for PyPI. If not specified one will be guessed.

egg_name

Egg name for the app. If not specified one will be guessed.

do_install_steps()

Perform the real installation steps.

This method is called by run() and does the following:

• call get_dbinfo() to get DB info from user, and test connection

• call make_template_context() to use when generating output

• call make_appdir() to create app dir with config files

• call install_db_schema() to (optionally) create tables in DB

get_dbinfo()

Collect DB connection info from the user, and test the connection. If connection fails, exit the install.

This method is normally called by do_install_steps().

Returns:

Dict of DB info collected from user.

install_db_schema(db_url, appdir=None)

First prompt the user, but if they agree then apply all Alembic migrations to the configured database.

This method is normally called by do_install_steps(). The end result should be a complete schema, ready for the app to use.

Parameters:

db_url – sqlalchemy.engine.URL instance.

make_appdir(context, appdir=None)

Create the app folder structure and generate config files.

This method is normally called by do_install_steps().

Parameters:

context – Template context dict, i.e. from make_template_context().

The default logic will create a structure as follows, assuming /venv is the path to the virtual environment:

/venv/
└── app/
    ├── cache/
    ├── data/
    ├── log/
    ├── work/
    ├── wutta.conf
    ├── web.conf
    └── upgrade.sh

File templates for this come from wuttjamaican:templates/install by default.

make_config_file(template, output_path, **kwargs)

Write a new config file to the given path, using the given template and context.

Parameters:

• template – Template instance, or name of one to fetch via lookup.

• output_path – Path to which output should be written.

• **kwargs – Extra context for the template.

Some context will be provided automatically for the template, but these may be overridden via the **kwargs:

• app_title - value from get_title().

• appdir - value from get_appdir().

• db_url - poser/dummy value

• os - reference to os module

This method is mostly about sorting out the context dict. Once it does that it calls render_mako_template().

make_template_context(dbinfo, **kwargs)

This must return a dict to be used as global template context when generating output (e.g. config) files.

This method is normally called by do_install_steps(). The context returned is then passed to render_mako_template().

Parameters:

• dbinfo – Dict of DB connection info as obtained from get_dbinfo().

• **kwargs – Extra template context.

Returns:

Dict for global template context.

The context dict will include:

• envdir - value from sys.prefix

• envname - “last” dirname from sys.prefix

• pkg_name - value from pkg_name

• app_title - value from app_title

• pypi_name - value from pypi_name

• egg_name - value from egg_name

• appdir - app folder under sys.prefix

• db_url - value from dbinfo['dburl']

prompt_bool(info, default=None)

Prompt the user for a boolean (Y/N) value.

Convenience wrapper around prompt_generic() with is_bool=True..

Returns:

True or False.

prompt_generic(info, default=None, is_password=False, is_bool=False, required=False)

Prompt the user to get their input.

See also prompt_bool().

Parameters:

• info – String to display (in bold) as prompt text.

• default – Default value to assume if user just presses Enter without providing a value.

• is_bool – Whether the prompt is for a boolean (Y/N) value, vs. a normal text value.

• is_password – Whether the prompt is for a “password” or other sensitive text value. (User input will be masked.)

• required – Whether the value is required (user must provide a value before continuing).

Returns:

String value provided by the user (or the default), unless is_bool was requested in which case True or False.

render_mako_template(template, context, output_path=None)

Convenience wrapper around render_mako_template().

Parameters:

template – Template instance, or name of one to fetch via lookup.

This method allows specifying the template by name, in which case the real template object is fetched via lookup.

Other args etc. are the same as for the wrapped app handler method.

rprint(*args, **kwargs)

Convenience wrapper for rich.print().

run()

Run the interactive command-line installer.

This does the following:

• check for prompt_toolkit and maybe ask to install it

• define the template lookup paths, for making config files

• call show_welcome()

• call sanity_check()

• call do_install_steps()

• call show_goodbye()

Although if a problem is encountered then not all calls may happen.

sanity_check()

Perform various sanity checks before doing the install. If any problem is found the installer should exit with code 2.

This is normally called by run().

show_goodbye()

Show the final message; this assumes setup completed okay.

This is normally called by run().

show_welcome()

Show the intro/welcome message, and prompt user to begin the install.

This is normally called by run().