Source code for galaxy.webapps.galaxy.api.folders

"""
API operations on library folders.
"""

import logging
from typing import (
    Optional,
    Union,
)

from fastapi import (
    Body,
    Path,
    Query,
)
from typing_extensions import Annotated

from galaxy.managers.context import ProvidesUserContext
from galaxy.schema.fields import LibraryFolderDatabaseIdField
from galaxy.schema.schema import (
    CreateLibraryFolderPayload,
    LibraryAvailablePermissions,
    LibraryFolderCurrentPermissions,
    LibraryFolderDetails,
    LibraryFolderPermissionAction,
    LibraryFolderPermissionsPayload,
    LibraryPermissionScope,
    UpdateLibraryFolderPayload,
)
from galaxy.webapps.galaxy.api import (
    depends,
    DependsOnTrans,
    Router,
)
from galaxy.webapps.galaxy.services.library_folders import LibraryFoldersService

log = logging.getLogger(__name__)

router = Router(tags=["data libraries folders"])

FolderIdPathParam = Annotated[
    LibraryFolderDatabaseIdField,
    Path(..., title="Folder ID", description="The encoded identifier of the library folder."),
]

UndeleteQueryParam = Annotated[
    Optional[bool], Query(title="Undelete", description="Whether to restore a deleted library folder.")
]


[docs]@router.cbv
class FastAPILibraryFolders:
    service: LibraryFoldersService = depends(LibraryFoldersService)

[docs]    @router.get(
        "/api/folders/{id}",
        summary="Displays information about a particular library folder.",
    )
    def show(
        self,
        id: FolderIdPathParam,
        trans: ProvidesUserContext = DependsOnTrans,
    ) -> LibraryFolderDetails:
        """Returns detailed information about the library folder with the given ID."""
        return self.service.show(trans, id)

[docs]    @router.post(
        "/api/folders/{id}",
        summary="Create a new library folder underneath the one specified by the ID.",
    )
    def create(
        self,
        id: FolderIdPathParam,
        trans: ProvidesUserContext = DependsOnTrans,
        payload: CreateLibraryFolderPayload = Body(...),
    ) -> LibraryFolderDetails:
        """Returns detailed information about the newly created library folder."""
        return self.service.create(trans, id, payload)

[docs]    @router.put(
        "/api/folders/{id}",
        summary="Updates the information of an existing library folder.",
    )
    @router.patch("/api/folders/{id}")
    def update(
        self,
        id: FolderIdPathParam,
        trans: ProvidesUserContext = DependsOnTrans,
        payload: UpdateLibraryFolderPayload = Body(...),
    ) -> LibraryFolderDetails:
        """Updates the information of an existing library folder."""
        return self.service.update(trans, id, payload)

[docs]    @router.delete(
        "/api/folders/{id}",
        summary="Marks the specified library folder as deleted (or undeleted).",
    )
    def delete(
        self,
        id: FolderIdPathParam,
        undelete: UndeleteQueryParam = None,
        trans: ProvidesUserContext = DependsOnTrans,
    ) -> LibraryFolderDetails:
        """Marks the specified library folder as deleted (or undeleted)."""
        return self.service.delete(trans, id, undelete)

[docs]    @router.get(
        "/api/folders/{id}/permissions",
        summary="Gets the current or available permissions of a particular library folder.",
    )
    def get_permissions(
        self,
        id: FolderIdPathParam,
        trans: ProvidesUserContext = DependsOnTrans,
        scope: Optional[LibraryPermissionScope] = Query(
            None,
            title="Scope",
            description="The scope of the permissions to retrieve. Either the `current` permissions or the `available`.",
        ),
        page: int = Query(
            default=1, title="Page", description="The page number to retrieve when paginating the available roles."
        ),
        page_limit: int = Query(
            default=10, title="Page Limit", description="The maximum number of permissions per page when paginating."
        ),
        q: Optional[str] = Query(
            None, title="Query", description="Optional search text to retrieve only the roles matching this query."
        ),
    ) -> Union[LibraryFolderCurrentPermissions, LibraryAvailablePermissions]:
        """Gets the current or available permissions of a particular library.
        The results can be paginated and additionally filtered by a query."""
        return self.service.get_permissions(
            trans,
            id,
            scope,
            page,
            page_limit,
            q,
        )

[docs]    @router.post(
        "/api/folders/{id}/permissions",
        summary="Sets the permissions to manage a library folder.",
    )
    def set_permissions(
        self,
        id: FolderIdPathParam,
        trans: ProvidesUserContext = DependsOnTrans,
        action: Optional[LibraryFolderPermissionAction] = Query(
            default=None,
            title="Action",
            description=(
                "Indicates what action should be performed on the Library. "
                f"Currently only `{LibraryFolderPermissionAction.set_permissions.value}` is supported."
            ),
        ),
        payload: LibraryFolderPermissionsPayload = Body(...),
    ) -> LibraryFolderCurrentPermissions:
        """Sets the permissions to manage a library folder."""
        payload_dict = payload.model_dump(by_alias=True)
        if isinstance(payload, LibraryFolderPermissionsPayload) and action is not None:
            payload_dict["action"] = action
        return self.service.set_permissions(trans, id, payload_dict)