wuttjamaican.app

WuttJamaican - app handler

class wuttjamaican.app.AppHandler(config)

Base class and default implementation for top-level app handler.

aka. “the handler to handle all handlers”

aka. “one handler to bind them all”

For more info see App Handler.

There is normally no need to create one of these yourself; rather you should call get_app() on the config object if you need the app handler.

Parameters:

config – Config object for the app. This should be an instance of WuttaConfig.

model

Reference to the app model module.

Note that get_model() is responsible for determining which module this will point to. However you can always get the model using this attribute (e.g. app.model) and do not need to call get_model() yourself - that part will happen automatically.

enum

Reference to the app enum module.

Note that get_enum() is responsible for determining which module this will point to. However you can always get the model using this attribute (e.g. app.enum) and do not need to call get_enum() yourself - that part will happen automatically.

providers

Dictionary of AppProvider instances, as returned by get_all_providers().

property appname

The app name for the current app. This is just an alias for wuttjamaican.conf.WuttaConfig.appname.

Note that this appname does not necessariy reflect what you think of as the name of your (e.g. custom) app. It is more fundamental than that; your Python package naming and the app title are free to use a different name as their basis.

continuum_is_enabled()

Returns boolean indicating if Wutta-Continuum is installed and enabled.

Default will be False as enabling it requires additional installation and setup. For instructions see Installation.

delete_setting(session, name)

Delete a config setting from the DB.

See also get_setting() and save_setting().

Parameters:

• session – Current db session.

• name – Name of the setting to delete.

display_format_date = '%Y-%m-%d'

Format string to use when displaying datetime.date objects. See also render_date().

display_format_datetime = '%Y-%m-%d %H:%M%z'

Format string to use when displaying datetime.datetime objects. See also render_datetime().

get_all_providers()

Load and return all registered providers.

Note that you do not need to call this directly; instead just use providers.

The discovery logic is based on entry points using the wutta.app.providers group. For instance here is a sample entry point used by WuttaWeb (in its pyproject.toml):

[project.entry-points."wutta.app.providers"]
wuttaweb = "wuttaweb.app:WebAppProvider"

Returns:

Dictionary keyed by entry point name; values are AppProvider instances.

get_appdir(*args, **kwargs)

Returns path to the app dir.

This does not check for existence of the path, it only reads it from config or (optionally) provides a default path.

Parameters:

• configured_only – Pass True here if you only want the configured path and ignore the default path.

• create – Pass True here if you want to ensure the returned path exists, creating it if necessary.

• *args – Any additional args will be added as child paths for the final value.

For instance, assuming /srv/envs/poser is the virtual environment root:

app.get_appdir()             # => /srv/envs/poser/app

app.get_appdir('data')       # => /srv/envs/poser/app/data

get_auth_handler(**kwargs)

Get the configured auth handler.

Return type:

AuthHandler

get_db_handler(**kwargs)

Get the configured db handler.

Return type:

DatabaseHandler

get_distribution(obj=None)

Returns the appropriate Python distribution name.

If obj is specified, this will attempt to locate the distribution based on the top-level module which contains the object’s type/class.

If obj is not specified, this behaves a bit differently. It first will look for a config setting named wutta.app_dist (or similar, dpending on appname). If there is such a config value, it is returned. Otherwise the “auto-locate” logic described above happens, but using self instead of obj.

In other words by default this returns the distribution to which the running app handler belongs.

See also get_version().

Parameters:

obj – Any object which may be used as a clue to locate the appropriate distribution.

Returns:

string, or None

Also note that a distribution name is different from a package name. The distribution name is how things appear on PyPI for instance.

If you want to override the default distribution name (and skip the auto-locate based on app handler) then you can define it in config:

[wutta]
app_dist = My-Poser-Dist

get_email_handler(**kwargs)

Get the configured email handler.

See also send_email().

Return type:

EmailHandler

get_enum()

Returns the app enum module.

Note that you don’t actually need to call this method; you can get the module by simply accessing enum (e.g. app.enum) instead.

By default this will return wuttjamaican.enum unless the config class or some config extension has provided another default.

A custom app can override the default like so (within a config extension):

config.setdefault('wutta.enum_spec', 'poser.enum')

get_install_handler(**kwargs)

Get the configured install handler.

Return type:

InstallHandler

get_model()

Returns the app model module.

Note that you don’t actually need to call this method; you can get the model by simply accessing model (e.g. app.model) instead.

By default this will return wuttjamaican.db.model unless the config class or some config extension has provided another default.

A custom app can override the default like so (within a config extension):

config.setdefault('wutta.model_spec', 'poser.db.model')

get_node_title(default=None)

Returns the configured title for the local app node.

If none is configured, and no default provided, will return the value from get_title().

Parameters:

default – Value to use if the node title is not configured.

Returns:

Title for the local app node.

get_node_type(default=None)

Returns the “type” of current app node.

The framework itself does not (yet?) have any notion of what a node type means. This abstraction is here for convenience, in case it is needed by a particular app ecosystem.

Returns:

String name for the node type, or None.

The node type must be configured via file; this cannot be done with a DB setting. Depending on appname that is like so:

[wutta]
node_type = warehouse

get_people_handler(**kwargs)

Get the configured “people” handler.

Return type:

PeopleHandler

get_person(obj, **kwargs)

Convenience method to locate a Person for the given object.

This delegates to the “people” handler method, get_person().

