magpie.utils

Module Contents

Classes

ExtendedEnum	Utility enum.Enum methods.
FlexibleNameEnum	Enum that allows more permissive name cases for lookup.
SingletonMeta	A metaclass that creates a Singleton base class when called.
classproperty	Mimics property decorator, but applied onto classmethod in backward compatible way.

Functions

get_logger(→ logging.Logger)	Immediately sets the logger level to avoid duplicate log outputs from the root logger and this logger when
set_logger_config(→ logging.Logger)	Applies the provided logging configuration settings to the logger.
print_log(→ None)	Logs the requested message to the logger and optionally enforce printing to the console according to configuration
raise_log(→ NoReturn)	Logs the provided message to the logger and raises the corresponding exception afterwards.
bool2str(→ magpie.typedefs.Str)	Converts value to explicit "true" or "false" str with permissive variants comparison
islambda(→ bool)	Evaluate if argument is a callable lambda expression.
isclass(→ bool)	Evaluate an object for class type (ie: class definition, not an instance nor any other type).
ismethod(→ bool)	Evaluate an object for method type (i.e.: class method reference.
signature_with_args(→ magpie.typedefs.Str)	Returns a visual representation of a function signature with is arguments.
get_settings_from_config_ini(...)
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.
cleanup_session(→ Callable[[pyramid.request.Request], ...)	Tween that forces the database connection to be closed once the response is obtained from the request.
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.
debug_cookie_identify(request)	Logs debug information about request cookie.
get_request_user(→ Optional[magpie.models.User])	Obtains the user that corresponds to the authentication details found in the request.
get_json(→ magpie.typedefs.JSON)	Retrieves the 'JSON' body of a response using the property/callable according to the response's implementation.
get_header(= None, split, ...)	Retrieves header_name by fuzzy match (independently of upper/lower-case and underscore/dash) from various
convert_response(→ pyramid.response.Response)	Converts a requests.Response object to an equivalent pyramid.response.Response object.
get_authenticate_headers(...)	Obtains all required headers by 401 responses based on executed request.
get_cookies(→ magpie.typedefs.CookiesType)	Retrieves a dictionary of cookie names and values from distinct implementations and container types.
get_admin_cookies(→ magpie.typedefs.CookiesType)
get_registry(→ Optional[pyramid.registry.Registry])	Retrieves the application registry from various containers referencing to it.
get_settings(→ magpie.typedefs.SettingsType)	Retrieve application settings from a supported container.
import_target(→ Optional[Any])	Imports a target resource from a Python script as module.
normalize_field_pattern(→ magpie.typedefs.Str)	Escapes necessary regex pattern characters and applies start/end-of-line control characters.
patch_magpie_url(→ magpie.typedefs.SettingsType)	Updates potentially missing configuration settings for normal application execution.
get_magpie_url(→ magpie.typedefs.Str)	Obtains the configured Magpie URL entrypoint based on the various combinations of supported configuration settings.
get_phoenix_url(→ magpie.typedefs.Str)	Obtains the configured Phoenix URL entrypoint based on the various combinations of supported configuration settings.
get_twitcher_url(→ magpie.typedefs.Str)	Obtains the configured Twitcher URL entrypoint based on various combinations of supported configuration settings.
get_twitcher_protected_service_url(→ magpie.typedefs.Str)	Obtains the protected service URL behind Twitcher Proxy based on combination of supported configuration settings.
is_magpie_ui_path(→ bool)	Determines if the request path corresponds to any Magpie UI location.
fully_qualified_name(→ str)	Obtains the '<module>.<name>' full path definition of the object to allow finding and importing it.
log_request_format(→ magpie.typedefs.Str)
log_request(→ None)	Subscriber event that logs basic details about the incoming requests.
log_exception_tween(...)	Tween factory that logs any exception before re-raising it.
is_json_body(→ bool)
decompose_enum_flags(→ List[enum.Enum])	Decompose a Flag-enabled Enum into its individual parts.

Attributes

CONTENT_TYPE_ANY
CONTENT_TYPE_JSON
CONTENT_TYPE_FORM
CONTENT_TYPE_HTML
CONTENT_TYPE_PLAIN
CONTENT_TYPE_APP_XML
CONTENT_TYPE_TXT_XML
FORMAT_TYPE_MAPPING
SUPPORTED_ACCEPT_TYPES
SUPPORTED_FORMAT_TYPES
KNOWN_CONTENT_TYPES
LOGGER

magpie.utils.CONTENT_TYPE_ANY = '*/*'

magpie.utils.CONTENT_TYPE_JSON = 'application/json'

magpie.utils.CONTENT_TYPE_FORM = 'application/x-www-form-urlencoded'

magpie.utils.CONTENT_TYPE_HTML = 'text/html'

magpie.utils.CONTENT_TYPE_PLAIN = 'text/plain'

magpie.utils.CONTENT_TYPE_APP_XML = 'application/xml'

magpie.utils.CONTENT_TYPE_TXT_XML = 'text/xml'

magpie.utils.FORMAT_TYPE_MAPPING

magpie.utils.SUPPORTED_ACCEPT_TYPES

magpie.utils.SUPPORTED_FORMAT_TYPES

magpie.utils.KNOWN_CONTENT_TYPES

magpie.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.utils.LOGGER

magpie.utils.set_logger_config(logger: logging.Logger, force_stdout: bool = False, message_format: magpie.typedefs.Str | None = None, datetime_format: magpie.typedefs.Str | None = None, log_file: magpie.typedefs.Str | None = None) → logging.Logger

Applies the provided logging configuration settings to the logger.

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

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

magpie.utils.raise_log(msg: magpie.typedefs.Str, exception: Type[Exception] = Exception, logger: logging.Logger | None = None, level: int = logging.ERROR) → NoReturn

Logs the provided message to the logger and raises the corresponding exception afterwards.

Raises:

exception – whichever exception provided is raised systematically after logging.

magpie.utils.bool2str(value: Any) → magpie.typedefs.Str

Converts value to explicit "true" or "false" str with permissive variants comparison that can represent common falsy or truthy values.

magpie.utils.islambda(func: Any) → bool

Evaluate if argument is a callable lambda expression.

magpie.utils.isclass(obj: Any) → bool

Evaluate an object for class type (ie: class definition, not an instance nor any other type).

magpie.utils.ismethod(obj: Any) → bool

Evaluate an object for method type (i.e.: class method reference.

magpie.utils.signature_with_args(func: Callable[[Ellipsis], Any], *args: Any, **kwargs: Any) → magpie.typedefs.Str

Returns a visual representation of a function signature with is arguments.

def function(a, b, c=1): ...

signature_with_args(function, 1, 2, c=3)

# returns:  <module.function(a=1, b=2, c=3)>

magpie.utils.get_settings_from_config_ini(config_ini_path: magpie.typedefs.Str, ini_main_section_name: magpie.typedefs.Str = 'app:magpie_app') → magpie.typedefs.SettingsType

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

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.utils.setup_pyramid_config(config: pyramid.config.Configurator) → None

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

magpie.utils.cleanup_session(handler: Callable[[pyramid.request.Request], pyramid.response.Response], _: pyramid.registry.Registry) → Callable[[pyramid.request.Request], pyramid.response.Response]

Tween that forces the database connection to be closed once the response is obtained from the request.

magpie.utils.setup_session_config(config: pyramid.config.Configurator) → None

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

magpie.utils.setup_ziggurat_config(config: pyramid.config.Configurator) → None

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.utils.debug_cookie_identify(request)

Logs debug information about request cookie.

Warning

This function is intended for debugging purposes only. It reveals sensible configuration information.

Re-implements basic functionality of pyramid.AuthTktAuthenticationPolicy.cookie.identify() called via request.unauthenticated_userid() within get_request_user() to provide additional logging.

See also

• pyramid.authentication.AuthTktCookieHelper

• pyramid.authentication.AuthTktAuthenticationPolicy

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

Obtains the user that corresponds to the authentication details found in the request.

Prior to resolving the user matching the authenticated user ID, reattaches the detached session or closed transaction if commit occurred beforehand. This can happen for example when creating a user from a pending-user where the user must be committed to allow webhooks to refer to it immediately, although the request has not completed processing. Operations using the request.user reference following that user creation could have a detached object state from the session. Ensure that any resolved user is also attached to the reestablished database session reference in the request.

After reattaching to the session, following step is the original configuration setup similarly to typical methodology:

config.include("ziggurat_foundations.ext.pyramid.get_user")

Parameters:

request – request to look for authenticated user.

Returns:

authenticated user or none if unauthenticated.

magpie.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.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.utils.convert_response(response: magpie.typedefs.AnyResponseType) → pyramid.response.Response

Converts a requests.Response object to an equivalent pyramid.response.Response object.

Content of the response is expected to be JSON.

Parameters:

response – Response to be converted.

Returns:

Converted response.

magpie.utils.get_authenticate_headers(request: pyramid.request.Request, error_type: magpie.typedefs.Str = 'invalid_token') → magpie.typedefs.HeadersType | None

Obtains all required headers by 401 responses based on executed request.

Parameters:

• request – request that was sent to attempt authentication or access which must respond with Unauthorized.

• error_type – Additional detail of the cause of error. Must be one of (invalid_request, invalid_token, insufficient_scope).

magpie.utils.get_cookies(request_or_response: magpie.typedefs.AnyRequestType | magpie.typedefs.AnyResponseType) → magpie.typedefs.CookiesType

Retrieves a dictionary of cookie names and values from distinct implementations and container types.

Parameters:

request_or_response – Object that potentially contains cookies, by literal property or corresponding headers.

Returns:

Found cookies.

magpie.utils.get_admin_cookies(container: magpie.typedefs.AnySettingsContainer, verify: bool = True, raise_message: magpie.typedefs.Str | None = None) → magpie.typedefs.CookiesType

magpie.utils.get_registry(container: magpie.typedefs.AnyRegistryContainer | None = None, nothrow: bool = False) → pyramid.registry.Registry | None

Retrieves the application registry from various containers referencing to it.

magpie.utils.get_settings(container: magpie.typedefs.AnySettingsContainer | None, app: bool = False) → magpie.typedefs.SettingsType

Retrieve application settings from a supported container.

Parameters:

• container – supported container with a handle to application settings.

• app – allow retrieving from current thread registry if no container was defined.

Returns:

found application settings dictionary.

Raises:

TypeError – when no application settings could be found or unsupported container.

magpie.utils.import_target(target: magpie.typedefs.Str, default_root: magpie.typedefs.Str | None = None) → Any | None

Imports a target resource from a Python script as module.

The Python script does not need to be defined within a module directory (i.e.: with __init__.py). Files can be imported from virtually anywhere. To avoid name conflicts in generated module references, each imported target employs its full escaped file path as module name.

Format expected as follows:

"path/to/script.py:function"

Parameters:

• target – Resource to be imported.

• default_root – Root directory to employ if target is relative (default magpie.constants.MAGPIE_ROOT).

Returns:

Found and imported resource or None.

magpie.utils.normalize_field_pattern(pattern: magpie.typedefs.Str, escape: bool = True) → magpie.typedefs.Str

Escapes necessary regex pattern characters and applies start/end-of-line control characters.

magpie.utils.patch_magpie_url(container: magpie.typedefs.AnySettingsContainer) → magpie.typedefs.SettingsType

Updates potentially missing configuration settings for normal application execution.

magpie.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.utils.get_phoenix_url(container: magpie.typedefs.AnySettingsContainer | None = None) → magpie.typedefs.Str

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

See also

Documentation section Phoenix Settings for available setting combinations.

Parameters:

container – container that provides access to application settings.

Returns:

resolved Phoenix URL

magpie.utils.get_twitcher_url(container: magpie.typedefs.AnySettingsContainer | None = None, hostname: magpie.typedefs.Str | None = None) → magpie.typedefs.Str

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

See also

Documentation section Twitcher Settings for available setting combinations.

Parameters:

• container – container that provides access to application settings.

• hostname – override literal hostname to generate the URL instead of resolving using settings.

Returns:

resolved Twitcher URL

magpie.utils.get_twitcher_protected_service_url(magpie_service_name: magpie.typedefs.Str, container: magpie.typedefs.AnySettingsContainer | None = None, hostname: magpie.typedefs.Str | None = None) → magpie.typedefs.Str

Obtains the protected service URL behind Twitcher Proxy based on combination of supported configuration settings.

See also

Documentation section Twitcher Settings for available setting combinations.

Parameters:

• magpie_service_name – name of the service to employ in order to form the URL path behind the proxy.

• container – container that provides access to application settings.

• hostname – override literal hostname to generate the URL instead of resolving using settings.

Returns:

resolved Twitcher Proxy protected service URL

magpie.utils.is_magpie_ui_path(request: pyramid.request.Request) → bool

Determines if the request path corresponds to any Magpie UI location.

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

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

magpie.utils.log_request_format(request: pyramid.request.Request) → magpie.typedefs.Str

magpie.utils.log_request(event: pyramid.events.NewRequest) → None

Subscriber event that logs basic details about the incoming requests.

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

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.utils.is_json_body(body: Any, return_body: bool = False) → bool

class magpie.utils.ExtendedEnum

Bases: enum.Enum

Utility enum.Enum methods.

Create an extended enum with these utilities as follows:

class CustomEnum(ExtendedEnum):
    ItemA = "A"
    ItemB = "B"

property title: magpie.typedefs.Str

Returns the title representation of the enum element.

Title use the original enum element name with capitalization considering underscores for separate words.

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

Returns the member names assigned to corresponding enum elements.

classmethod values() → List[magpie.typedefs.AnyKey]

Returns the literal values assigned to corresponding enum elements.

classmethod get(key_or_value: magpie.typedefs.AnyKey, default: Any | None = None) → _TC | None

Finds an enum entry by defined name or its value.

Returns the entry directly if it is already a valid enum.

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

Returns the title representation of all enum elements.

class magpie.utils.FlexibleNameEnum

Bases: ExtendedEnum

Enum that allows more permissive name cases for lookup.

classmethod _missing_(value)

classmethod __missing_flexible(value)

classmethod get(key_or_value, default=None)

Finds an enum entry by defined name or its value.

Returns the entry directly if it is already a valid enum.

magpie.utils.decompose_enum_flags(enum_flags: enum.Enum) → List[enum.Enum]

Decompose a Flag-enabled Enum into its individual parts.

The operation is agnostic of the Enum implementation, whether from stdlib enum or aenum.

class magpie.utils.SingletonMeta

Bases: type

A metaclass that creates a Singleton base class when called.

Create a class such that:

@six.add_metaclass(SingletonMeta)
class A(object):
    pass

@six.add_metaclass(SingletonMeta)
class B(object):
    pass

a1 = A()
a2 = A()
b1 = B()
b2 = B()
a1 is a2    # True
b1 is b2    # True
a1 is b1    # False

_instances

__call__(*args, **kwargs)

Call self as a function.

class magpie.utils.classproperty

Bases: property

Mimics property decorator, but applied onto classmethod in backward compatible way.

Note

This decorator purposely only supports getter attribute to define unmodifiable class properties.

See also

https://stackoverflow.com/a/5191224

Initialize self. See help(type(self)) for accurate signature.

__get__(cls, owner)

Return an attribute of instance, which is of type owner.