magpie.ui.utils

Attributes

CONTENT_TYPE_JSON
LOGGER

Classes

UserGroupStatus	Supported statuses of user-group relationships.
BaseViews	Base methods for Magpie UI pages.
AdminRequests	Regroups multiple administration-level operations to be dispatched to the API requests.

Functions

get_exception_info(→ magpie.typedefs.JSON)	Obtains additional exception content details about the response according to available information.
get_request_info(→ magpie.typedefs.JSON)	Obtains additional content details about the request according to available information.
get_logged_user(→ Optional[magpie.models.User])
get_constant(→ magpie.typedefs.SettingValue)	Search in order for matched value of constant_name:
mask_credentials(→ magpie.typedefs.JSON)	Masks away any credential matched against flags recursively from JSON container.
get_header(= None, split, ...)	Retrieves header_name by fuzzy match (independently of upper/lower-case and underscore/dash) from various
get_json(→ magpie.typedefs.JSON)	Retrieves the 'JSON' body of a response using the property/callable according to the response's implementation.
get_logger(→ logging.Logger)	Immediately sets the logger level to avoid duplicate log outputs from the root logger and this logger when
get_magpie_url(→ magpie.typedefs.Str)	Obtains the configured Magpie URL entrypoint based on the various combinations of supported configuration settings.
check_response(→ magpie.typedefs.AnyResponseType)	returns: response if the HTTP status code is successful.
request_api(→ magpie.typedefs.AnyResponseType)	Use a pyramid sub-request to request Magpie API routes via the UI. This avoids max retries and closed connections
redirect_error(→ magpie.typedefs.AnyResponseType)	Redirects the contents to be rendered by the UI 'error' page.
handle_errors(→ Callable)	Decorator that encapsulates the operation in a try/except block, and redirects the response to the UI error page

Module Contents

magpie.ui.utils.get_exception_info(response: pyramid.httpexceptions.HTTPException | pyramid.request.Request | pyramid.response.Response, content: magpie.typedefs.JSON | None = None, exception_details: bool = False) → magpie.typedefs.JSON

Obtains additional exception content details about the response according to available information.

magpie.ui.utils.get_request_info(request: pyramid.request.Request | pyramid.httpexceptions.HTTPException, default_message: magpie.typedefs.Str | None = None, exception_details: bool = False) → magpie.typedefs.JSON

Obtains additional content details about the request according to available information.

magpie.ui.utils.get_logged_user(request: pyramid.request.Request) → magpie.models.User | None

magpie.ui.utils.get_constant(constant_name: magpie.typedefs.Str, settings_container: magpie.typedefs.AnySettingsContainer | None = None, settings_name: magpie.typedefs.Str | None = None, default_value: magpie.typedefs.SettingValue | None = None, raise_not_set: bool = True, raise_missing: bool = True, print_missing: bool = False, empty_missing: bool = False) → magpie.typedefs.SettingValue

Search in order for matched value of constant_name:

1. search in MAGPIE_CONSTANTS

2. search in settings if specified

3. search alternative setting names (see below)

4. search in magpie.constants definitions

5. search in environment variables

Parameter constant_name is expected to have the format MAGPIE_[VARIABLE_NAME] although any value can be passed to retrieve generic settings from all above-mentioned search locations.

If settings_name is provided as alternative name, it is used as is to search for results if constant_name was not found. Otherwise, magpie.[variable_name] is used for additional search when the format MAGPIE_[VARIABLE_NAME] was used for constant_name (i.e.: MAGPIE_ADMIN_USER will also search for magpie.admin_user and so on for corresponding constants).

Parameters:

• constant_name – key to search for a value

• settings_container – WSGI application settings container (if not provided, uses found one in current thread)

• settings_name – alternative name for settings if specified

• default_value – default value to be returned if not found anywhere, and exception raises are disabled.

• raise_not_set – raise an exception if the found key is None, search until last case if others are None

• raise_missing – raise exception if key is not found anywhere

• print_missing – print message if key is not found anywhere, return None

• empty_missing – consider an empty value for an existing key as if it was missing (i.e.: as if not set).

Returns:

found value or default_value

Raises:

• ValueError – if resulting value is invalid based on options (by default raise missing/empty/None value)

• LookupError – if no appropriate value could be found from all search locations (according to options)

class magpie.ui.utils.UserGroupStatus

Bases: magpie.utils.FlexibleNameEnum

Supported statuses of user-group relationships.

ALL = 'all'

ACTIVE = 'active'

PENDING = 'pending'

classmethod allowed() → List[magpie.typedefs.Str]

Returns all supported representation values that can be mapped to a valid status.

magpie.ui.utils.mask_credentials(container: magpie.typedefs.JSON, redact: magpie.typedefs.Str = '[REDACTED]', flags: List[magpie.typedefs.Str] | None = None, parent: magpie.typedefs.Str | None = None) → magpie.typedefs.JSON