get_session(obj)

Returns the SQLAlchemy session with which the given object is associated. Simple convenience wrapper around sqlalchemy.orm.object_session().

get_setting(session, name, **kwargs)

Get a config setting value from the DB.

This does not consult the config object directly to determine the setting value; it always queries the DB.

Default implementation is just a convenience wrapper around get_setting().

See also save_setting() and delete_setting().

Parameters:

• session – App DB session.

• name – Name of the setting to get.

Returns:

Setting value as string, or None.

get_title(default=None)

Returns the configured title for the app.

Parameters:

default – Value to be returned if there is no app title configured.

Returns:

Title for the app.

get_version(dist=None, obj=None)

Returns the version of a given Python distribution.

If dist is not specified, calls get_distribution() to get it. (It passes obj along for this).

So by default this will return the version of whichever distribution owns the running app handler.

Returns:

Version as string.

load_object(spec)

Import and/or load and return the object designated by the given spec string.

This invokes wuttjamaican.util.load_object().

Parameters:

spec – String of the form module.dotted.path:objname.

Returns:

The object referred to by spec. If the module could not be imported, or did not contain an object of the given name, then an error will raise.

make_appdir(path, subfolders=None, **kwargs)

Establish an app dir at the given path.

Default logic only creates a few subfolders, meant to help steer the admin toward a convention for sake of where to put things. But custom app handlers are free to do whatever.

Parameters:

• path – Path to the desired app dir. If the path does not yet exist then it will be created. But regardless it should be “refreshed” (e.g. missing subfolders created) when this method is called.

• subfolders – Optional list of subfolder names to create within the app dir. If not specified, defaults will be: ['cache', 'data', 'log', 'work'].

make_session(**kwargs)

Creates a new SQLAlchemy session for the app DB. By default this will create a new Session instance.

Returns:

SQLAlchemy session for the app DB.

make_title(text, **kwargs)

Return a human-friendly “title” for the given text.

This is mostly useful for converting a Python variable name (or similar) to a human-friendly string, e.g.:

make_title('foo_bar')     # => 'Foo Bar'

By default this just invokes wuttjamaican.util.make_title().

make_true_uuid()

Generate a new UUID value.

By default this simply calls wuttjamaican.util.make_true_uuid().

Returns:

uuid.UUID instance

Warning

For now, callers should use this method when they want a proper UUID instance, whereas make_uuid() will always return a string.

However once all dependent logic has been refactored to support proper UUID data type, then make_uuid() will return those and this method will eventually be removed.

make_uuid()

Generate a new UUID value.

By default this simply calls wuttjamaican.util.make_uuid().

Returns:

UUID value as 32-character string.

Warning

For now, this method always returns a string.

However once all dependent logic has been refactored to support proper UUID data type, then this method will return those and the make_true_uuid() method will eventually be removed.

progress_loop(*args, **kwargs)

Convenience method to iterate over a set of items, invoking logic for each, and updating a progress indicator along the way.

This is a wrapper around wuttjamaican.util.progress_loop(); see those docs for param details.

render_date(value)

Return a human-friendly display string for the given date.

Uses display_format_date to render the value.

Parameters:

value – A datetime.date instance (or None).

Returns:

Display string, or None.

render_datetime(value)

Return a human-friendly display string for the given datetime.

Uses display_format_datetime to render the value.

Parameters:

value – A datetime.datetime instance (or None).

Returns:

Display string, or None.

render_mako_template(template, context, output_path=None)

Convenience method to render a Mako template.

Parameters:

• template – Template instance.

• context – Dict of context for the template.

• output_path – Optional path to which output should be written.

Returns:

Rendered output as string.

render_time_ago(value)

Return a human-friendly string, indicating how long ago something occurred.

Default logic uses humanize.naturaltime() for the rendering.

Parameters:

value – Instance of datetime.datetime or datetime.timedelta.

Returns:

Text to display.

resource_path(path)

Convenience wrapper for wuttjamaican.util.resource_path().

save_setting(session, name, value, force_create=False)

Save a config setting value to the DB.

See also get_setting() and delete_setting().

Parameters:

• session – Current db session.

• name – Name of the setting to save.

• value – Value to be saved for the setting; should be either a string or None.

• force_create –

  If False (the default) then logic will first try to locate an existing setting of the same name, and update it if found, or create if not.

  But if this param is True then logic will only try to create a new record, and not bother checking to see if it exists.

  (Theoretically the latter offers a slight efficiency gain.)

send_email(*args, **kwargs)

Send an email message.

This is a convenience wrapper around send_email().

short_session(**kwargs)

Returns a context manager for a short-lived database session.

This is a convenience wrapper around short_session.

If caller does not specify factory nor config params, this method will provide a default factory in the form of make_session().

class wuttjamaican.app.AppProvider(config)

Base class for app providers.

These can add arbitrary extra functionality to the main app handler. See also App Providers.

Parameters:

config – The app config object.

Instances have the following attributes:

config

Reference to the config object.

app

Reference to the parent app handler.

property appname

The app name for the current app.

See also AppHandler.appname.

class wuttjamaican.app.GenericHandler(config)

Generic base class for handlers.

When the app defines a new type of handler it may subclass this when defining the handler base class.

Parameters:

config – Config object for the app. This should be an instance of WuttaConfig.

property appname

The app name for the current app.

See also AppHandler.appname.