magpie.api.management.resource.resource_utils ============================================= .. py:module:: magpie.api.management.resource.resource_utils Functions --------- .. autoapisummary:: magpie.api.management.resource.resource_utils.check_valid_service_or_resource_permission magpie.api.management.resource.resource_utils.check_valid_service_resource magpie.api.management.resource.resource_utils.check_unique_child_resource_name magpie.api.management.resource.resource_utils.crop_tree_with_permission magpie.api.management.resource.resource_utils.get_resource_path magpie.api.management.resource.resource_utils.get_service_or_resource_types magpie.api.management.resource.resource_utils.get_resource_parents magpie.api.management.resource.resource_utils.get_resource_children magpie.api.management.resource.resource_utils.get_resource_permissions magpie.api.management.resource.resource_utils.get_resource_root_service magpie.api.management.resource.resource_utils.get_resource_root_service_by_id magpie.api.management.resource.resource_utils.get_resource_root_service_impl magpie.api.management.resource.resource_utils.create_resource magpie.api.management.resource.resource_utils.delete_resource Module Contents --------------- .. py:function:: check_valid_service_or_resource_permission(permission_name: Union[magpie.typedefs.Str, magpie.permissions.Permission], service_or_resource: magpie.typedefs.ServiceOrResourceType, db_session: sqlalchemy.orm.session.Session) -> Optional[magpie.permissions.Permission] Checks if a permission is valid to be applied to a specific `service` or a `resource` under a root service. :param permission_name: permission name to be validated :param service_or_resource: resource item corresponding to either a Service or a Resource :param db_session: db connection :return: valid Permission if allowed by the service/resource :raises HTTPBadRequest: if the permission is not valid for the targeted service/resource .. py:function:: check_valid_service_resource(parent_resource: magpie.typedefs.ServiceOrResourceType, resource_type: magpie.typedefs.Str, db_session: sqlalchemy.orm.session.Session) -> magpie.models.Service Checks if a new Resource can be contained under a parent Resource given the requested type and the corresponding Service under which the parent Resource is already assigned. :param parent_resource: Resource under which the new resource of `resource_type` must be placed :param resource_type: desired resource type :param db_session: :return: root Service if all checks were successful .. py:function:: check_unique_child_resource_name(resource_name: magpie.typedefs.Str, parent_id: int, error_message: magpie.typedefs.Str, db_session: sqlalchemy.orm.session.Session) -> None Verify that resource will be unique amongst other resources at the same target position. Verifies that the provided :paramref:`resource_name` does not already exist amongst other children resources at the level immediately under the parent, for the specified parent resource. :returns: nothing if no conflict detected :raises HTTPConflict: if the :paramref:`resource_name` conflict with another existing resource .. py:function:: crop_tree_with_permission(children: magpie.typedefs.NestedResourceNodes, resource_id_list: List[int]) -> Tuple[magpie.typedefs.NestedResourceNodes, List[int]] Recursively prunes all children resources from the tree hierarchy *except* listed ones matched by ID. Input :paramref:`children` is expected to be a dictionary of resource nodes and children resources with their ID as keys:: { : { "node": , "children": { : { "node": , "children": { <...> } }, <...> }, <...> } :param children: full hierarchy of children resource nodes. :param resource_id_list: resource IDs of nodes to preserve. :return: pruned hierarchy of resource nodes. .. py:function:: get_resource_path(resource_id: int, db_session: sqlalchemy.orm.session.Session) -> magpie.typedefs.Str Obtains the full path representation of the specified resource ID from the root service it resides under using all respective names of the intermediate resources. For example, the following hierarchy:: (id: 1) (id: 2) (id: 3) Will return the following path: ``/service-1/resource-1/resource-2``. This is the same representation of the ``resource`` field within startup permissions configuration file. .. py:function:: get_service_or_resource_types(service_or_resource: magpie.typedefs.ServiceOrResourceType) -> Tuple[Type[magpie.services.ServiceInterface], magpie.typedefs.Str] Obtain the `service` or `resource` class and a corresponding ``"service"`` or ``"resource"`` type identifier. .. py:function:: get_resource_parents(resource: magpie.typedefs.ServiceOrResourceType, db_session: sqlalchemy.orm.session.Session, tree_service_builder: Optional[ziggurat_foundations.models.services.resource_tree.ResourceTreeService] = None) -> List[magpie.typedefs.ServiceOrResourceType] Obtains the parent resource nodes of the input service or resource. :param resource: Initial resource where to start building the list from. :param db_session: Database connection to retrieve resources. :param tree_service_builder: Utility that build the tree (default: :py:data:`models.RESOURCE_TREE_SERVICE`). :returns: List of resources starting at input resource going all the way down to the root service. .. py:function:: get_resource_children(resource: magpie.typedefs.ServiceOrResourceType, db_session: sqlalchemy.orm.session.Session, tree_service_builder: Optional[ziggurat_foundations.models.services.resource_tree.ResourceTreeService] = None, limit_depth: Optional[int] = None) -> magpie.typedefs.NestedResourceNodes Obtains the children resource node structure of the input service or resource. :param resource: Initial resource where to start building the tree from. :param db_session: Database connection to retrieve resources. :param tree_service_builder: Utility that build the tree (default: :py:data:`models.RESOURCE_TREE_SERVICE`). :param limit_depth: Maximum depth to look for children resources (very deep if not specified, could be slow). :returns: ``{node: Resource, children: {node_id: }}`` .. py:function:: get_resource_permissions(resource: magpie.typedefs.ServiceOrResourceType, db_session: sqlalchemy.orm.session.Session) -> List[magpie.permissions.Permission] Obtains the applicable permissions on the service or resource, accordingly to what was provided. When parsing a resource, rewinds the hierarchy up to the top-most service in order to find the context under which the resource resides, and therefore which permissions this resource is allowed to have under that service. .. py:function:: get_resource_root_service(resource: magpie.typedefs.ServiceOrResourceType, db_session: sqlalchemy.orm.session.Session) -> Optional[magpie.models.Service] Retrieves the service-specialized resource corresponding to the top-level resource in the tree hierarchy. .. seealso:: - :func:`get_resource_root_service_by_id` for same operation but using the resource ID - :func:`get_resource_root_service_impl` to retrieve the explicit service's implementation .. py:function:: get_resource_root_service_by_id(resource_id: magpie.typedefs.ServiceOrResourceType, db_session: sqlalchemy.orm.session.Session) -> Optional[magpie.models.Service] Retrieves the service-specialized resource corresponding to the top-level resource in the tree hierarchy. .. seealso:: - :func:`get_resource_root_service` for same operation but directly using the resource .. py:function:: get_resource_root_service_impl(resource: magpie.typedefs.ServiceOrResourceType, request: pyramid.request.Request) -> magpie.services.ServiceInterface Obtain the root service implementation. Retrieves the root-resource from the provided resource within a tree hierarchy and generates the corresponding top-level service's implementation from the :func:`service_factory`. .. seealso:: :func:`get_resource_root_service` to retrieve only the service flavored resource model .. py:function:: create_resource(resource_name: magpie.typedefs.Str, resource_display_name: Optional[magpie.typedefs.Str], resource_type: magpie.typedefs.Str, parent_id: int, db_session: sqlalchemy.orm.session.Session) -> pyramid.httpexceptions.HTTPException .. py:function:: delete_resource(request)