magpie.models

Attributes

_UserType
LOGGER
Base
RESOURCE_TREE_SERVICE
REMOTE_RESOURCE_TREE_SERVICE
RESOURCE_TYPES
RESOURCE_TYPE_DICT

Classes

Permission	Applicable Permission values (names) under certain Service and Resource.
ExtendedEnum	Utility enum.Enum methods.
FlexibleNameEnum	Enum that allows more permissive name cases for lookup.
Group	Mixin for Group model
GroupPermission	Mixin for GroupPermission model
UserGroupStatus	Supported statuses of user-group relationships.
UserGroup	Mixin for UserGroup model
GroupResourcePermission	Mixin for GroupResourcePermission model
Resource	Mixin for Resource model
UserPermission	Mixin for UserPermission model
UserResourcePermission	Mixin for UserResourcePermission model
User	Base mixin for User object representation.
UserPending	Temporary definition of a User pending for approval by an administrator.
UserStatuses	Values applicable to User statues.
UserSearchService	Extends the ziggurat_foundations UserService with additional features provided by Magpie.
ExternalIdentity	Mixin for External Identity model - it represents oAuth(or other) accounts
RootFactory	Used to build base Access Control List (ACL) of the request user.
UserFactory	Used to build base Access Control List (ACL) of the request user.
Service	Resource of service type.
PathBase
File	Resource that represents the leaf node in a file-system-like hierarchy.
Directory	Resource that represents an intermediate directory node within a file-system-like hierarchy.
Layer	Resource that defines multiple corresponding representations of a layer according to the OWS it lies under.
Workspace	Resource employed to contain a group of scoped Layer within a Geoserver instance.
Route	Resource employed to represent a single request path fragment.
Process	Resource that represents a process under an OWS instance servicing a WPS endpoint.
RemoteResource	Basic class that all other classes inherit from that supplies some
RemoteResourcesSyncInfo	Basic class that all other classes inherit from that supplies some
RemoteResourceTreeService
RemoteResourceTreeServicePostgresSQL	This is necessary, because ResourceTreeServicePostgresSQL.model is the Resource class. If we want to change it for a
TokenOperation	Supported operations by the temporary tokens.
TemporaryToken	Model that defines a token for temporary URL completion of a given pending operation.

Functions

get_constant(→ magpie.typedefs.SettingValue)	Search in order for matched value of constant_name:
decompose_enum_flags(→ List[enum.Enum])	Decompose a Flag-enabled Enum into its individual parts.
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_session_callable(→ sqlalchemy.orm.session.Session)
resource_factory(→ Resource)
find_children_by_name(→ Optional[Resource])

Module Contents

magpie.models.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.models.Permission

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'

class magpie.models.ExtendedEnum

Bases: enum.Enum

Utility enum.Enum methods.

Create an extended enum with these utilities as follows:

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

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.

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.

class magpie.models.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.models.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.

magpie.models.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.models.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.models._UserType: magpie.typedefs.TypeAlias = 'User'

magpie.models.LOGGER

magpie.models.Base

magpie.models.get_session_callable(request: pyramid.request.Request) → sqlalchemy.orm.session.Session

class magpie.models.Group

Bases: ziggurat_foundations.models.group.GroupMixin, Base

Mixin for Group model

_priority = None

get_member_count(db_session: sqlalchemy.orm.session.Session | None = None) → int

property discoverable

Indicates if the group is discoverable for users to self-register to it.

property terms

Text containing the terms and conditions.

property priority: magpie.typedefs.GroupPriority

Sorting priority weight of the group for resolving conflicting permissions.

class magpie.models.GroupPermission

Bases: ziggurat_foundations.models.group_permission.GroupPermissionMixin, Base

Mixin for GroupPermission model

class magpie.models.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.

class magpie.models.UserGroup

Bases: ziggurat_foundations.models.user_group.UserGroupMixin, Base

Mixin for UserGroup model

class magpie.models.GroupResourcePermission

Bases: ziggurat_foundations.models.group_resource_permission.GroupResourcePermissionMixin, Base

Mixin for GroupResourcePermission model

class magpie.models.Resource

Bases: ziggurat_foundations.models.resource.ResourceMixin, Base

Mixin for Resource model

resource_type_name: magpie.typedefs.Str = None

permissions: List[magpie.permissions.Permission] = []

child_resource_allowed = True

resource_display_name

property root_service_id

property __acl__: magpie.typedefs.AccessControlListType