Masks away any credential matched against flags recursively from JSON container.

Matched credential entries are replaced by redact. List items are all replaced by the same redact when their parent field name is matched.

Parameters:

• container – JSON container to mask. If starting with a list on top-level, first level children will not be masked unless parent is provided.

• redact – string by which to replace flagged fields.

• flags – field names (partial matches) to flag for masking.

• parent – reference to contained elements if in a listing format rather than mapping.

Returns:

masked credentials JSON container.

magpie.ui.utils.CONTENT_TYPE_JSON = 'application/json'

magpie.ui.utils.get_header(header_name: magpie.typedefs.Str, header_container: magpie.typedefs.AnyHeadersType, default: magpie.typedefs.Str | None, magpie.typedefs.Str | List[magpie.typedefs.Str] | None, bool = None, split: magpie.typedefs.Str | List[magpie.typedefs.Str] | None = None, multi: bool = False, pop: bool = False) → magpie.typedefs.Str | List[magpie.typedefs.Str] | None

Retrieves header_name by fuzzy match (independently of upper/lower-case and underscore/dash) from various framework implementations of Headers.

If split is specified, the matched header_name is first split with it and the first item is returned. This allows to parse complex headers (e.g.: text/plain; charset=UTF-8 to text/plain with split=';').

Parameters:

• header_name – Header to find.

• header_container – Where to look for header_name.

• default – Value to returned if header_container is invalid or header_name could not be found.

• split – Character(s) to use to split the found header_name.

• multi – Return extracted header as array of multiple values or return a single value on fist match.

• pop – Remove the header from the container if found.

Returns:

Found header value(s) if applicable.

magpie.ui.utils.get_json(request_or_response: magpie.typedefs.AnyRequestType | magpie.typedefs.AnyResponseType) → magpie.typedefs.JSON

Retrieves the ‘JSON’ body of a response using the property/callable according to the response’s implementation.

magpie.ui.utils.get_logger(name: magpie.typedefs.Str, level: int | None = None, force_stdout: bool = None, message_format: magpie.typedefs.Str | None = None, datetime_format: magpie.typedefs.Str | None = None) → logging.Logger

Immediately sets the logger level to avoid duplicate log outputs from the root logger and this logger when level is logging.NOTSET.

magpie.ui.utils.get_magpie_url(container: magpie.typedefs.AnySettingsContainer | None = None) → magpie.typedefs.Str

Obtains the configured Magpie URL entrypoint based on the various combinations of supported configuration settings.

See also

Documentation section Application Settings for available setting combinations.

Parameters:

container – container that provides access to application settings.

Returns:

resolved Magpie URL

magpie.ui.utils.LOGGER

magpie.ui.utils.check_response(response: magpie.typedefs.AnyResponseType) → magpie.typedefs.AnyResponseType

Returns:

response if the HTTP status code is successful.

Raises:

HTTPError – (of appropriate type) if the response corresponds to an HTTP error code

magpie.ui.utils.request_api(request: pyramid.request.Request, path: magpie.typedefs.Str, method: magpie.typedefs.Str = 'GET', data: magpie.typedefs.JSON | magpie.typedefs.Str | None = None, headers: magpie.typedefs.HeadersType | None = None, cookies: magpie.typedefs.CookiesType | None = None) → magpie.typedefs.AnyResponseType

Use a pyramid sub-request to request Magpie API routes via the UI. This avoids max retries and closed connections when using 1 worker (eg: during tests).

Some information is retrieved from request to pass down to the sub-request (eg: cookies). If they are passed as argument, corresponding values will override the ones found in request.

All sub-requests to the API are assumed to be magpie.common.CONTENT_TYPE_JSON unless explicitly overridden with headers. Headers are also looked for additional Set-Cookie header in case they need to be passed down to cookies.

Parameters:

• request – incoming Magpie UI request that requires sub-request to Magpie API, to retrieve required details.

• path – local Magpie API path (relative to root without URL).

• method – HTTP method to send the API sub-request.

• data – JSON dictionary or literal string content of the request body.

• headers – override headers to employ for the API sub-request. Defaults to JSON Accept & Content-Type headers.

• cookies – Override cookies to employ for the API sub-request. Defaults to current logged user. For empty cookies (no user), explicitly provide an empty dictionary.

magpie.ui.utils.redirect_error(request: pyramid.request.Request, code: int = None, content: magpie.typedefs.JSON | None = None) → magpie.typedefs.AnyResponseType

Redirects the contents to be rendered by the UI ‘error’ page.

Parameters:

• request – incoming request that resulted into some kind of error.

• code – explicit HTTP status code for the error response, extracted from contents if otherwise available.

• content – any body content provided as error response from the API.

magpie.ui.utils.handle_errors(func: Callable) → Callable

Decorator that encapsulates the operation in a try/except block, and redirects the response to the UI error page with API error contents.

In worst case scenario where the operation cannot figure out what to do with the exception response, raise the most basic HTTPInternalServerError that can be formulated from available details.

