magpie.app

Magpie is a service for AuthN and AuthZ based on Ziggurat-Foundations.

Attributes

LOGGER

Classes

RemoveSlashNotFoundViewFactory

Utility that will try to resolve a path without appended slash if one was provided.

Functions

apply_response_format_tween(...)

Tween that applies the response Content-Type according to the requested Accept header or format query.

internal_server_error(...)

Overrides default HTTP.

not_found_or_method_not_allowed(...)

Overrides the default HTTPNotFound [404] by appropriate HTTPMethodNotAllowed [405] when applicable.

unauthorized_or_forbidden(...)

Overrides the default HTTP Forbidden [403] by appropriate Unauthorized [401] when applicable.

validate_accept_header_tween(...)

Tween that validates that the specified request Accept header or format query (if any) is supported.

setup_webhooks_config(→ None)

Prepares and validates Webhook settings for the application based on definitions in configuration file(s).

register_defaults(→ None)

Registers into database every undefined default users and groups matching following variables:

get_constant(→ magpie.typedefs.SettingValue)

Search in order for matched value of constant_name:

get_db_session_from_config_ini(config_ini_path[, ...])

run_database_migration_when_ready(→ None)

Runs db migration if requested by config and need from revisions.

set_sqlalchemy_log_level(→ magpie.typedefs.SettingsType)

Suppresses sqlalchemy verbose logging if not in logging.DEBUG for Magpie.

magpie_register_permissions_from_config(→ None)

Applies permissions specified in configuration(s) defined as file, directory with files or literal configuration.

magpie_register_services_from_config(...)

Registers Magpie services from one or many providers.cfg file.

get_auth_config(→ pyramid.config.Configurator)

Generates Magpie application configuration with all utilities required for security and access control.

fully_qualified_name(→ str)

Obtains the '<module>.<name>' full path definition of the object to allow finding and importing it.

get_logger(→ logging.Logger)

Immediately sets the logger level to avoid duplicate log outputs from the root logger and this logger when

log_exception_tween(...)

Tween factory that logs any exception before re-raising it.

log_request(→ None)

Subscriber event that logs basic details about the incoming requests.

patch_magpie_url(→ magpie.typedefs.SettingsType)

Updates potentially missing configuration settings for normal application execution.

print_log(→ None)

Logs the requested message to the logger and optionally enforce printing to the console according to configuration

setup_cache_settings(→ None)

Setup caching settings if not defined in configuration and enforce values if requested.

setup_pyramid_config(→ None)

Setup Pyramid utilities in the application configuration to define expected object references.

setup_session_config(→ None)

Setup database Session transaction handlers and Request properties for active User.

setup_ziggurat_config(→ None)

Setup ziggurat_foundations configuration settings and extensions that are required by Magpie.

setup_magpie_configs(→ None)

Resolve known configuration file paths from settings or environment variables and process them for the application.

main(→ pyramid.router.Router)

This function returns a Pyramid WSGI application.

Module Contents

class magpie.app.RemoveSlashNotFoundViewFactory(notfound_view=None)[source]

Bases: object

Utility that will try to resolve a path without appended slash if one was provided.

__call__(request)[source]
magpie.app.apply_response_format_tween(handler: Callable[[pyramid.request.Request], pyramid.httpexceptions.HTTPException], registry: pyramid.registry.Registry) → Callable[[pyramid.request.Request], pyramid.response.Response][source]

Tween that applies the response Content-Type according to the requested Accept header or format query.

The target Content-Type is expected to have been validated by validate_accept_header_tween() beforehand to handle not-acceptable errors. If an invalid format is detected at this stage, JSON is used by default. This can be the case for example for validate_accept_header_tween() itself that raises the error about the invalid Accept header or format query, but detects these inadequate parameters from incoming request.

The tween also ensures that additional request metadata extracted from get_request_info() is applied to the response body if not already provided by a previous operation.

magpie.app.internal_server_error(request: pyramid.request.Request) → pyramid.httpexceptions.HTTPException[source]

Overrides default HTTP.

magpie.app.not_found_or_method_not_allowed(request: pyramid.request.Request) → pyramid.httpexceptions.HTTPException[source]

Overrides the default HTTPNotFound [404] by appropriate HTTPMethodNotAllowed [405] when applicable.