User or group that owns a resource are granted full access to it.

__str__()

Return str(self).

class magpie.models.UserPermission

Bases: ziggurat_foundations.models.user_permission.UserPermissionMixin, Base

Mixin for UserPermission model

class magpie.models.UserResourcePermission

Bases: ziggurat_foundations.models.user_resource_permission.UserResourcePermissionMixin, Base

Mixin for UserResourcePermission model

class magpie.models.User

Bases: ziggurat_foundations.models.user.UserMixin, Base

Base mixin for User object representation. It supplies all the basic functionality from password hash generation and matching to utility methods used for querying database for users and their permissions or resources they have access to. It is meant to be extended with other application specific properties

__str__()

Return str(self).

get_groups_by_status(status: UserGroupStatus, db_session: sqlalchemy.orm.session.Session = None) → Set[magpie.typedefs.Str]

List all groups a user belongs to, filtered by UserGroup status type.

class magpie.models.UserPending

Bases: Base

Temporary definition of a User pending for approval by an administrator.

property __tablename__

property id

Unique identifier of user.

property user_name

Unique user name.

property user_password

Password hash of the user.

property email

Email of the user.

property registered_date

Date of user's registration.

property status

Pending user status is enforced.

Avoid error in case the corresponding attribute of User was accessed.

property groups

Pending user is not a member of any group.

Avoid error in case this field gets accessed when simultaneously handling User and :class`UserPending`.

get_groups_by_status(status: UserGroupStatus, db_session: sqlalchemy.orm.session.Session = None) → List[magpie.typedefs.Str]

Pending user is not a member of any group.

Avoid error in case this method gets accessed when simultaneously handling User and :class`UserPending`.

upgrade(db_session: sqlalchemy.orm.session.Session | None = None) → User

Upgrades this :class`UserPending` instance to a complete and corresponding User definition.

Automatically handles instance updates in the database. All relevant User metadata is transferred from available UserPending details.

All operations that should take place during normal User creation will take effect, including minimal Group membership creation and Webhook triggers.

This current UserPending instance is finally removed and should not be accessed following upgrade.

Parameters:

db_session – Database connection to use, otherwise retrieved from the user pending object.

Returns:

created user instance

property passwordmanager

Employ the same password manager attached to :class:`User` instances from :class:`UserService`.

This allows all functionalities of password generation, encryption and comparison to be directly transferable between this pending user until it eventually gets upgraded to a full User once validated.

class magpie.models.UserStatuses

Bases: enum.IntFlag, magpie.utils.FlexibleNameEnum

Values applicable to User statues.

Provides allowed values for the status search query of User and UserPending entries. Also, defines the possible values of User.status field, omitting UserStatuses.Pending reserved for objects defined by UserPending.

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

OK = 1

WebhookError = 2

Pending = 4

classmethod _get_one(status: AnyUserStatus) → UserStatuses | None

classmethod get(status: None | int | magpie.typedefs.Str | UserStatuses | Iterable[None, int, magpie.typedefs.Str, UserStatuses], default: UserStatuses | None = None) → UserStatuses | None

Obtains the combined flag UserStatuses

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

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

classmethod all() → UserStatuses

Representation of all flags combined.

__or__(other: UserStatuses | int) → UserStatuses

Return self|value.

__and__(other: UserStatuses | int) → UserStatuses

Return self&value.

__xor__(other: UserStatuses | int) → UserStatuses

Return self^value.

__iter__() → Iterable[UserStatuses]

__len__()

class magpie.models.UserSearchService

Bases: ziggurat_foundations.models.services.user.UserService

Extends the ziggurat_foundations UserService with additional features provided by Magpie.

Note

For any search result where parameter status is equal to or contains UserStatuses.Pending combined with any other UserStatuses members, or through the all representation, the returned iterable could be a mix of both User models or only UserPending. Therefore, only fields supported by both of those models should be accessed from the result.

classmethod by_status(status: UserStatuses | None = None, db_session: sqlalchemy.orm.session.Session | None = None) → Iterable[AnyUser]

Search for appropriate User and/or UserPending according to specified UserStatuses.

When the status is None, normal retrieval of all non-pending User is executed, as if directly using the UserService implementation. Otherwise, a combination of appropriate search criterion is executed based on the status flags.

classmethod by_user_name(user_name: magpie.typedefs.Str, status: UserStatuses | None = None, db_session: sqlalchemy.orm.session.Session | None = None) → AnyUser | None

