def replace_sample_acls(self, ctx, params): """ Completely overwrite a sample's ACLs. Any current ACLs are replaced by the provided ACLs, even if empty, and gone forever. The sample owner cannot be changed via this method. :param params: instance of type "ReplaceSampleACLsParams" (replace_sample_acls parameters. id - the ID of the sample to modify. acls - the ACLs to set on the sample. as_admin - replace the sample acls regardless of ACL contents as long as the user has full administration permissions.) -> structure: parameter "id" of type "sample_id" (A Sample ID. Must be globally unique. Always assigned by the Sample service.), parameter "acls" of type "SampleACLs" (Access control lists for a sample. Access levels include the privileges of the lower access levels. owner - the user that created and owns the sample. admin - users that can administrate (e.g. alter ACLs) the sample. write - users that can write (e.g. create a new version) to the sample. read - users that can view the sample.) -> structure: parameter "owner" of type "user" (A user's username.), parameter "admin" of list of type "user" (A user's username.), parameter "write" of list of type "user" (A user's username.), parameter "read" of list of type "user" (A user's username.), parameter "as_admin" of type "boolean" (A boolean value, 0 for false, 1 for true.) """ # ctx is the context object #BEGIN replace_sample_acls id_ = _get_id_from_object(params, required=True) acls = _acls_from_dict(params) admin = _check_admin( self._user_lookup, ctx[_CTX_TOKEN], _AdminPermission.FULL, # pretty annoying to test ctx.log_info is working, do it manually 'replace_sample_acls', ctx.log_info, skip_check=not params.get('as_admin')) self._samples.replace_sample_acls(id_, _UserID(ctx[_CTX_USER]), acls, as_admin=admin)
def create_data_link(self, ctx, params): """ Create a link from a KBase Workspace object to a sample. The user must have admin permissions for the sample and write permissions for the Workspace object. :param params: instance of type "CreateDataLinkParams" (create_data_link parameters. upa - the workspace UPA of the object to be linked. dataid - the dataid of the data to be linked, if any, within the object. If omitted the entire object is linked to the sample. id - the sample id. version - the sample version. node - the sample node. update - if false (the default), fail if a link already exists from the data unit (the combination of the UPA and dataid). if true, expire the old link and create the new link unless the link is already to the requested sample node, in which case the operation is a no-op. as_admin - run the method as a service administrator. The user must have full administration permissions. as_user - create the link as a different user. Ignored if as_admin is not true. Neither the administrator nor the impersonated user need have permissions to the data or sample.) -> structure: parameter "upa" of type "ws_upa" (A KBase Workspace service Unique Permanent Address (UPA). E.g. 5/6/7 where 5 is the workspace ID, 6 the object ID, and 7 the object version.), parameter "dataid" of type "data_id" (An id for a unit of data within a KBase Workspace object. A single object may contain many data units. A dataid is expected to be unique within a single object. Must be less than 255 characters.), parameter "id" of type "sample_id" (A Sample ID. Must be globally unique. Always assigned by the Sample service.), parameter "version" of type "version" (The version of a sample. Always > 0.), parameter "node" of type "node_id" (A SampleNode ID. Must be unique within a Sample and be less than 255 characters.), parameter "update" of type "boolean" (A boolean value, 0 for false, 1 for true.), parameter "as_admin" of type "boolean" (A boolean value, 0 for false, 1 for true.), parameter "as_user" of type "user" (A user's username.) """ # ctx is the context object #BEGIN create_data_link duid, sna, update = _create_data_link_params(params) as_admin, user = _get_admin_request_from_object(params, 'as_admin', 'as_user') _check_admin( self._user_lookup, ctx[_CTX_TOKEN], _AdminPermission.FULL, # pretty annoying to test ctx.log_info is working, do it manually 'create_data_link', ctx.log_info, as_user=user, skip_check=not as_admin) self._samples.create_data_link( user if user else _UserID(ctx[_CTX_USER]), duid, sna, update, as_admin=as_admin)
def update_samples_acls( params, samples_client, user_lookup, user, token, perms, log_info ): ''' Completely replace the ACLs for a list of samples. :param id_: the sample's ID. :param params: the update_samples_acls parameters :param samples_client: the samples client instance :param user_lookup: the KBaseUserLookup client method :param user: client username :param token: client token :param perms: client permissions :param log_info: logger :returns: None :raises IllegalParameterError: if the ID is provided but is invalid. :raises InvalidUserError: if any of the user names are invalid. :raises NoSuchSampleError: if the sample does not exist. :raises NoSuchUserError: if any of the users in the ACLs do not exist. :raises SampleStorageError: if the sample could not be retrieved. :raises UnauthorizedError: if any of the users names are valid but do not exist in the system. :raises UnauthorizedError: if the user does not have the permission required. :raises UnauthorizedError: if the user does not have admin permission for the sample or the request attempts to alter the owner. ''' acldelta = _acl_delta_from_dict(params) admin = _check_admin( user_lookup, token, perms, 'update_sample_acls', log_info, skip_check=not params.get('as_admin'), ) ids = params.get('ids') for id_ in ids: _validate_sample_id(id_, '') samples_client.update_sample_acls( id_, _UserID(user), acldelta, as_admin=admin )
def get_sample_acls(self, ctx, params): """ Get a sample's ACLs. :param params: instance of type "GetSampleACLsParams" (get_sample_acls parameters. id - the ID of the sample to retrieve. as_admin - get the sample acls regardless of ACL contents as long as the user has administration read permissions.) -> structure: parameter "id" of type "sample_id" (A Sample ID. Must be globally unique. Always assigned by the Sample service.), parameter "as_admin" of type "boolean" (A boolean value, 0 for false, 1 for true.) :returns: instance of type "SampleACLs" (Access control lists for a sample. Access levels include the privileges of the lower access levels. owner - the user that created and owns the sample. admin - users that can administrate (e.g. alter ACLs) the sample. write - users that can write (e.g. create a new version) to the sample. read - users that can view the sample.) -> structure: parameter "owner" of type "user" (A user's username.), parameter "admin" of list of type "user" (A user's username.), parameter "write" of list of type "user" (A user's username.), parameter "read" of list of type "user" (A user's username.) """ # ctx is the context object # return variables are: acls #BEGIN get_sample_acls id_ = _get_id_from_object(params, required=True) admin = _check_admin( self._user_lookup, ctx[_CTX_TOKEN], _AdminPermission.READ, # pretty annoying to test ctx.log_info is working, do it manually 'get_sample_acls', ctx.log_info, skip_check=not params.get('as_admin')) acls_ret = self._samples.get_sample_acls(id_, _UserID(ctx[_CTX_USER]), as_admin=admin) acls = _acls_to_dict(acls_ret) #END get_sample_acls # At some point might do deeper type checking... if not isinstance(acls, dict): raise ValueError('Method get_sample_acls return value ' + 'acls is not type dict as required.') # return the results return [acls]
def expire_data_link(self, ctx, params): """ Expire a link from a KBase Workspace object. The user must have admin permissions for the sample and write permissions for the Workspace object. :param params: instance of type "ExpireDataLinkParams" (expire_data_link parameters. upa - the workspace upa of the object from which the link originates. dataid - the dataid, if any, of the data within the object from which the link originates. Omit for links where the link is from the entire object. as_admin - run the method as a service administrator. The user must have full administration permissions. as_user - expire the link as a different user. Ignored if as_admin is not true. Neither the administrator nor the impersonated user need have permissions to the link if a new version is saved.) -> structure: parameter "upa" of type "ws_upa" (A KBase Workspace service Unique Permanent Address (UPA). E.g. 5/6/7 where 5 is the workspace ID, 6 the object ID, and 7 the object version.), parameter "dataid" of type "data_id" (An id for a unit of data within a KBase Workspace object. A single object may contain many data units. A dataid is expected to be unique within a single object. Must be less than 255 characters.), parameter "as_admin" of type "boolean" (A boolean value, 0 for false, 1 for true.), parameter "as_user" of type "user" (A user's username.) """ # ctx is the context object #BEGIN expire_data_link duid = _get_data_unit_id_from_object(params) as_admin, user = _get_admin_request_from_object(params, 'as_admin', 'as_user') _check_admin( self._user_lookup, ctx[_CTX_TOKEN], _AdminPermission.FULL, # pretty annoying to test ctx.log_info is working, do it manually 'expire_data_link', ctx.log_info, as_user=user, skip_check=not as_admin) self._samples.expire_data_link( user if user else _UserID(ctx[_CTX_USER]), duid, as_admin=as_admin)
def create_sample(self, ctx, params): """ Create a new sample or a sample version. :param params: instance of type "CreateSampleParams" (Parameters for creating a sample. If Sample.id is null, a new Sample is created along with a new ID. Otherwise, a new version of Sample.id is created. If Sample.id does not exist, an error is returned. Any incoming user, version or timestamp in the incoming sample is ignored. sample - the sample to save. prior_version - if non-null, ensures that no other sample version is saved between prior_version and the version that is created by this save. If this is not the case, the sample will fail to save. as_admin - run the method as a service administrator. The user must have full administration permissions. as_user - create the sample as a different user. Ignored if as_admin is not true. Neither the administrator nor the impersonated user need have permissions to the sample if a new version is saved.) -> structure: parameter "sample" of type "Sample" (A Sample, consisting of a tree of subsamples and replicates. id - the ID of the sample. user - the user that saved the sample. node_tree - the tree(s) of sample nodes in the sample. The the roots of all trees must be BioReplicate nodes. All the BioReplicate nodes must be at the start of the list, and all child nodes must occur after their parents in the list. name - the name of the sample. Must be less than 255 characters. save_date - the date the sample version was saved. version - the version of the sample.) -> structure: parameter "id" of type "sample_id" (A Sample ID. Must be globally unique. Always assigned by the Sample service.), parameter "user" of type "user" (A user's username.), parameter "node_tree" of list of type "SampleNode" (A node in a sample tree. id - the ID of the node. parent - the id of the parent node for the current node. BioReplicate nodes, and only BioReplicate nodes, do not have a parent. type - the type of the node. meta_controlled - metadata restricted by the sample controlled vocabulary and validators. meta_user - unrestricted metadata.) -> structure: parameter "id" of type "node_id" (A SampleNode ID. Must be unique within a Sample and be less than 255 characters.), parameter "parent" of type "node_id" (A SampleNode ID. Must be unique within a Sample and be less than 255 characters.), parameter "type" of type "samplenode_type" (The type of a sample node. One of: BioReplicate - a biological replicate. Always at the top of the sample tree. TechReplicate - a technical replicate. SubSample - a sub sample that is not a technical replicate.), parameter "meta_controlled" of type "metadata" (Metadata attached to a sample. The UnspecifiedObject map values MUST be a primitive type - either int, float, string, or equivalent typedefs.) -> mapping from type "metadata_key" (A key in a metadata key/value pair. Less than 1000 unicode characters.) to mapping from type "metadata_value_key" (A key for a value associated with a piece of metadata. Less than 1000 unicode characters. Examples: units, value, species) to unspecified object, parameter "meta_user" of type "metadata" (Metadata attached to a sample. The UnspecifiedObject map values MUST be a primitive type - either int, float, string, or equivalent typedefs.) -> mapping from type "metadata_key" (A key in a metadata key/value pair. Less than 1000 unicode characters.) to mapping from type "metadata_value_key" (A key for a value associated with a piece of metadata. Less than 1000 unicode characters. Examples: units, value, species) to unspecified object, parameter "name" of type "sample_name" (A sample name. Must be less than 255 characters.), parameter "save_date" of type "timestamp" (A timestamp in epoch milliseconds.), parameter "version" of type "version" (The version of a sample. Always > 0.), parameter "prior_version" of Long, parameter "as_admin" of type "boolean" (A boolean value, 0 for false, 1 for true.), parameter "as_user" of type "user" (A user's username.) :returns: instance of type "SampleAddress" (A Sample ID and version. id - the ID of the sample. version - the version of the sample.) -> structure: parameter "id" of type "sample_id" (A Sample ID. Must be globally unique. Always assigned by the Sample service.), parameter "version" of type "version" (The version of a sample. Always > 0.) """ # ctx is the context object # return variables are: address #BEGIN create_sample sample, id_, prev_ver = _create_sample_params(params) as_admin, user = _get_admin_request_from_object(params, 'as_admin', 'as_user') _check_admin( self._user_lookup, ctx[_CTX_TOKEN], _AdminPermission.FULL, # pretty annoying to test ctx.log_info is working, do it manually 'create_sample', ctx.log_info, as_user=user, skip_check=not as_admin) ret = self._samples.save_sample( sample, user if user else _UserID(ctx[_CTX_USER]), id_, prev_ver, as_admin=as_admin) address = {'id': str(ret[0]), 'version': ret[1]} #END create_sample # At some point might do deeper type checking... if not isinstance(address, dict): raise ValueError('Method create_sample return value ' + 'address is not type dict as required.') # return the results return [address]
def get_sample_via_data(self, ctx, params): """ Get a sample via a workspace object. Read permissions to a workspace object grants read permissions to all versions of any linked samples, whether the links are expired or not. This method allows for fetching samples when the user does not have explicit read access to the sample. :param params: instance of type "GetSampleViaDataParams" (get_sample_via_data parameters. upa - the workspace UPA of the target object. id - the target sample id. version - the target sample version.) -> structure: parameter "upa" of type "ws_upa" (A KBase Workspace service Unique Permanent Address (UPA). E.g. 5/6/7 where 5 is the workspace ID, 6 the object ID, and 7 the object version.), parameter "id" of type "sample_id" (A Sample ID. Must be globally unique. Always assigned by the Sample service.), parameter "version" of type "version" (The version of a sample. Always > 0.) :returns: instance of type "Sample" (A Sample, consisting of a tree of subsamples and replicates. id - the ID of the sample. user - the user that saved the sample. node_tree - the tree(s) of sample nodes in the sample. The the roots of all trees must be BioReplicate nodes. All the BioReplicate nodes must be at the start of the list, and all child nodes must occur after their parents in the list. name - the name of the sample. Must be less than 255 characters. save_date - the date the sample version was saved. version - the version of the sample.) -> structure: parameter "id" of type "sample_id" (A Sample ID. Must be globally unique. Always assigned by the Sample service.), parameter "user" of type "user" (A user's username.), parameter "node_tree" of list of type "SampleNode" (A node in a sample tree. id - the ID of the node. parent - the id of the parent node for the current node. BioReplicate nodes, and only BioReplicate nodes, do not have a parent. type - the type of the node. meta_controlled - metadata restricted by the sample controlled vocabulary and validators. meta_user - unrestricted metadata.) -> structure: parameter "id" of type "node_id" (A SampleNode ID. Must be unique within a Sample and be less than 255 characters.), parameter "parent" of type "node_id" (A SampleNode ID. Must be unique within a Sample and be less than 255 characters.), parameter "type" of type "samplenode_type" (The type of a sample node. One of: BioReplicate - a biological replicate. Always at the top of the sample tree. TechReplicate - a technical replicate. SubSample - a sub sample that is not a technical replicate.), parameter "meta_controlled" of type "metadata" (Metadata attached to a sample. The UnspecifiedObject map values MUST be a primitive type - either int, float, string, or equivalent typedefs.) -> mapping from type "metadata_key" (A key in a metadata key/value pair. Less than 1000 unicode characters.) to mapping from type "metadata_value_key" (A key for a value associated with a piece of metadata. Less than 1000 unicode characters. Examples: units, value, species) to unspecified object, parameter "meta_user" of type "metadata" (Metadata attached to a sample. The UnspecifiedObject map values MUST be a primitive type - either int, float, string, or equivalent typedefs.) -> mapping from type "metadata_key" (A key in a metadata key/value pair. Less than 1000 unicode characters.) to mapping from type "metadata_value_key" (A key for a value associated with a piece of metadata. Less than 1000 unicode characters. Examples: units, value, species) to unspecified object, parameter "name" of type "sample_name" (A sample name. Must be less than 255 characters.), parameter "save_date" of type "timestamp" (A timestamp in epoch milliseconds.), parameter "version" of type "version" (The version of a sample. Always > 0.) """ # ctx is the context object # return variables are: sample #BEGIN get_sample_via_data upa = _get_upa_from_object(params) sid, ver = _get_sample_address_from_object(params, version_required=True) sample = self._samples.get_sample_via_data( _UserID(ctx[_CTX_USER]), upa, _SampleAddress(sid, ver)) sample = _sample_to_dict(sample) #END get_sample_via_data # At some point might do deeper type checking... if not isinstance(sample, dict): raise ValueError('Method get_sample_via_data return value ' + 'sample is not type dict as required.') # return the results return [sample]
def get_data_links_from_data(self, ctx, params): """ Get data links to samples originating from Workspace data. The user must have read permissions to the workspace data. :param params: instance of type "GetDataLinksFromDataParams" (get_data_links_from_data parameters. upa - the data UPA. effective_time - the effective time at which the query should be run - the default is the current time. Providing a time allows for reproducibility of previous results. as_admin - run the method as a service administrator. The user must have read administration permissions.) -> structure: parameter "upa" of type "ws_upa" (A KBase Workspace service Unique Permanent Address (UPA). E.g. 5/6/7 where 5 is the workspace ID, 6 the object ID, and 7 the object version.), parameter "effective_time" of type "timestamp" (A timestamp in epoch milliseconds.), parameter "as_admin" of type "boolean" (A boolean value, 0 for false, 1 for true.) :returns: instance of type "GetDataLinksFromDataResults" (get_data_links_from_data results. links - the links. effective_time - the time at which the query was run. This timestamp, if saved, can be used when running the method again to ensure reproducible results.) -> structure: parameter "links" of list of type "DataLink" (A data link from a KBase workspace object to a sample. upa - the workspace UPA of the linked object. dataid - the dataid of the linked data, if any, within the object. If omitted the entire object is linked to the sample. id - the sample id. version - the sample version. node - the sample node. createdby - the user that created the link. created - the time the link was created. expiredby - the user that expired the link, if any. expired - the time the link was expired, if at all.) -> structure: parameter "upa" of type "ws_upa" (A KBase Workspace service Unique Permanent Address (UPA). E.g. 5/6/7 where 5 is the workspace ID, 6 the object ID, and 7 the object version.), parameter "dataid" of type "data_id" (An id for a unit of data within a KBase Workspace object. A single object may contain many data units. A dataid is expected to be unique within a single object. Must be less than 255 characters.), parameter "id" of type "sample_id" (A Sample ID. Must be globally unique. Always assigned by the Sample service.), parameter "version" of type "version" (The version of a sample. Always > 0.), parameter "node" of type "node_id" (A SampleNode ID. Must be unique within a Sample and be less than 255 characters.), parameter "createdby" of type "user" (A user's username.), parameter "created" of type "timestamp" (A timestamp in epoch milliseconds.), parameter "expiredby" of type "user" (A user's username.), parameter "expired" of type "timestamp" (A timestamp in epoch milliseconds.), parameter "effective_time" of type "timestamp" (A timestamp in epoch milliseconds.) """ # ctx is the context object # return variables are: results #BEGIN get_data_links_from_data upa = _get_upa_from_object(params) dt = _get_datetime_from_epochmillseconds_in_object(params, 'effective_time') admin = _check_admin( self._user_lookup, ctx[_CTX_TOKEN], _AdminPermission.READ, # pretty annoying to test ctx.log_info is working, do it manually 'get_data_links_from_data', ctx.log_info, skip_check=not params.get('as_admin')) links, ts = self._samples.get_links_from_data( _UserID(ctx[_CTX_USER]), upa, dt, as_admin=admin) results = {'links': _links_to_dicts(links), 'effective_time': _datetime_to_epochmilliseconds(ts) } #END get_data_links_from_data # At some point might do deeper type checking... if not isinstance(results, dict): raise ValueError('Method get_data_links_from_data return value ' + 'results is not type dict as required.') # return the results return [results]
def get_sample(self, ctx, params): """ Get a sample. If the version is omitted the most recent sample is returned. :param params: instance of type "GetSampleParams" (get_sample parameters. id - the ID of the sample to retrieve. version - the version of the sample to retrieve, or the most recent sample if omitted. as_admin - get the sample regardless of ACLs as long as the user has administration read permissions.) -> structure: parameter "id" of type "sample_id" (A Sample ID. Must be globally unique. Always assigned by the Sample service.), parameter "version" of type "version" (The version of a sample. Always > 0.), parameter "as_admin" of type "boolean" (A boolean value, 0 for false, 1 for true.) :returns: instance of type "Sample" (A Sample, consisting of a tree of subsamples and replicates. id - the ID of the sample. user - the user that saved the sample. node_tree - the tree(s) of sample nodes in the sample. The the roots of all trees must be BioReplicate nodes. All the BioReplicate nodes must be at the start of the list, and all child nodes must occur after their parents in the list. name - the name of the sample. Must be less than 255 characters. save_date - the date the sample version was saved. version - the version of the sample.) -> structure: parameter "id" of type "sample_id" (A Sample ID. Must be globally unique. Always assigned by the Sample service.), parameter "user" of type "user" (A user's username.), parameter "node_tree" of list of type "SampleNode" (A node in a sample tree. id - the ID of the node. parent - the id of the parent node for the current node. BioReplicate nodes, and only BioReplicate nodes, do not have a parent. type - the type of the node. meta_controlled - metadata restricted by the sample controlled vocabulary and validators. meta_user - unrestricted metadata.) -> structure: parameter "id" of type "node_id" (A SampleNode ID. Must be unique within a Sample and be less than 255 characters.), parameter "parent" of type "node_id" (A SampleNode ID. Must be unique within a Sample and be less than 255 characters.), parameter "type" of type "samplenode_type" (The type of a sample node. One of: BioReplicate - a biological replicate. Always at the top of the sample tree. TechReplicate - a technical replicate. SubSample - a sub sample that is not a technical replicate.), parameter "meta_controlled" of type "metadata" (Metadata attached to a sample. The UnspecifiedObject map values MUST be a primitive type - either int, float, string, or equivalent typedefs.) -> mapping from type "metadata_key" (A key in a metadata key/value pair. Less than 1000 unicode characters.) to mapping from type "metadata_value_key" (A key for a value associated with a piece of metadata. Less than 1000 unicode characters. Examples: units, value, species) to unspecified object, parameter "meta_user" of type "metadata" (Metadata attached to a sample. The UnspecifiedObject map values MUST be a primitive type - either int, float, string, or equivalent typedefs.) -> mapping from type "metadata_key" (A key in a metadata key/value pair. Less than 1000 unicode characters.) to mapping from type "metadata_value_key" (A key for a value associated with a piece of metadata. Less than 1000 unicode characters. Examples: units, value, species) to unspecified object, parameter "name" of type "sample_name" (A sample name. Must be less than 255 characters.), parameter "save_date" of type "timestamp" (A timestamp in epoch milliseconds.), parameter "version" of type "version" (The version of a sample. Always > 0.) """ # ctx is the context object # return variables are: sample #BEGIN get_sample id_, ver = _get_sample_address_from_object(params) admin = _check_admin(self._user_lookup, ctx[_CTX_TOKEN], _AdminPermission.READ, # pretty annoying to test ctx.log_info is working, do it manually 'get_sample', ctx.log_info, skip_check=not params.get('as_admin')) s = self._samples.get_sample(id_, _UserID(ctx[_CTX_USER]), ver, as_admin=admin) sample = _sample_to_dict(s) #END get_sample # At some point might do deeper type checking... if not isinstance(sample, dict): raise ValueError('Method get_sample return value ' + 'sample is not type dict as required.') # return the results return [sample]