Not found response can correspond to underlying process operation not finding a required item, or a completely unknown route (path did not match any existing API definition). Method not allowed is more specific to the case where the path matches an existing API route, but the specific request method (GET, POST, etc.) is not allowed on this path.

Without this fix, both situations return [404] regardless.

magpie.app.unauthorized_or_forbidden(request: pyramid.request.Request) → pyramid.httpexceptions.HTTPException[source]

Overrides the default HTTP Forbidden [403] by appropriate Unauthorized [401] when applicable.

Unauthorized response is for restricted user access according to missing credentials and/or authorization headers. Forbidden response is for operation refused by the underlying process operations or due to insufficient permissions.

Without this fix, both situations return Forbidden [403] regardless.

See also

In case the request references to Magpie UI route, it is redirected to magpie.ui.home.HomeViews.error_view() for it to handle and display the error accordingly.

magpie.app.validate_accept_header_tween(handler: Callable[[pyramid.request.Request], pyramid.response.Response], registry: pyramid.registry.Registry) → Callable[[pyramid.request.Request], pyramid.response.Response][source]

Tween that validates that the specified request Accept header or format query (if any) is supported.

Supported values are defined by SUPPORTED_ACCEPT_TYPES and for the given context of API or UI.

Raises:

HTTPNotAcceptable – if desired Accept or format specifier of content-type is not supported.

magpie.app.setup_webhooks_config(config_path: magpie.typedefs.Str | None, settings: magpie.typedefs.SettingsType) → None

Prepares and validates Webhook settings for the application based on definitions in configuration file(s).

Following execution, all validated Webhook configurations will have every parameters defined in WEBHOOK_KEYS, whether optional or mandatory. Required parameters in WEBHOOK_KEYS_REQUIRED are explicitly validated for defined value and raise if missing. Parameters from WEBHOOK_KEYS_OPTIONAL are defaulted to None if missing.

Any Webhook failing validation will raise the whole configuration and not apply any changes to the settings. Format validation is applied to some specific parameters to anticipate and raise definitions guaranteed to be erroneous to avoid waiting until runtime for them to fail upon their trigger event.

See also

Documentation in Webhook Configuration.

Parameters:

  • config_path – a single file or directory path where configuration file(s) with webhook section.

  • settings – modified settings in-place with added valid webhooks.

magpie.app.register_defaults(db_session: sqlalchemy.orm.session.Session | None = None, settings: magpie.typedefs.AnySettingsContainer | None = None, ini_file_path: magpie.typedefs.Str | None = None) → None[source]

Registers into database every undefined default users and groups matching following variables:

magpie.app.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[source]
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)

magpie.app.get_db_session_from_config_ini(config_ini_path, ini_main_section_name='app:magpie_app', settings_override=None)[source]
magpie.app.run_database_migration_when_ready(settings: magpie.typedefs.SettingsType, db_session: sqlalchemy.orm.session.Session | None = None) → None[source]

Runs db migration if requested by config and need from revisions.

magpie.app.set_sqlalchemy_log_level(magpie_log_level: magpie.typedefs.Str | int) → magpie.typedefs.SettingsType[source]

Suppresses sqlalchemy verbose logging if not in logging.DEBUG for Magpie.

magpie.app.magpie_register_permissions_from_config(permissions_config: magpie.typedefs.Str | magpie.typedefs.PermissionsConfig, settings: magpie.typedefs.AnySettingsContainer | None = None, db_session: sqlalchemy.orm.session.Session | None = None, raise_errors: bool = False) → None[source]

Applies permissions specified in configuration(s) defined as file, directory with files or literal configuration.

Parameters:

  • permissions_config – file/dir path to permissions config or JSON/YAML equivalent pre-loaded.

  • settings – Magpie settings to resolve an instance session when using requests instead of DB session. Will look for magpie.url, magpie.admin_user and magpie.admin_password by default, or any corresponding environment variable resolution if omitted in the settings.

  • db_session – db session to use instead of requests to directly create/remove permissions with config.

  • raise_errors – raises errors related to permissions, instead of just logging the info.

See also

magpie/config/permissions.cfg for specific parameters and operational details.

magpie.app.magpie_register_services_from_config(service_config_path: magpie.typedefs.Str, push_to_phoenix: bool = False, skip_registration: bool = False, force_update: bool = False, disable_getcapabilities: bool = False, db_session: sqlalchemy.orm.session.Session | None = None) → magpie.typedefs.ServicesSettings[source]