See also

redirect_error()

class magpie.ui.utils.BaseViews(request)

Bases: object

Base methods for Magpie UI pages.

MAGPIE_FIXED_GROUP_MEMBERSHIPS = []

Special Group memberships that cannot be edited.

MAGPIE_FIXED_GROUP_EDITS = []

Special Group details that cannot be edited.

MAGPIE_FIXED_USERS = []

Special User details that cannot be edited.

MAGPIE_FIXED_USERS_REFS = []

Special User that cannot have any relationship edited.

This includes both Group memberships and Permission references.

MAGPIE_USER_PWD_LOCKED = []

Special User that could self-edit themselves, but is disabled since conflicting with other policies.

MAGPIE_USER_PWD_DISABLED = []

Special User where password cannot be edited (managed by Magpie configuration settings).

MAGPIE_ANONYMOUS_GROUP = None

Reference to magpie.constants.MAGPIE_ANONYMOUS_GROUP for convenience in UI pages.

add_template_data(data: Dict[magpie.typedefs.Str, Any] | None = None) → Dict[magpie.typedefs.Str, Any]

Adds required template data for the ‘heading’ mako template applied to every UI page.

render(template: magpie.typedefs.Str, data: Dict[magpie.typedefs.Str, Any] | None = None) → pyramid.response.Response

Render the response with an explicit Mako template reference.

Views that are decorated by pyramid.view.view_config() or registered by pyramid.config.Configurator.add_view() with a renderer parameter do not require to call this function as it is auto-resolved with the submitted data.

class magpie.ui.utils.AdminRequests(request)

Bases: BaseViews

Regroups multiple administration-level operations to be dispatched to the API requests.

create_user_default_template_data(data)

Generates all the default values for the various fields employed for display purposes of the user creation form.

Parameters:

data – any template data that should override the defaults.

Returns:

updated template data with defaults and overridden values.

get_admin_session() → magpie.typedefs.CookiesType

Temporarily login as default administrator to execute an elevated operation that the current user cannot make.

Warning

Cookies MUST NOT be preserved or memorized, to avoid user gaining restricted access. This is intended only for basic operations such as validating information. Care must be taken such information retrieved this way do not provide a way of non-administrator to indirectly infer some otherwise protected information. User sparingly.

Returns:

Cookies of the administrator login.

get_all_groups(first_default_group=None)

get_group_info(group_name: magpie.typedefs.Str) → magpie.typedefs.JSON

get_group_users(group_name: magpie.typedefs.Str, user_group_status: magpie.models.UserGroupStatus = UserGroupStatus.ACTIVE) → List[magpie.typedefs.Str]

update_group_info(group_name: magpie.typedefs.Str, group_info: magpie.typedefs.JSON) → magpie.typedefs.JSON

delete_group(group_name: magpie.typedefs.Str) → magpie.typedefs.JSON

get_user_groups(user_name: magpie.typedefs.Str, user_group_status: magpie.models.UserGroupStatus = UserGroupStatus.ACTIVE) → List[magpie.typedefs.Str]

get_user_names()

Obtains all user names.

get_user_statuses(status: magpie.typedefs.Str | int = 0) → List[magpie.typedefs.Str]

Obtains all user names that have the corresponding status value.

get_user_emails()

get_user_details(status: str | int | None = None, cookies: magpie.typedefs.CookiesType | None = None) → List[magpie.typedefs.JSON]

Obtains all user details, optionally filtered to by corresponding status value.

Employ this method to avoid multiple requests fetching individual information.

See also

• get_user_emails()

• get_user_names()

• get_user_statuses()

get_resource_types()

Returns:

dictionary of all resources as {id: ‘resource_type’}

Return type:

dict

static flatten_tree_resource(resource_node, resource_dict)

Parameters:

• resource_node – any-level dictionary composing the resources tree

• resource_dict – reference of flattened dictionary across levels

Returns:

flattened dictionary resource_dict of all {id: ‘resource_type’}

Return type:

dict

get_services(cur_svc_type)

get_service_data(service_name)

get_service_types()

update_service_name(old_service_name, new_service_name, service_push)

update_service_url(service_name, new_service_url, service_push)

create_user(data)

Processes the user creation form with fields input data.

All the fields are pre- and post-validated according to expected behaviour by the API. Pre-validations attempt soft checks to detect as many potential errors such that they can all be simultaneously displayed on the form, to avoid back-and-forth erroneous submissions by the user. Post-validations are the hard checks imposed by the API, which include some of the pre-checks.

Whenever some failure occurs, returned data will contain is_error with True or False accordingly. Following successful request without error, the User will be created. It is up to the calling function to redirect the response and further process the returned data as needed.

Parameters:

data – initial templated data overrides according to who is initiation the user creation.

Returns:

updated template data with any relevant error messages and statuses if applicable.

Raises:

HTTPException – any unhandled or unknown HTTP error received from the API.