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.

check_appdir()

Check if the app dir already exists; exit with code 2 if so.

This is normally called from sanity_check().

do_install_steps()

Perform the real installation steps.

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

• call prompt_user_for_context() to collect DB info etc.

• 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_db_url()

This must return the DB engine URL.

Default logic will prompt the user for hostname, port, DB name and credentials. It then assembles the URL from those parts.

This method will also test the DB connection. If it fails, the install is aborted.

This method is normally called by prompt_user_for_context().

Returns:

SQLAlchemy engine URL (as object or string)

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.

This method calls make_appdir() for the basic structure and then write_all_config_files() for the gory details.

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(**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().

Note these first 2 params are not explicitly listed in the method signature; they are required nonetheless.

Parameters:

• db_url – This must be a string URL for the DB engine.

• wants_continuum – Whether data versioning should be enabled within the config.

• **kwargs – Extra template context.

Returns:

Dict for global template context.

The final context dict should include at least:

• 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 kwargs

• wants_continuum - value from kwargs

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.

prompt_user_for_context()

This is responsible for initial user prompts.

This happens early in the install, so this method can verify the info, e.g. test the DB connection, but should not write any files as the app dir may not exist yet.

Default logic calls get_db_url() for the DB connection, then may ask about Wutta-Continuum data versioning. (The latter is skipped if the package is missing.)

Subclass should override this method if they need different prompting logic. The return value should always include at least these 2 items:

• db_url - URL for the DB connection

• wants_continuum - whether data versioning should be enabled

Returns:

Dict of template context

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

• 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().

The default logic here just calls check_appdir().

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().

write_all_config_files(appdir, context)

This method should write all config files within the app dir. It’s called from make_appdir().

Subclass can override this for specialized installers.

Note that the app dir may or may not be newly-created, when this method is called. Some installers may support a “refresh” of the existing app dir.

Default logic (over)writes 3 files:

• wutta.conf

• web.cof

• upgrade.sh