`wuttaweb.util`¶

Web Utilities

class wuttaweb.util.FieldList(iterable=(), /)[source]¶

Convenience wrapper for a form’s field list. This is a subclass of list.

You normally would not need to instantiate this yourself, but it is used under the hood for fields as well as columns.

insert_after(field, newfield)[source]¶

Insert a new field, after an existing field.

Parameters:

field – String name for the existing field.
newfield – String name for the new field, to be inserted just after the existing field.

insert_before(field, newfield)[source]¶

Insert a new field, before an existing field.

Parameters:

field – String name for the existing field.
newfield – String name for the new field, to be inserted just before the existing field.

set_sequence(fields)[source]¶

Sort the list such that it matches the same sequence as the given fields list.

This does not add or remove any elements, it just (potentially) rearranges the internal list elements. Therefore you do not need to explicitly declare all fields; just the ones you care about.

The resulting field list will have the requested fields in order, at the beginning of the list. Any unrequested fields will remain in the same order as they were previously, but will be placed after the requested fields.

Parameters:: fields – List of fields in the desired order.

wuttaweb.util.get_available_themes(config)[source]¶

Returns the official list of theme names which are available for use in the app. Privileged users may choose among these when changing the global theme.

If config specifies a list, that will be honored. Otherwise the default list is: ['default', 'butterfly']

Note that the ‘default’ theme is Vue 2 + Buefy, while ‘butterfly’ is Vue 3 + Oruga.

You can specify via config by setting e.g.:

[wuttaweb]
themes.keys = default, butterfly, my-other-one

Parameters:: config – App config object.

wuttaweb.util.get_csrf_token(request)[source]¶

Convenience function, returns the effective CSRF token (raw string) for the given request.

See also render_csrf_token().

wuttaweb.util.get_effective_theme(config, theme=None, session=None)[source]¶

Validate and return the “effective” theme.

If caller specifies a theme then it will be returned (if “available” - see below).

Otherwise the current theme will be read from db setting. (Note we do not read simply from config object, we always read from db setting - this allows for the theme setting to change dynamically while app is running.)

In either case if the theme is not listed in get_available_themes() then a ValueError is raised.

Parameters:

config – App config object.
theme – Optional name of desired theme, instead of getting current theme per db setting.
session – Optional db session.

Returns:

Name of theme.

wuttaweb.util.get_form_data(request)[source]¶

Returns the effective form data for the given request.

Mostly this is a convenience, which simply returns one of the following, depending on various attributes of the request.

wuttaweb.util.get_liburl(request, key, configured_only=False, default_only=False, prefix='wuttaweb')[source]¶

Return the appropriate URL for the web resource library identified by key.

WuttaWeb makes certain assumptions about which libraries would be used on the frontend, and which versions for each would be used by default. But ultimately a URL must be determined for each, hence this function.

Each library has a built-in default URL which references a public Internet (i.e. CDN) resource, but your config can override the final URL in two ways:

The simplest way is to just override the version but otherwise let the default logic construct the URL. See get_libver() for more on that approach.

The most flexible way is to override the URL explicitly, e.g.:

[wuttaweb]
liburl.bb_vue = https://example.com/cache/vue-3.4.31.js

Parameters:

request – Current request.
key –
Unique key for the library, as string. Possibilities are:

Vue 2 + Buefy
- vue
- vue_resource
- buefy
- buefy.css
- fontawesome
Vue 3 + Oruga
- bb_vue
- bb_oruga
- bb_oruga_bulma
- bb_oruga_bulma_css
- bb_fontawesome_svg_core
- bb_free_solid_svg_icons
- bb_vue_fontawesome
configured_only – Pass True here if you only want the configured URL and ignore the default URL.
default_only – Pass True here if you only want the default URL and ignore the configured URL.
prefix –
If specified, will override the prefix used for config lookups.

Warning

This prefix param is for backward compatibility and may be removed in the future.

Returns:

The appropriate URL as string. Can also return None in some cases.

wuttaweb.util.get_libver(request, key, configured_only=False, default_only=False, prefix='wuttaweb')[source]¶

Return the appropriate version string for the web resource library identified by key.

WuttaWeb makes certain assumptions about which libraries would be used on the frontend, and which versions for each would be used by default. But it should also be possible to customize which versions are used, hence this function.

Each library has a built-in default version but your config can override them, e.g.:

[wuttaweb]
libver.bb_vue = 3.4.29

Parameters:

request – Current request.
key – Unique key for the library, as string. Possibilities are the same as for get_liburl().
configured_only – Pass True here if you only want the configured version and ignore the default version.
default_only – Pass True here if you only want the default version and ignore the configured version.
prefix –
If specified, will override the prefix used for config lookups.

Warning

This prefix param is for backward compatibility and may be removed in the future.

Returns:

The appropriate version string, e.g. '1.2.3' or 'latest' etc. Can also return None in some cases.

wuttaweb.util.get_model_fields(config, model_class, include_fk=False)[source]¶

Convenience function to return a list of field names for the given data model class.

This logic only supports SQLAlchemy mapped classes and will use that to determine the field listing if applicable. Otherwise this returns None.

Parameters:

config – App config object.
model_class – Data model class.
include_fk – Whether to include foreign key column names in the result. They are excluded by default, since the relationship names are also included and generally preferred.

Returns:

List of field names, or None if it could not be determined.

wuttaweb.util.get_theme_template_path(config, theme=None, session=None)[source]¶

Return the template path for effective theme.

If caller specifies a theme then it will be used; otherwise the current theme will be read from db setting. The logic for that happens in get_effective_theme(), which this function will call first.

Once we have the valid theme name, we check config in case it specifies a template path override for it. But if not, a default template path is assumed.

The default path would be expected to live under wuttaweb:templates/themes; for instance the butterfly theme has a default template path of wuttaweb:templates/themes/butterfly.

Parameters:

config – App config object.
theme – Optional name of desired theme, instead of getting current theme per db setting.
session – Optional db session.

Returns:

Path on disk to theme template folder.

wuttaweb.util.make_json_safe(value, key=None, warn=True)[source]¶

Convert a Python value as needed, to ensure it is compatible with json.dumps().

Parameters:

value – Python value.
key – Optional key for the value, if known. This is used when logging warnings, if applicable.
warn – Whether warnings should be logged if the value is not already JSON-compatible.

Returns:

A (possibly new) Python value which is guaranteed to be JSON-serializable.

wuttaweb.util.render_csrf_token(request, name='_csrf')[source]¶

Convenience function, returns CSRF hidden input inside hidden div, e.g.:

<div style="display: none;">
   <input type="hidden" name="_csrf" value="TOKEN" />
</div>

This function is part of wuttaweb.helpers (as csrf_token()) which means you can do this in page templates:

${h.form(request.current_route_url())}
${h.csrf_token(request)}
<!-- other fields etc. -->
${h.end_form()}

wuttaweb.util¶

`wuttaweb.util`¶