From ef187ad37eb71dedf9e49db4a0203ab86fcb519e Mon Sep 17 00:00:00 2001 From: Martin Cech Date: Thu, 29 Aug 2019 13:30:27 -0400 Subject: [PATCH] restyle docstring for consistency --- .../webapps/galaxy/api/folder_contents.py | 7 ++-- lib/galaxy/webapps/galaxy/api/folders.py | 34 +++++++++++------- .../webapps/galaxy/api/library_contents.py | 36 +++++++++---------- .../webapps/galaxy/api/library_datasets.py | 35 +++++++++--------- 4 files changed, 61 insertions(+), 51 deletions(-) diff --git a/lib/galaxy/webapps/galaxy/api/folder_contents.py b/lib/galaxy/webapps/galaxy/api/folder_contents.py index 66f66780fbe..4e4add851b6 100644 --- a/lib/galaxy/webapps/galaxy/api/folder_contents.py +++ b/lib/galaxy/webapps/galaxy/api/folder_contents.py @@ -251,8 +251,9 @@ class FolderContentsController(BaseAPIController, UsesLibraryMixin, UsesLibraryM @expose_api def create(self, trans, encoded_folder_id, payload, **kwd): """ - * POST /api/folders/{encoded_id}/contents - create a new library file from an HDA + POST /api/folders/{encoded_id}/contents + + Create a new library file from an HDA. :param encoded_folder_id: the encoded id of the folder to import dataset(s) to :type encoded_folder_id: an encoded id string @@ -299,7 +300,7 @@ class FolderContentsController(BaseAPIController, UsesLibraryMixin, UsesLibraryM def __decode_library_content_id(self, trans, encoded_folder_id): """ - Identifies whether the id provided is properly encoded + Identify whether the id provided is properly encoded LibraryFolder. :param encoded_folder_id: encoded id of Galaxy LibraryFolder diff --git a/lib/galaxy/webapps/galaxy/api/folders.py b/lib/galaxy/webapps/galaxy/api/folders.py index e168f242771..0d497fbccf4 100644 --- a/lib/galaxy/webapps/galaxy/api/folders.py +++ b/lib/galaxy/webapps/galaxy/api/folders.py @@ -24,7 +24,8 @@ class FoldersController(BaseAPIController, UsesLibraryMixin, UsesLibraryMixinIte @expose_api def index(self, trans, **kwd): """ - *GET /api/folders/ + GET /api/folders/ + This would normally display a list of folders. However, that would be across multiple libraries, so it's not implemented. """ @@ -33,8 +34,7 @@ class FoldersController(BaseAPIController, UsesLibraryMixin, UsesLibraryMixinIte @expose_api def show(self, trans, id, **kwd): """ - show( self, trans, id, **kwd ) - *GET /api/folders/{encoded_folder_id} + GET /api/folders/{encoded_folder_id} Displays information about a folder. @@ -52,8 +52,9 @@ class FoldersController(BaseAPIController, UsesLibraryMixin, UsesLibraryMixinIte @expose_api def create(self, trans, encoded_parent_folder_id, payload=None, **kwd): """ - *POST /api/folders/{encoded_parent_folder_id} - Create a new folder object underneath the one specified in the parameters. + POST /api/folders/{encoded_parent_folder_id} + + Create a new folder object underneath the one specified in the parameters. :param encoded_parent_folder_id: (required) the parent folder's id :type encoded_parent_folder_id: an encoded id string (should be prefixed by 'F') @@ -81,7 +82,7 @@ class FoldersController(BaseAPIController, UsesLibraryMixin, UsesLibraryMixinIte @expose_api def get_permissions(self, trans, encoded_folder_id, **kwd): """ - * GET /api/folders/{id}/permissions + GET /api/folders/{id}/permissions Load all permissions for the given folder id and return it. @@ -132,8 +133,9 @@ class FoldersController(BaseAPIController, UsesLibraryMixin, UsesLibraryMixinIte @expose_api def set_permissions(self, trans, encoded_folder_id, payload=None, **kwd): """ - *POST /api/folders/{encoded_folder_id}/permissions - Set permissions of the given folder to the given role ids. + POST /api/folders/{encoded_folder_id}/permissions + + Set permissions of the given folder to the given role ids. :param encoded_folder_id: the encoded id of the folder to set the permissions of :type encoded_folder_id: an encoded id string @@ -224,9 +226,10 @@ class FoldersController(BaseAPIController, UsesLibraryMixin, UsesLibraryMixinIte @expose_api def delete(self, trans, encoded_folder_id, **kwd): """ - delete( self, trans, encoded_folder_id, **kwd ) - * DELETE /api/folders/{encoded_folder_id} - marks the folder with the given ``encoded_folder_id`` as `deleted` (or removes the `deleted` mark if the `undelete` param is true) + DELETE /api/folders/{encoded_folder_id} + + Mark the folder with the given ``encoded_folder_id`` as `deleted` + (or remove the `deleted` mark if the `undelete` param is true). .. note:: Currently, only admin users can un/delete folders. @@ -249,19 +252,24 @@ class FoldersController(BaseAPIController, UsesLibraryMixin, UsesLibraryMixinIte @expose_api def update(self, trans, encoded_folder_id, payload=None, **kwd): """ - * PATCH /api/folders/{encoded_folder_id} - Update the folder defined by an ``encoded_folder_id`` with the data in the payload. + PATCH /api/folders/{encoded_folder_id} + + Update the folder defined by an ``encoded_folder_id`` + with the data in the payload. .. note:: Currently, only admin users can update library folders. Also the folder must not be `deleted`. :param id: the encoded id of the folder :type id: an encoded id string + :param payload: (required) dictionary structure containing:: 'name': new folder's name, cannot be empty 'description': new folder's description :type payload: dict + :returns: detailed folder information :rtype: dict + :raises: RequestParameterMissingException """ decoded_folder_id = self.folder_manager.cut_and_decode(trans, encoded_folder_id) diff --git a/lib/galaxy/webapps/galaxy/api/library_contents.py b/lib/galaxy/webapps/galaxy/api/library_contents.py index d030f9e92b0..3907bcd9f74 100644 --- a/lib/galaxy/webapps/galaxy/api/library_contents.py +++ b/lib/galaxy/webapps/galaxy/api/library_contents.py @@ -43,12 +43,12 @@ class LibraryContentsController(BaseAPIController, UsesLibraryMixin, UsesLibrary @expose_api def index(self, trans, library_id, **kwd): """ - index( self, trans, library_id, **kwd ) - * GET /api/libraries/{library_id}/contents: - Returns a list of library files and folders. + GET /api/libraries/{library_id}/contents: - .. note:: May be slow! Returns all content traversing recursively through all folders. - .. seealso:: :class:`galaxy.webapps.galaxy.api.FolderContentsController.index` for a non-recursive solution + Return a list of library files and folders. + + .. note:: This endpoint is slow for large libraries. Returns all content traversing recursively through all folders. + .. seealso:: :class:`galaxy.webapps.galaxy.api.FolderContentsController.index` for a faster non-recursive solution :param library_id: the encoded id of the library :type library_id: str @@ -123,9 +123,9 @@ class LibraryContentsController(BaseAPIController, UsesLibraryMixin, UsesLibrary @expose_api def show(self, trans, id, library_id, **kwd): """ - show( self, trans, id, library_id, **kwd ) - * GET /api/libraries/{library_id}/contents/{id} - Returns information about library file or folder. + GET /api/libraries/{library_id}/contents/{id} + + Returns information about library file or folder. :param id: the encoded id of the library item to return :type id: str @@ -160,9 +160,9 @@ class LibraryContentsController(BaseAPIController, UsesLibraryMixin, UsesLibrary @expose_api def create(self, trans, library_id, payload, **kwd): """ - create( self, trans, library_id, payload, **kwd ) - * POST /api/libraries/{library_id}/contents: - create a new library file or folder + POST /api/libraries/{library_id}/contents: + + Create a new library file or folder. To copy an HDA into a library send ``create_type`` of 'file' and the HDA's encoded id in ``from_hda_id`` (and optionally ``ldda_message``). @@ -374,9 +374,10 @@ class LibraryContentsController(BaseAPIController, UsesLibraryMixin, UsesLibrary @expose_api def update(self, trans, id, library_id, payload, **kwd): """ - update( self, trans, id, library_id, payload, **kwd ) - * PUT /api/libraries/{library_id}/contents/{id} - create a ImplicitlyConvertedDatasetAssociation + PUT /api/libraries/{library_id}/contents/{id} + + Create an ImplicitlyConvertedDatasetAssociation. + .. seealso:: :class:`galaxy.model.ImplicitlyConvertedDatasetAssociation` :type id: str @@ -412,9 +413,9 @@ class LibraryContentsController(BaseAPIController, UsesLibraryMixin, UsesLibrary @expose_api def delete(self, trans, library_id, id, **kwd): """ - delete( self, trans, library_id, id, **kwd ) - * DELETE /api/libraries/{library_id}/contents/{id} - delete the LibraryDataset with the given ``id`` + DELETE /api/libraries/{library_id}/contents/{id} + + Delete the LibraryDataset with the given ``id``. :type id: str :param id: the encoded id of the library dataset to delete @@ -430,7 +431,6 @@ class LibraryContentsController(BaseAPIController, UsesLibraryMixin, UsesLibrary * deleted: if the library dataset was marked as deleted, * purged: if the library dataset was purged """ - # a request body is optional here purge = False if kwd.get('payload', None): purge = util.string_as_bool(kwd['payload'].get('purge', False)) diff --git a/lib/galaxy/webapps/galaxy/api/library_datasets.py b/lib/galaxy/webapps/galaxy/api/library_datasets.py index 73979eac7f5..627c093a36b 100644 --- a/lib/galaxy/webapps/galaxy/api/library_datasets.py +++ b/lib/galaxy/webapps/galaxy/api/library_datasets.py @@ -49,9 +49,9 @@ class LibraryDatasetsController(BaseAPIController, UsesVisualizationMixin, Libra @expose_api_anonymous def show(self, trans, id, **kwd): """ - Show the details of a library dataset. + GET /api/libraries/datasets/{encoded_dataset_id} - * GET /api/libraries/datasets/{encoded_dataset_id} + Show the details of a library dataset. :param id: the encoded id of the library dataset to query :type id: an encoded id string @@ -66,9 +66,9 @@ class LibraryDatasetsController(BaseAPIController, UsesVisualizationMixin, Libra @expose_api_anonymous def show_version(self, trans, encoded_dataset_id, encoded_ldda_id, **kwd): """ - Display a specific version of a library dataset (i.e. ldda). + GET /api/libraries/datasets/{encoded_dataset_id}/versions/{encoded_ldda_id} - * GET /api/libraries/datasets/{encoded_dataset_id}/versions/{encoded_ldda_id} + Display a specific version of a library dataset (i.e. ldda). :param encoded_dataset_id: the encoded id of the related library dataset :type encoded_dataset_id: an encoded id string @@ -97,9 +97,9 @@ class LibraryDatasetsController(BaseAPIController, UsesVisualizationMixin, Libra @expose_api def show_roles(self, trans, encoded_dataset_id, **kwd): """ - Display information about current or available roles for a given dataset permission. + GET /api/libraries/datasets/{encoded_dataset_id}/permissions - * GET /api/libraries/datasets/{encoded_dataset_id}/permissions + Display information about current or available roles for a given dataset permission. :param encoded_dataset_id: the encoded id of the dataset to query :type encoded_dataset_id: an encoded id string @@ -159,9 +159,10 @@ class LibraryDatasetsController(BaseAPIController, UsesVisualizationMixin, Libra @expose_api def update(self, trans, encoded_dataset_id, payload=None, **kwd): - """Update the given library dataset (the latest linked ldda). + """ + PATCH /api/libraries/datasets/{encoded_dataset_id} - * PATCH /api/libraries/datasets/{encoded_dataset_id} + Update the given library dataset (the latest linked ldda). :param encoded_dataset_id: the encoded id of the library dataset to update :type encoded_dataset_id: an encoded id string @@ -187,9 +188,9 @@ class LibraryDatasetsController(BaseAPIController, UsesVisualizationMixin, Libra @expose_api def update_permissions(self, trans, encoded_dataset_id, payload=None, **kwd): """ - Set permissions of the given library dataset to the given role ids. + POST /api/libraries/datasets/{encoded_dataset_id}/permissions - *POST /api/libraries/datasets/{encoded_dataset_id}/permissions + Set permissions of the given library dataset to the given role ids. :param encoded_dataset_id: the encoded id of the dataset to update permissions of :type encoded_dataset_id: an encoded id string @@ -294,9 +295,9 @@ class LibraryDatasetsController(BaseAPIController, UsesVisualizationMixin, Libra @expose_api def delete(self, trans, encoded_dataset_id, **kwd): """ - Mark the dataset deleted or undeleted. + DELETE /api/libraries/datasets/{encoded_dataset_id} - * DELETE /api/libraries/datasets/{encoded_dataset_id} + Mark the dataset deleted or undeleted. :param encoded_dataset_id: the encoded id of the dataset to change :type encoded_dataset_id: an encoded id string @@ -332,9 +333,9 @@ class LibraryDatasetsController(BaseAPIController, UsesVisualizationMixin, Libra @expose_api def load(self, trans, payload=None, **kwd): """ - Load dataset(s) from the given source into the library. + POST /api/libraries/datasets - * POST /api/libraries/datasets + Load dataset(s) from the given source into the library. :param payload: dictionary structure containing: :param encoded_folder_id: the encoded id of the folder to import dataset(s) to @@ -497,10 +498,10 @@ class LibraryDatasetsController(BaseAPIController, UsesVisualizationMixin, Libra # TODO convert to expose_api def download(self, trans, format, **kwd): """ - Download requested datasets (identified by encoded IDs) in requested format. + GET /api/libraries/datasets/download/{format} + POST /api/libraries/datasets/download/{format} - * GET /api/libraries/datasets/download/{format} - * POST /api/libraries/datasets/download/{format} + Download requested datasets (identified by encoded IDs) in requested format. example: ``GET localhost:8080/api/libraries/datasets/download/tbz?ld_ids%255B%255D=a0d84b45643a2678&ld_ids%255B%255D=fe38c84dcd46c828``