Retrieves the user matching the given name.

Search is always accomplished against User table unless UserStatuses.Pending is provided in the status. If more that one status is provided such that both UserPending and User could yield results, the User is returned first, as there should not be any conflict between those two models.

classmethod by_name_or_email(user_name: magpie.typedefs.Str, email: magpie.typedefs.Str, status: UserStatuses | None = None, db_session: sqlalchemy.orm.session.Session | None = None) → AnyUser | None

Retrieves the first matched user by either name or email, whichever comes first.

If the status is provided, search is executed against relevant User and/or :class`UserPending` definitions. The user_name is looked for first across both tables (as needed) and then by email if not previously matched.

See also

by_user_name() by_email() by_email_and_username()

class magpie.models.ExternalIdentity

Bases: ziggurat_foundations.models.external_identity.ExternalIdentityMixin, Base

Mixin for External Identity model - it represents oAuth(or other) accounts attached to your user object

class magpie.models.RootFactory(request: pyramid.request.Request)

Bases: object

Used to build base Access Control List (ACL) of the request user.

All API and UI routes will employ this set of effective principals to determine if the user is authorized to access the pyramid view according to the permission value it was configured with.

Note

Keep in mind that Magpie is configured with default permission magpie.constants.MAGPIE_ADMIN_PERMISSION. Views that require more permissive authorization must be overridden with permission argument.

See also

• set_default_permission within magpie.includeme() initialization steps

__name__ = None

__parent__ = ''

property __acl__: magpie.typedefs.AccessControlListType

Administrators have all permissions, user/group-specific permissions added if user is logged in.

class magpie.models.UserFactory(request: pyramid.request.Request)

Bases: RootFactory

Used to build base Access Control List (ACL) of the request user.

All API and UI routes will employ this set of effective principals to determine if the user is authorized to access the pyramid view according to the permission value it was configured with.

Note

Keep in mind that Magpie is configured with default permission magpie.constants.MAGPIE_ADMIN_PERMISSION. Views that require more permissive authorization must be overridden with permission argument.

See also

• set_default_permission within magpie.includeme() initialization steps

__getitem__(user_name: magpie.typedefs.Str) → UserFactory

property __acl__: magpie.typedefs.AccessControlListType

Grant access to Request User according to its relationship to Context User.

If it is the same user (either from explicit name or by magpie.constants.MAGPIE_LOGGED_USER reserved keyword), allow magpie.constants.MAGPIE_LOGGED_PERMISSION for itself to access corresponding views.

If request user is unauthenticated (None), magpie.constants.MAGPIE_LOGGED_USER or itself, also grant magpie.constants.MAGPIE_CONTEXT_PERMISSION to allow access to contextually-available details (e.g.: user can view his own information and public ones).

All ACL permissions from RootFactory are applied on top of user-specific permissions added here.

class magpie.models.Service

Bases: Resource

Resource of service type.

__tablename__ = 'services'

resource_id

resource_type_name = 'service'

__mapper_args__

property permissions

property url

property type

Identifier matching ``magpie.services.ServiceInterface.service_type``.

property sync_type

Identifier matching ``magpie.cli.SyncServiceInterface.sync_type``.

property configuration

Configuration modifiers for parsing access to resources and permissions.

See also

• magpie.services.ServiceInterface.get_config()

static by_service_name(service_name, db_session)

class magpie.models.PathBase

Bases: object

permissions

class magpie.models.File

Bases: Resource, PathBase

Resource that represents the leaf node in a file-system-like hierarchy.

In the context of THREDDS, this represents the corresponding files exposed by the service. This resource cannot have any children resource under it.

child_resource_allowed = False

resource_type_name = 'file'

__mapper_args__

class magpie.models.Directory

Bases: Resource, PathBase

Resource that represents an intermediate directory node within a file-system-like hierarchy.

In the context of THREDDS, this represents the corresponding directories exposed by the service. Any amount of Directory can be nested under itself to form the tree hierarchy.

resource_type_name = 'directory'

__mapper_args__

class magpie.models.Layer

Bases: Resource

Resource that defines multiple corresponding representations of a layer according to the OWS it lies under.

In the context of WFS, this is the represented collection of features. In the context of WMS, this is the referenced features employed to generate the map.

child_resource_allowed = False

resource_type_name = 'layer'

__mapper_args__

permissions

class magpie.models.Workspace

Bases: Resource

Resource employed to contain a group of scoped Layer within a Geoserver instance.

