magpie.register¶

Exceptions¶

`RegistrationError`	Generic error during registration operation.
`RegistrationValueError`	Registration error caused by an invalid value precondition.
`RegistrationLoginError`	Registration error caused by a failure to complete required login operation.
`RegistrationConfigurationError`	Registration error caused by an invalid configuration entry or definition.

Classes¶

`Permission`	Applicable Permission values (names) under certain Service and Resource.
`PermissionSet`	Explicit definition of a `Permission` with applicable `Access` and `Scope` to resolve it.
`ServiceWPS`	Service that represents a `Web Processing Service` endpoint.

Functions¶

`validate_services_config`(→ magpie.typedefs.ServicesConfig)	Validate configuration within the `providers` section.
`get_constant`(→ magpie.typedefs.SettingValue)	Search in order for matched value of `constant_name`:
`bool2str`(→ magpie.typedefs.Str)	Converts `value` to explicit `"true"` or `"false"` `str` with permissive variants comparison
`get_admin_cookies`(→ magpie.typedefs.CookiesType)
`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.
`get_phoenix_url`(→ magpie.typedefs.Str)	Obtains the configured Phoenix URL entrypoint based on the 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.
`islambda`(→ bool)	Evaluate if argument is a callable `lambda` expression.
`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.
`_login_loop`(login_url, cookies_file[, data, message])
`_request_curl`(→ Tuple[int, int])	Executes a request using cURL.
`_phoenix_update_services`(→ bool)
`_phoenix_login`(→ bool)	Performs Phoenix login using provided cookies.
`_phoenix_login_check`(→ bool)	Since Phoenix always return 200, even on invalid login, 'hack' check unauthorized access.
`_phoenix_remove_services`(→ bool)	Removes the Phoenix services using temporary cookies retrieved from login with defined PHOENIX constants.
`_phoenix_register_services`(→ Tuple[bool, ...)
`_register_services`(→ Tuple[bool, ...)	Registers services on desired location using provided configurations and access cookies.
`sync_services_phoenix`(→ bool)	Syncs Magpie services by pushing updates to Phoenix.
`_magpie_add_register_services_perms`(→ None)
`_magpie_update_services_conflict`(...)	Resolve conflicting services by name during registration by updating them only if pointing to different URL.
`_magpie_register_services_with_requests`(→ bool)	Registers Services of loaded `providers` configuration using API requests.
`_magpie_register_services_with_db_session`(→ bool)	Registration procedure of Services from `providers` section using pre-established database session.
`_load_config`(→ Union)	Loads a YAML/JSON file path or pre-loaded dictionary configuration.
`get_all_configs`(…)	Loads all matched configurations.
`_expand_all`(→ magpie.typedefs.JSON)	Applies environment variable expansion recursively to all applicable fields of a configuration definition.
`magpie_register_services_from_config`(...)	Registers Magpie services from one or many providers.cfg file.
`_handle_permission`(→ None)	Logs a message related to a 'permission' entry and raises an error if required.
`_use_request`(cookies_or_session)
`_parse_resource_path`(→ Tuple[Optional[int], bool])	Parses the resource field of a permission config entry and retrieves the final resource id. Creates missing
`_apply_permission_entry`(→ None)	Applies the single permission entry retrieved from the permission configuration.
`magpie_register_permissions_from_config`(→ None)	Applies permissions specified in configuration(s) defined as file, directory with files or literal configuration.
`_resolve_config_registry`(...)	Converts a list of configurations entries from multiple files into a single resolved mapping.
`_process_permissions`(→ None)	Processes a single permissions configuration.
`pseudo_random_string`(→ magpie.typedefs.Str)	Generate a string made of random characters.

Module Contents¶

magpie.register.GroupResourcePermissionsAPI[source]¶

magpie.register.GroupsAPI[source]¶

magpie.register.ServiceAPI[source]¶

magpie.register.ServiceResourcesAPI[source]¶

magpie.register.ServicesAPI[source]¶

magpie.register.SigninAPI[source]¶

magpie.register.SignoutAPI[source]¶

magpie.register.UserResourcePermissionsAPI[source]¶

magpie.register.UsersAPI[source]¶

magpie.register.validate_services_config(services_configuration: magpie.typedefs.JSON) → magpie.typedefs.ServicesConfig[source]¶

Validate configuration within the providers section.

Parameters:: services_configuration – Service definitions loaded from one or more combined configuration files.
Returns:: Services configuration with validated schema and applied defaults.

magpie.register.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:

search in MAGPIE_CONSTANTS
search in settings if specified
search alternative setting names (see below)
search in magpie.constants definitions
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.register.Permission[source]¶

Bases: magpie.utils.ExtendedEnum

Applicable Permission values (names) under certain Service and Resource.

READ = 'read'¶

WRITE = 'write'¶

ACCESS = 'access'¶

BROWSE = 'browse'¶

GET_CAPABILITIES = 'getcapabilities'¶

GET_MAP = 'getmap'¶

GET_FEATURE_INFO = 'getfeatureinfo'¶

GET_LEGEND_GRAPHIC = 'getlegendgraphic'¶

GET_METADATA = 'getmetadata'¶

GET_PROPERTY_VALUE = 'getpropertyvalue'¶

GET_FEATURE = 'getfeature'¶

GET_FEATURE_WITH_LOCK = 'getfeaturewithlock'¶

GET_GML_OBJECT = 'getgmlobject'¶

DESCRIBE_FEATURE_TYPE = 'describefeaturetype'¶

DESCRIBE_LAYER = 'describelayer'¶

DESCRIBE_PROCESS = 'describeprocess'¶

EXECUTE = 'execute'¶

LOCK_FEATURE = 'lockfeature'¶

TRANSACTION = 'transaction'¶

CREATE_STORED_QUERY = 'createstoredquery'¶

DROP_STORED_QUERY = 'dropstoredquery'¶

LIST_STORED_QUERIES = 'liststoredqueries'¶

DESCRIBE_STORED_QUERIES = 'describestoredqueries'¶

Bases: object

Explicit definition of a Permission with applicable Access and Scope to resolve it.

The Permission is the name of the applicable permission on the magpie.models.Resource. The Scope defines how the Permission should impact the resolution of the perceived Effective Permissions over a magpie.models.Resource tree hierarchy. The Access defines how the Permission access should be interpreted (granted or denied).

Optionally, a PermissionType can be provided to specifically indicate which kind of permission this set represents. This type is only for informative purposes, and is not saved to database nor displayed by the explicit string representation. It is returned within JSON representation and can be employed by Effective Permissions resolution to be more verbose about returned results.

On missing Access or Scope specifications, they default to Access.ALLOW and Scope.RECURSIVE to handle backward compatible naming convention of plain permission_name.

Initializes the permission definition, possibly using required conversion from other implementations.

Parameters:

permission – Name of the permission, or any other implementation from which the name can be inferred.
access – Effective behaviour of the permissions. Generally, grant or deny the specified permission.
scope – Scope for which the permission affects hierarchical resources. Important for effective resolution.
typ – Type of permission being represented. Informative only, does not impact behavior if omitted.
reason – Slightly more indicative information on why the current permission-type has this value. Value should be either explicitly provided or will be inferred if converted from input PermissionTuple.

See also

PermissionSet._convert()

__slots__ = ['_name', '_access', '_scope', '_tuple', '_type', '_reason']¶

__eq__(other: Any) → bool[source]¶: Return self==value.

__ne__(other: Any) → bool[source]¶: Return self!=value.

__lt__(other: Any) → bool[source]¶

Ascending sort of permission according to their name, access and scope modifiers.

First sort by permission name alphabetically, followed by increasing restrictive access and increasing range of scoped resources.

Using this sorting methodology, similar permissions by name are grouped together first, and permissions of same name with modifiers are then ordered, the first having less priority when selecting a single item to display with conflicting possibilities. Respecting Access.DENY is more important than Access.ALLOW (to protect the Resource), and Scope.MATCH is closer to the actual Resource than Scope.RECURSIVE permission received from a farther parent in the hierarchy.

Sorted explicit string representation becomes:

[name1]-[allow]-[match]
[name1]-[allow]-[recursive]
[name1]-[deny]-[match]
[name1]-[deny]-[recursive]
[name2]-[allow]-[match]
[name2]-[allow]-[recursive]
[name2]-[deny]-[match]
[name2]-[deny]-[recursive]
...

We then obtain two crucial ordering results:

We can easily pick the last sorted item with highest resolution priority to find the final result of corresponding permissions. (note: final result for same user or group, their direct/inherited resolution is not considered here).
Picking the first element with lowest priority also displays the permission that impacts the widest range of resources. For instance in Magpie UI, indicating that a permission as Scope.RECURSIVE is more verbose as it tell other resources under it are also receive the specified Access modifier rather than only the punctual resource.

Warning

Alphabetically sorting permissions by string representation (implicit/explicit) is not equivalent to sorting them according to Permission priority according to how modifiers are resolved. To obtain the prioritized sorting as strings, a list of PermissionSet (with the strings as input) should be used to convert and correctly interpreted the raw strings, and then be converted back after sorting.

# valid priority-sorted strings
[str(perm) for perm in sorted(PermissionSet(p) for p in permission_strings)]

# not equivalent to raw sorting
list(sorted(permission_strings))

__hash__() → int[source]¶: Return hash(self).

__str__() → magpie.typedefs.Str[source]¶

Obtains the compound literal representation of the PermissionSet.

Employed for database storage supporting ziggurat format.

__repr__() → magpie.typedefs.Str[source]¶: Obtains the visual representation of the PermissionSet.

like(other: Any) → bool[source]¶

Evaluates if one permission is similar to another permission definition regardless of modifiers.

This is different than == operator which will evaluate exactly equal permission definitions.

json() → magpie.typedefs.PermissionDict[source]¶: Obtains the JSON representation of this PermissionSet.

webhook_params() → magpie.typedefs.JSON[source]¶: Obtain JSON representation employed for Webhook reference.

ace(user_or_group: magpie.models.User | magpie.models.Group | None) → magpie.typedefs.AccessControlEntryType[source]¶: Converts the PermissionSet into an ACE that pyramid can understand.

property reason: magpie.typedefs.Str | None¶

Indicative reason of the returned value defined by type() or inferred by the PermissionTuple.

See also

combine()

Returns:: Single string that describes the reason (source) of the permission, or multiple strings if updated by combination of multiple permissions.

classmethod resolve(permission1: magpie.typedefs.ResolvablePermissionType, permission2: magpie.typedefs.ResolvablePermissionType, context: PermissionType = PermissionType.INHERITED, multiple_choice: magpie.typedefs.Str | None = None) → magpie.typedefs.ResolvablePermissionType[source]¶

Resolves provided permissions into a single one considering various modifiers and groups for a resource.

Permissions MUST have the same Permission name. The associated Resource on which the two compared permissions are applied on should also be the same This method SHOULD NOT be used by itself to obtain for Effective Permission since it does not handle multi-level Resource resolution. Resolution is accomplished in this case only for a given level in the tree hierarchy.

The comparison considers both the Access and Scope of every Inherited Permission of the User, as well as its Group memberships sorted by their priority.

See also

magpie.services.ServiceInterface.effective_permissions()
magpie.api.management.user.user_utils.combine_user_group_permissions()
PermissionSet.__lt__()

Parameters:

permission1 – Permission to compare.
permission2 – Permission to compare.
context – Control the resolution context (local/effective) of the permissions (safeguard against invalid definitions).
multiple_choice – Alternate explanation to default PERMISSION_REASON_MULTIPLE applied if multiple Permission refer to distinct Group of equal priority and equivalent access definitions, meaning they are interchangeable without impacting resolution to access the same target Resource.

Returns:

Permission with highest priority to resolve access a resource without considering scope.

property group_priority: magpie.typedefs.GroupPriority | None¶: Priority accessor in case of group inherited permission resolved by PermissionTuple.

property perm_tuple: ziggurat_foundations.permissions.PermissionTuple | None¶: Get the original PermissionTuple if available (PermissionSet must have been created by one).

property implicit_permission: magpie.typedefs.Str | None¶

Obtain the implicit string representation of the PermissionSet as plain Permission name.

This representation is backward compatible with prior versions of Magpie where explicit representation of permission names in the database did not exist.

If the contained modifiers of the PermissionSet (notably the Access.DENY) result in a string representation that is not possible according to non existing permissions for older Magpie instances, the returned value will be None.

See also

explicit_permission() for the new representation.

property explicit_permission: magpie.typedefs.Str¶

Obtain the explicit string representation of the PermissionSet.

This format is always guaranteed to be completely defined contrary to implicit_permission().

See also

__str__() (default string value).
implicit_permission() for the old representation.

property name: Permission¶

permission¶

property access: Access¶

property scope: Scope¶

property type: PermissionType | None¶

classmethod _convert(permission: magpie.typedefs.AnyPermissionType) → PermissionSet | None[source]¶

Converts any permission representation to the PermissionSet with applicable enum members.

Supports older Permission representation such that implicit conversion of permission name without access and scope values are padded with defaults. Also, pre-defined partial or full definition from literal string representation are parsed to generate the PermissionSet instance.

Parameters:: permission – implicit or explicit permission name string, or any other known permission implementation
Raises:: ValueError – when the permission name cannot be identified or parsed

magpie.register.SERVICE_TYPE_DICT[source]¶

class magpie.register.ServiceWPS(service: magpie.models.Service, request: pyramid.request.Request)[source]¶

Bases: ServiceOWS

Service that represents a Web Processing Service endpoint.

Initialize the service.

Parameters:

service – Base service resource that must be handled by this service implementation.
request – Active request to handle requested resources, permissions and effective access. The request can be omitted if basic service definition details are to be retrieved. It is mandatory for any requested or effective component that should be resolved.

service_type = 'wps'¶

permissions¶

params_expected = ['service', 'request', 'version', 'identifier']¶

resource_types_permissions¶

resource_requested() → Tuple[magpie.typedefs.ServiceOrResourceType, bool] | None[source]¶

Defines how to interpret the incoming request into the targeted model.Resource for the given service.

Each service must implement its own definition.

The expected return value must be either of the following:

- List<(target-resource, target?)>  When multiple resources need validation ('target?' as below for each).
- (target-resource, True)           when the exact resource is found according to request parsing.
- (parent-resource, False)          when any parent of the resource is found according to request parsing.
- None                              when invalid request or not found resource.

The parent-resource should indicate the closest higher-level resource in the hierarchy that would nest the otherwise desired target-resource. The idea behind this is that Magpie will be able to resolve the effective recursive scoped permission even if not all corresponding resources were explicitly defined in the database.

For example, if the request would be interpreted with the following hierarchy after service-specific resolution:

ServiceA
    Resource1         <== closest *existing* parent resource
        [Resource2]   <== target (according to service/request resolution), but not existing in database

A permission defined as Allow/Recursive on Resource1 should normally allow access to Resource2. If Resource2 is not present in the database though, it cannot be looked for, and the corresponding ACL cannot be generated. Because the (real) protected service using Magpie can have a large and dynamic hierarchy, it is not convenient to enforce perpetual sync between it and its resource representation in Magpie. Using (parent-resource, False) will allow resolution of permission from the closest available parent.

Note

In case of parent-resource returned, only recursive-scoped permissions will be considered, since the missing target-resource is the only one that should be checked for match-scoped permissions. For this reason, the service-specific implementation should preferably return the explicit target resource whenever possible.

If the returned resource is None, the ACL will effectively be resolved to denied access. This can be used to indicate failure to retrieve the expected resource or that corresponding resource does not exist. Otherwise, this method implementation should convert any request path, query parameters, etc. into an existing resource.

If a list of (target-resource, target?) is returned, all of those resources should individually perform Effective Resolution and should ALL simultaneously be granted access to let the request through. This can be used to resolve ambiguous or equivalent parameter combinations from parsing the request, or to validate access to parameters that allow multi-resource references using some kind of list value representation.

See also

_get_acl() for Effective Resolution of over multiple Resource references.
effective_permissions() for Effective Resolution of a single Resource.

Returns:: One or many tuple of reference resource (target/parent), and explicit match status of the corresponding resource (True/False)

magpie.register.bool2str(value: Any) → magpie.typedefs.Str[source]¶: Converts value to explicit "true" or "false" str with permissive variants comparison that can represent common falsy or truthy values.

magpie.register.get_admin_cookies(container: magpie.typedefs.AnySettingsContainer, verify: bool = True, raise_message: magpie.typedefs.Str | None = None) → magpie.typedefs.CookiesType[source]¶

magpie.register.get_json(request_or_response: magpie.typedefs.AnyRequestType | magpie.typedefs.AnyResponseType) → magpie.typedefs.JSON[source]¶: Retrieves the ‘JSON’ body of a response using the property/callable according to the response’s implementation.

magpie.register.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.register.get_magpie_url(container: magpie.typedefs.AnySettingsContainer | None = None) → magpie.typedefs.Str[source]¶

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.register.get_phoenix_url(container: magpie.typedefs.AnySettingsContainer | None = None) → magpie.typedefs.Str[source]¶

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.register.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[source]¶

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.register.islambda(func: Any) → bool[source]¶: Evaluate if argument is a callable lambda expression.

magpie.register.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.register.raise_log(msg: magpie.typedefs.Str, exception: Type[Exception] = Exception, logger: logging.Logger | None = None, level: int = logging.ERROR) → NoReturn[source]¶

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

Raises:: exception – whichever exception provided is raised systematically after logging.

magpie.register.LOGGER[source]¶

magpie.register.LOGIN_ATTEMPT = 5[source]¶

magpie.register.LOGIN_TIMEOUT = 2[source]¶

magpie.register.CREATE_SERVICE_INTERVAL = 2[source]¶

magpie.register.GETCAPABILITIES_INTERVAL = 10[source]¶

magpie.register.GETCAPABILITIES_ATTEMPTS = 12[source]¶

magpie.register.SERVICES_MAGPIE = 'MAGPIE'[source]¶

magpie.register.SERVICES_PHOENIX = 'PHOENIX'[source]¶

magpie.register.SERVICES_PHOENIX_ALLOWED[source]¶

exception magpie.register.RegistrationError[source]¶

Bases: RuntimeError

Generic error during registration operation.

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

exception magpie.register.RegistrationValueError[source]¶

Bases: RegistrationError, ValueError

Registration error caused by an invalid value precondition.

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

exception magpie.register.RegistrationLoginError[source]¶

Bases: RegistrationError

Registration error caused by a failure to complete required login operation.

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

exception magpie.register.RegistrationConfigurationError[source]¶

Bases: RegistrationValueError

Registration error caused by an invalid configuration entry or definition.

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

magpie.register._login_loop(login_url, cookies_file, data=None, message='Login response')[source]¶

magpie.register._request_curl(url: magpie.typedefs.Str, cookie_jar: magpie.typedefs.Str | None = None, cookies: magpie.typedefs.Str | None = None, form_params: magpie.typedefs.Str | None = None, msg: magpie.typedefs.Str | None = 'Response') → Tuple[int, int][source]¶

Executes a request using cURL.

Returns:: tuple of the returned system command code and the response http code

magpie.register._phoenix_update_services(services_dict: magpie.typedefs.JSON) → bool[source]¶

magpie.register._phoenix_login(cookies_file: magpie.typedefs.Str) → bool[source]¶: Performs Phoenix login using provided cookies.

magpie.register._phoenix_login_check(cookies: magpie.typedefs.Str) → bool[source]¶

Since Phoenix always return 200, even on invalid login, ‘hack’ check unauthorized access.

Parameters:: cookies – temporary cookies file storage used for login with _phoenix_login().
Returns:: status indicating if login access was granted with defined credentials.

magpie.register._phoenix_remove_services() → bool[source]¶

Removes the Phoenix services using temporary cookies retrieved from login with defined PHOENIX constants.

Returns:: success status of the procedure.

magpie.register._phoenix_register_services(services_dict: Dict[magpie.typedefs.Str, Dict[magpie.typedefs.Str, Any]], allowed_service_types: List[magpie.typedefs.Str] | None = None) → Tuple[bool, Dict[magpie.typedefs.Str, int]][source]¶

magpie.register._register_services(where: magpie.typedefs.Str | None, services_dict: Dict[magpie.typedefs.Str, Dict[magpie.typedefs.Str, magpie.typedefs.Str]], cookies: magpie.typedefs.Str, message: magpie.typedefs.Str | None = 'Register response') → Tuple[bool, Dict[magpie.typedefs.Str, int]][source]¶

Registers services on desired location using provided configurations and access cookies.

Returns:: tuple of overall success and individual http response of each service registration.

magpie.register.sync_services_phoenix(services: Iterable[magpie.models.Service] | magpie.typedefs.JSON, services_as_dicts: bool = False) → bool[source]¶

Syncs Magpie services by pushing updates to Phoenix.

Services must be one of types specified in magpie.register.SERVICES_PHOENIX_ALLOWED.

Parameters:

services –
An iterable of models.Service by default, or a dictionary of {svc-name: {<service-info>}} JSON objects containing each service’s information if services_ad_dicts is True.

where <service-info> is defined as:
```
{"public_url": <url>, "service_name": <name>, "service_type": <type>}
```
services_as_dicts – indicate if services must be parsed as JSON definitions.

magpie.register._magpie_add_register_services_perms(services: magpie.typedefs.ServicesSettings, statuses: Dict[magpie.typedefs.Str, int], curl_cookies: str, request_cookies: magpie.typedefs.AnyCookiesType, disable_getcapabilities: bool) → None[source]¶

magpie.register._magpie_update_services_conflict(conflict_services: List[magpie.typedefs.Str], services_dict: magpie.typedefs.ServicesSettings, request_cookies: magpie.typedefs.AnyCookiesType) → Dict[magpie.typedefs.Str, int][source]¶: Resolve conflicting services by name during registration by updating them only if pointing to different URL.

magpie.register._magpie_register_services_with_requests(services_dict: magpie.typedefs.ServicesSettings, push_to_phoenix: bool, username: magpie.typedefs.Str, password: magpie.typedefs.Str, provider: magpie.typedefs.Str, force_update: bool = False, disable_getcapabilities: bool = False) → bool[source]¶

Registers Services of loaded providers configuration using API requests.

Parameters:

services_dict – services configuration definition.
push_to_phoenix – push registered Magpie services to Phoenix for synced configurations.
username – login username to use to obtain permissions for services registration.
password – login password to use to obtain permissions for services registration.
provider – login provider to use to obtain permissions for services registration.
force_update – override existing services matched by name
disable_getcapabilities – do not execute ‘GetCapabilities’ validation for applicable services.

Returns:

successful operation status

magpie.register._magpie_register_services_with_db_session(services_dict: magpie.typedefs.ServicesSettings, db_session: sqlalchemy.orm.session.Session, push_to_phoenix: bool = False, force_update: bool = False, update_getcapabilities_permissions: bool = False) → bool[source]¶: Registration procedure of Services from providers section using pre-established database session.

See also

magpie_register_services_from_config()

magpie.register._load_config(path_or_dict: magpie.typedefs.Str | magpie.typedefs.CombinedConfig, section: magpie.typedefs.Str, allow_missing: bool = False) → Union[source]¶: Loads a YAML/JSON file path or pre-loaded dictionary configuration.

magpie.register.CONFIG_KNOWN_EXTENSIONS[source]¶

magpie.register.get_all_configs(path_or_dict: magpie.typedefs.Str | magpie.typedefs.CombinedConfig, section: magpie.typedefs.Literal[groups], allow_missing: bool = False) → magpie.typedefs.GroupsConfig[source]¶

magpie.register.get_all_configs(path_or_dict: magpie.typedefs.Str | magpie.typedefs.CombinedConfig, section: magpie.typedefs.Literal[users], allow_missing: bool = False) → magpie.typedefs.UsersConfig

magpie.register.get_all_configs(path_or_dict: magpie.typedefs.Str | magpie.typedefs.CombinedConfig, section: magpie.typedefs.Literal[permissions], allow_missing: bool = False) → magpie.typedefs.PermissionsConfig

magpie.register.get_all_configs(path_or_dict: magpie.typedefs.Str | magpie.typedefs.CombinedConfig, section: magpie.typedefs.Literal[services], allow_missing: bool = False) → magpie.typedefs.ServicesConfig

magpie.register.get_all_configs(path_or_dict: magpie.typedefs.Str | magpie.typedefs.CombinedConfig, section: magpie.typedefs.Literal[webhooks], allow_missing: bool = False) → magpie.typedefs.WebhooksConfig

Loads all matched configurations.

Configurations are considered a valid match if they have one of the CONFIG_KNOWN_EXTENSIONS (if path) and that loaded (or passed) configurations contain the specified section name.

If the input is a directory path, loads any number of files contained in it that fulfill matching conditions. If it is a path pointing to a single valid configuration file, loads it by itself. If a dictionary is passed, returns it directly if it fulfills validation.

Parameters:

path_or_dict – directory path, file path or literal dictionary.
section – section name that must be inside every matched configuration file to be loaded.
allow_missing – allow to have no valid configuration after all are resolved, otherwise raises.

Raises:

RegistrationError – when no valid configuration can be found and empty one is not allowed.

Returns:

list of configurations loaded if input was a directory path
list of single configuration if input was a file path
list of single configuration if input was a JSON dict
empty list if none of the other cases where matched

Note

Order of file loading will be resolved by alphabetically sorted filename if specifying a directory path.

magpie.register._expand_all(config: magpie.typedefs.JSON) → magpie.typedefs.JSON[source]¶: Applies environment variable expansion recursively to all applicable fields of a configuration definition.

magpie.register.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.register._handle_permission(message: magpie.typedefs.Str, permission_index: int, trail: magpie.typedefs.Str = ', skipping...', detail: magpie.typedefs.Str | None = None, permission: magpie.typedefs.Str | None = None, level: magpie.typedefs.Str | int = logging.WARN, raise_errors: bool = False) → None[source]¶

Logs a message related to a ‘permission’ entry and raises an error if required.

Log message format is as follows (detail portion omitted if none provided):

{message} [permission: #{permission_index}] [{permission}]{trail}
Detail: [{detail}]

Such that the following logging entry is generated (omitting any additional logging formatters):

>> log_permission("test", 1, " skip test...", "just a test", "fake")
test [permission: #1] [fake] skip test...
Detail: [just a test]

Parameters:

message – base message to log
permission_index – index of the permission in the configuration list for traceability
trail – trailing message appended after the base message
detail – additional details appended after the trailing message after moving to another line.
permission – permission name to log just before the trailing message.
level – logging level (default: logging.WARN)
raise_errors – raises errors related to permissions, instead of just logging the info.

See also

magpie/config/permissions.cfg

magpie.register._use_request(cookies_or_session)[source]¶

magpie.register._parse_resource_path(permission_config_entry: magpie.typedefs.PermissionConfigItem, entry_index: int, service_info: magpie.typedefs.JSON, cookies_or_session: magpie.typedefs.CookiesOrSessionType = None, magpie_url: magpie.typedefs.Str | None = None, raise_errors: bool = False) → Tuple[int | None, bool][source]¶

Parses the resource field of a permission config entry and retrieves the final resource id. Creates missing resources as necessary if they can be automatically resolved.

If cookies are provided, uses requests to a running Magpie instance (with magpie_url) to apply permission. If session to db is provided, uses direct db connection instead to apply permission.

Returns:: tuple of found id (if any, None otherwise), and success status of the parsing operation (error)

magpie.register._apply_permission_entry(permission_config_entry: magpie.typedefs.PermissionConfigItem, entry_index: int, resource_id: int, cookies_or_session: magpie.typedefs.CookiesOrSessionType, magpie_url: magpie.typedefs.Str, users: magpie.typedefs.UsersSettings, groups: magpie.typedefs.GroupsSettings, raise_errors: bool = False) → None[source]¶

Applies the single permission entry retrieved from the permission configuration.

Assumes that permissions fields where pre-validated. Permission is applied for the user/group/resource using request or db session accordingly to arguments.

magpie.register.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.register._resolve_config_registry(config_files: magpie.typedefs.MultiConfigs | None, key: magpie.typedefs.Str) → magpie.typedefs.AnyResolvedSettings[source]¶

Converts a list of configurations entries from multiple files into a single resolved mapping.

Resolution is accomplished against key to generate the mapping of unique items. First configuration entries have priority over later ones if keys are duplicated.

magpie.register._process_permissions(permissions: magpie.typedefs.PermissionsConfig, magpie_url: magpie.typedefs.Str, cookies_or_session: sqlalchemy.orm.session.Session, users: magpie.typedefs.UsersSettings | None = None, groups: magpie.typedefs.GroupsSettings | None = None, settings: magpie.typedefs.AnySettingsContainer | None = None, raise_errors: bool = False) → None[source]¶: Processes a single permissions configuration.

magpie.register.pseudo_random_string(length: int = 8, allow_chars: magpie.typedefs.Str = string.ascii_letters + string.digits) → magpie.typedefs.Str[source]¶: Generate a string made of random characters.

`GroupResourcePermissionsAPI`
`GroupsAPI`
`ServiceAPI`
`ServiceResourcesAPI`
`ServicesAPI`
`SigninAPI`
`SignoutAPI`
`UserResourcePermissionsAPI`
`UsersAPI`
`SERVICE_TYPE_DICT`
`LOGGER`
`LOGIN_ATTEMPT`
`LOGIN_TIMEOUT`
`CREATE_SERVICE_INTERVAL`
`GETCAPABILITIES_INTERVAL`
`GETCAPABILITIES_ATTEMPTS`
`SERVICES_MAGPIE`
`SERVICES_PHOENIX`
`SERVICES_PHOENIX_ALLOWED`
`CONFIG_KNOWN_EXTENSIONS`

magpie.register¶

Attributes¶

Exceptions¶

Classes¶

Functions¶

Module Contents¶

Table of Contents

Previous topic

Next topic

This Page