1 new commit in galaxy-central: https://bitbucket.org/galaxy/galaxy-central/commits/fe5867b89ec0/ Changeset: fe5867b89ec0 User: carlfeberhard Date: 2013-07-31 22:55:50 Summary: API Documentation: histories, history_contents Affected #: 2 files diff -r edef166c163f30175e98ddb0b98f7993d7d4d5eb -r fe5867b89ec01bfde18591df8809526d85fb821e lib/galaxy/webapps/galaxy/api/histories.py --- a/lib/galaxy/webapps/galaxy/api/histories.py +++ b/lib/galaxy/webapps/galaxy/api/histories.py @@ -1,5 +1,7 @@ """ API operations on a history. + +.. seealso:: :class:`galaxy.model.History` """ import pkg_resources @@ -21,17 +23,30 @@ @web.expose_api_anonymous def index( self, trans, deleted='False', **kwd ): """ - GET /api/histories - GET /api/histories/deleted - Displays a collection (list) of histories. + index( trans, deleted='False' ) + * GET /api/histories: + return undeleted histories for the current user + * GET /api/histories/deleted: + return deleted histories for the current user + + If the user is logged-in, a full list of all histories is shown. + If not logged in, only the curernt history (if any) is shown. + + :type deleted: boolean + :param deleted: if True, show only deleted histories, if False, non-deleted + + :rtype: list + :returns: list of dictionaries containing summary history information """ #TODO: query (by name, date, etc.) rval = [] deleted = string_as_bool( deleted ) try: if trans.user: - query = trans.sa_session.query(trans.app.model.History ).filter_by( user=trans.user, deleted=deleted ).order_by( - desc(trans.app.model.History.table.c.update_time)).all() + query = ( trans.sa_session.query( trans.app.model.History ) + .filter_by( user=trans.user, deleted=deleted ) + .order_by( desc( trans.app.model.History.table.c.update_time ) ) + .all() ) for history in query: item = history.get_api_value(value_mapper={'id':trans.security.encode_id}) item['url'] = url_for( 'history', id=trans.security.encode_id( history.id ) ) @@ -52,11 +67,24 @@ @web.expose_api_anonymous def show( self, trans, id, deleted='False', **kwd ): + # oh, sphinx - you bastard """ - GET /api/histories/{encoded_history_id} - GET /api/histories/deleted/{encoded_history_id} - GET /api/histories/most_recently_used - Displays information about a history. + show( trans, id, deleted='False' ) + * GET /api/histories/{id}: + return the history with ``id`` + * GET /api/histories/deleted/{id}: + return the deleted history with ``id`` + * GET /api/histories/most_recently_used: + return the most recently used history + + :type id: an encoded id string + :param id: the encoded id of the history to query or the string 'most_recently_used' + :type deleted: boolean + :param deleted: if True, allow information on a deleted history to be shown. + + :rtype: dictionary + :returns: detailed history information from + :func:`galaxy.web.base.controller.UsesHistoryDatasetAssociationMixin.get_history_dict` """ #TODO: GET /api/histories/{encoded_history_id}?as_archive=True #TODO: GET /api/histories/s/{username}/{slug} @@ -94,8 +122,16 @@ @web.expose_api def create( self, trans, payload, **kwd ): """ - POST /api/histories - Creates a new history. + create( trans, payload ) + * POST /api/histories: + create a new history + + :type payload: dict + :param payload: (optional) dictionary structure containing:: + 'name': the new history's name + + :rtype: dict + :returns: element view of new history """ hist_name = None if payload.get( 'name', None ): @@ -115,8 +151,24 @@ @web.expose_api def delete( self, trans, id, **kwd ): """ - DELETE /api/histories/{encoded_history_id} - Deletes a history + delete( self, trans, id, **kwd ) + * DELETE /api/histories/{id} + delete the history with the given ``id`` + .. note:: Currently does not stop any active jobs in the history. + + :type id: str + :param id: the encoded id of the history to delete + :type kwd: dict + :param kwd: (optional) dictionary structure containing:: + 'payload': a dictionary itself containing:: + 'purge': if True, purge the history and all of it's HDAs + + :rtype: dict + :returns: an error object if an error occurred or a dictionary containing:: + + id: the encoded id of the history, + deleted: if the history was marked as deleted, + purged: if the history was purged """ history_id = id # a request body is optional here @@ -175,8 +227,15 @@ @web.expose_api def undelete( self, trans, id, **kwd ): """ - POST /api/histories/deleted/{encoded_history_id}/undelete - Undeletes a history + undelete( self, trans, id, **kwd ) + * POST /api/histories/deleted/{id}/undelete: + undelete history (that hasn't been purged) with the given ``id`` + + :type id: str + :param id: the encoded id of the history to undelete + + :rtype: str + :returns: 'OK' if the history was undeleted """ history_id = id history = self.get_history( trans, history_id, check_ownership=True, check_accessible=False, deleted=True ) @@ -188,8 +247,21 @@ @web.expose_api def update( self, trans, id, payload, **kwd ): """ - PUT /api/histories/{encoded_history_id} - Changes an existing history. + update( self, trans, id, payload, **kwd ) + * PUT /api/histories/{id} + updates the values for the history with the given ``id`` + + :type id: str + :param id: the encoded id of the history to undelete + :type payload: dict + :param payload: a dictionary containing any or all the + fields in :func:`galaxy.model.History.get_api_value` and/or the following:: + + 'annotation': an annotation for the history + + :rtype: dict + :returns: an error object if an error occurred or a dictionary containing + any values that were different from the original and, therefore, updated """ #TODO: PUT /api/histories/{encoded_history_id} payload = { rating: rating } (w/ no security checks) try: @@ -255,6 +327,7 @@ raise ValueError( 'annotation must be a string or unicode: %s' %( str( type( val ) ) ) ) validated_payload[ 'annotation' ] = sanitize_html( val, 'utf-8' ) elif key not in valid_but_uneditable_keys: - raise AttributeError( 'unknown key: %s' %( str( key ) ) ) + pass + #log.warn( 'unknown key: %s', str( key ) ) return validated_payload diff -r edef166c163f30175e98ddb0b98f7993d7d4d5eb -r fe5867b89ec01bfde18591df8809526d85fb821e lib/galaxy/webapps/galaxy/api/history_contents.py --- a/lib/galaxy/webapps/galaxy/api/history_contents.py +++ b/lib/galaxy/webapps/galaxy/api/history_contents.py @@ -15,21 +15,31 @@ @web.expose_api_anonymous def index( self, trans, history_id, ids=None, **kwd ): """ - GET /api/histories/{encoded_history_id}/contents - Displays a collection (list) of history contents (HDAs) + index( self, trans, history_id, ids=None, **kwd ) + * GET /api/histories/{history_id}/contents + return a list of HDA data for the history with the given ``id`` - :param history_id: an encoded id string of the `History` to search - :param ids: (optional) a comma separated list of encoded `HDA` ids + :type history_id: str + :param history_id: encoded id string of the HDA's History + :type ids: str + :param ids: (optional) a comma separated list of encoded `HDA` ids - If Ids is not given, index returns a list of *summary* json objects for - every `HDA` associated with the given `history_id`. - See _summary_hda_dict. + If Ids is not given, index returns a list of *summary* objects for + every HDA associated with the given `history_id`. + + .. seealso:: + :func:`_summary_hda_dict` If ids is given, index returns a *more complete* json object for each HDA in the ids list. - Note: Anonymous users are allowed to get their current history contents - (generally useful for browser UI access of the api) + .. seealso:: + :func:`galaxy.web.base.controller.UsesHistoryDatasetAssociationMixin.get_hda_dict` + + .. note:: Anonymous users are allowed to get their current history contents + + :rtype: list + :returns: dictionaries containing summary or detailed HDA information """ rval = [] try: @@ -78,13 +88,13 @@ #TODO: move to model or Mixin def _summary_hda_dict( self, trans, history_id, hda ): """ - Returns a dictionary based on the HDA in .. _summary form:: - { - 'id' : < the encoded dataset id >, - 'name' : < currently only returns 'file' >, - 'type' : < name of the dataset >, - 'url' : < api url to retrieve this datasets full data >, - } + Returns a dictionary based on the HDA in summary form:: + { + 'id' : < the encoded dataset id >, + 'name' : < currently only returns 'file' >, + 'type' : < name of the dataset >, + 'url' : < api url to retrieve this datasets full data >, + } """ api_type = "file" encoded_id = trans.security.encode_id( hda.id ) @@ -98,8 +108,21 @@ @web.expose_api_anonymous def show( self, trans, id, history_id, **kwd ): """ - GET /api/histories/{encoded_history_id}/contents/{encoded_content_id} - Displays information about a history content (dataset). + show( self, trans, id, history_id, **kwd ) + * GET /api/histories/{history_id}/contents/{id} + return detailed information about an HDA within a history + + :type id: str + :param ids: the encoded id of the HDA to return + :type history_id: str + :param history_id: encoded id string of the HDA's History + + .. seealso:: :func:`galaxy.web.base.controller.UsesHistoryDatasetAssociationMixin.get_hda_dict` + + .. note:: Anonymous users are allowed to get their current history contents + + :rtype: dict + :returns: dictionary containing detailed HDA information """ hda_dict = {} try: @@ -135,8 +158,18 @@ @web.expose_api def create( self, trans, history_id, payload, **kwd ): """ - POST /api/histories/{encoded_history_id}/contents - Creates a new history content item (file, aka HistoryDatasetAssociation). + create( self, trans, history_id, payload, **kwd ) + * POST /api/histories/{history_id}/contents + create a new HDA by copying an accessible LibraryDataset + + :type history_id: str + :param history_id: encoded id string of the new HDA's History + :type payload: dict + :param payload: dictionary structure containing:: + 'from_ld_id': the encoded id of the LibraryDataset to copy + + :rtype: dict + :returns: dictionary containing detailed information for the new HDA """ #TODO: copy existing, accessible hda - dataset controller, copy_datasets #TODO: convert existing, accessible hda - model.DatasetInstance(or hda.datatype).get_converter_types @@ -173,8 +206,24 @@ @web.expose_api def update( self, trans, history_id, id, payload, **kwd ): """ - PUT /api/histories/{encoded_history_id}/contents/{encoded_content_id} - Changes an existing history dataset. + update( self, trans, history_id, id, payload, **kwd ) + * PUT /api/histories/{history_id}/contents/{id} + updates the values for the HDA with the given ``id`` + + :type history_id: str + :param history_id: encoded id string of the HDA's History + :type id: str + :param id: the encoded id of the history to undelete + :type payload: dict + :param payload: a dictionary containing any or all the + fields in :func:`galaxy.model.HistoryDatasetAssociation.get_api_value` + and/or the following:: + + 'annotation': an annotation for the history + + :rtype: dict + :returns: an error object if an error occurred or a dictionary containing + any values that were different from the original and, therefore, updated """ #TODO: PUT /api/histories/{encoded_history_id} payload = { rating: rating } (w/ no security checks) changed = {} @@ -251,6 +300,7 @@ raise ValueError( 'misc_info must be a string or unicode: %s' %( str( type( val ) ) ) ) validated_payload[ 'info' ] = util.sanitize_html.sanitize_html( val, 'utf-8' ) elif key not in valid_but_uneditable_keys: - raise AttributeError( 'unknown key: %s' %( str( key ) ) ) + pass + #log.warn( 'unknown key: %s', str( key ) ) return validated_payload Repository URL: https://bitbucket.org/galaxy/galaxy-central/ -- This is a commit notification from bitbucket.org. You are receiving this because you have the service enabled, addressing the recipient of this email.