resource_type_name = 'workspace'

__mapper_args__

permissions

class magpie.models.Route

Bases: Resource

Resource employed to represent a single request path fragment.

resource_type_name = 'route'

__mapper_args__

permissions

class magpie.models.Process

Bases: Resource

Resource that represents a process under an OWS instance servicing a WPS endpoint.

child_resource_allowed = False

resource_type_name = 'process'

__mapper_args__

permissions

class magpie.models.RemoteResource

Bases: ziggurat_foundations.models.base.BaseModel, Base

Basic class that all other classes inherit from that supplies some basic methods useful for interaction with packages like: deform, colander or wtforms

__tablename__ = 'remote_resources'

__possible_permissions__ = ()

_ziggurat_services

resource_id

service_id

parent_id

ordering

resource_name

resource_display_name

resource_type

__repr__()

Return repr(self).

class magpie.models.RemoteResourcesSyncInfo

Bases: ziggurat_foundations.models.base.BaseModel, Base

Basic class that all other classes inherit from that supplies some basic methods useful for interaction with packages like: deform, colander or wtforms

__tablename__ = 'remote_resources_sync_info'

id

service_id

service

remote_resource_id

last_sync

static by_service_id(service_id, session)

__repr__()

Return repr(self).

class magpie.models.RemoteResourceTreeService(service_cls)

Bases: ziggurat_foundations.models.services.resource_tree.ResourceTreeService

class magpie.models.RemoteResourceTreeServicePostgresSQL(service_cls)

Bases: ziggurat_foundations.models.services.resource_tree_postgres.ResourceTreeServicePostgreSQL

This is necessary, because ResourceTreeServicePostgresSQL.model is the Resource class. If we want to change it for a RemoteResource, we need this class.

The ResourceTreeService.__init__ call sets the model.

classmethod build_subtree_strut(result, *args, **kwargs)

Returns a dictionary in form of {node:Resource, children:{node_id: Resource}}.

Parameters:

result

Returns:

class magpie.models.TokenOperation

Bases: magpie.utils.ExtendedEnum

Supported operations by the temporary tokens.

GROUP_ACCEPT_TERMS = 'group-accept-terms'

Temporary token associated to an URL endpoint called by a user that accepts the terms and conditions (T&C) to join a particular group.

USER_PASSWORD_RESET = 'user-password-reset'

Temporary token associated to an URL endpoint to request a user password reset.

USER_REGISTRATION_CONFIRM_EMAIL = 'user-registration-confirm-email'

Temporary token associated to a pending user registration that requires email validation by visiting the link.

USER_REGISTRATION_ADMIN_APPROVE = 'user-registration-admin-approve'

Temporary token associated to a pending user registration that will be approved by an administrator when visited.

USER_REGISTRATION_ADMIN_DECLINE = 'user-registration-admin-decline'

Temporary token associated to a pending user registration that will be declined by an administrator when visited.

WEBHOOK_USER_STATUS_ERROR = 'webhook-user-status-error'

Temporary token employed to provide a callback URL that a registered webhook can call following the triggered event to indicate that the corresponding operation resulted into an invalid user status.

class magpie.models.TemporaryToken(*_, **__)

Bases: ziggurat_foundations.models.base.BaseModel, Base

Model that defines a token for temporary URL completion of a given pending operation.

__tablename__ = 'tmp_tokens'

token

operation

created

user_id

_user

user_pending_id

_pending_user

group_id

group

user() → AnyUser

url(settings: magpie.typedefs.AnySettingsContainer = None) → magpie.typedefs.Str

expired() → bool

static by_token(token: magpie.typedefs.Str | sqlalchemy.dialects.postgresql.UUID, db_session: sqlalchemy.orm.session.Session | None = None) → TemporaryToken | None

static by_user(user: AnyUser, db_session: sqlalchemy.orm.session.Session | None = None) → sqlalchemy.orm.query.Query | None

json() → magpie.typedefs.JSON

magpie.models.RESOURCE_TREE_SERVICE

magpie.models.REMOTE_RESOURCE_TREE_SERVICE

magpie.models.RESOURCE_TYPES

magpie.models.RESOURCE_TYPE_DICT: Dict[magpie.typedefs.Str, Type[Resource]]

magpie.models.resource_factory(**kwargs: Any) → Resource

magpie.models.find_children_by_name(child_name: magpie.typedefs.Str, parent_id: int | None, db_session: sqlalchemy.orm.session.Session) → Resource | None