Registers Magpie services from one or many providers.cfg file.

Uses the provided DB session to directly update service definitions, or uses API request routes as admin. Optionally pushes updates to Phoenix.

Parameters:

  • service_config_path – where to look for providers configuration(s). Directory or file path.

  • push_to_phoenix – whether to push loaded service definitions to remote Phoenix service.

  • skip_registration – Load, validate and combine Service configurations, but don’t register them.

  • force_update – override service definitions that conflict by name with registered ones.

  • disable_getcapabilities – Skip GetCapabilities request validation and permission update. By default, any service with type that allows GetCapabilities permissions will be tested to ensure it can be reached on the provided url. Once validated, this permission is applied to anonymous group to make its entrypoint accessible by anyone. Services that cannot have GetCapabilities permission are ignored regardless.

  • db_session – Use a pre-established database connection for registration. Otherwise, API requests are employed.

Returns:

loaded service configurations.

magpie.app.get_auth_config(container: magpie.typedefs.AnySettingsContainer) → pyramid.config.Configurator[source]

Generates Magpie application configuration with all utilities required for security and access control.

magpie.app.fully_qualified_name(obj: Any | Type[Any]) → str[source]

Obtains the '<module>.<name>' full path definition of the object to allow finding and importing it.

magpie.app.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[source]

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

magpie.app.log_exception_tween(handler: Callable[[pyramid.request.Request], pyramid.response.Response], registry: pyramid.registry.Registry) → Callable[[pyramid.request.Request], pyramid.response.Response][source]

Tween factory that logs any exception before re-raising it.

Application errors are marked as ERROR while non-critical HTTP errors are marked as WARNING.

magpie.app.log_request(event: pyramid.events.NewRequest) → None[source]

Subscriber event that logs basic details about the incoming requests.

magpie.app.patch_magpie_url(container: magpie.typedefs.AnySettingsContainer) → magpie.typedefs.SettingsType[source]

Updates potentially missing configuration settings for normal application execution.

magpie.app.print_log(msg: magpie.typedefs.Str, logger: logging.Logger | None = None, level: int = logging.INFO, **kwargs: Any) → None[source]

Logs the requested message to the logger and optionally enforce printing to the console according to configuration value defined by MAGPIE_LOG_PRINT.

magpie.app.setup_cache_settings(settings: magpie.typedefs.SettingsType, force: bool = False, enabled: bool = False, expire: int = 0) → None[source]

Setup caching settings if not defined in configuration and enforce values if requested.

Required caching regions that were missing from configuration are initiated with disabled caching by default. This ensures that any decorators or region references will not cause unknown key or region errors.

Parameters:

  • settings – reference to application settings that will be updated in place.

  • force – enforce following parameters, otherwise only ensure that caching regions exist.

  • enabled – enable caching when enforced settings is requested.

  • expire – cache expiration delay if setting values are enforced and enabled.

magpie.app.setup_pyramid_config(config: pyramid.config.Configurator) → None[source]

Setup Pyramid utilities in the application configuration to define expected object references.

magpie.app.setup_session_config(config: pyramid.config.Configurator) → None[source]

Setup database Session transaction handlers and Request properties for active User.

magpie.app.setup_ziggurat_config(config: pyramid.config.Configurator) → None[source]

Setup ziggurat_foundations configuration settings and extensions that are required by Magpie.

Ensures that all needed extensions and parameter configuration values are defined as intended. Resolves any erroneous configuration or conflicts from the INI (backward compatible to when it was required to provide them explicitly) to guarantee that references are defined as needed for the application to behave correctly.

Parameters:

config – configurator reference when loading the web application.

magpie.app.LOGGER[source]
magpie.app.setup_magpie_configs(settings: magpie.typedefs.SettingsType, db_session: sqlalchemy.orm.session.Session | None = None, setup_providers: bool = True, setup_permissions: bool = True, setup_webhooks: bool = True, skip_registration: bool = False) → None[source]

Resolve known configuration file paths from settings or environment variables and process them for the application.

See also

magpie.app.main(global_config: magpie.typedefs.SettingsType | None = None, **settings: magpie.typedefs.SettingsType) → pyramid.router.Router[source]

This function returns a Pyramid WSGI application.