scitacean.client.ScicatClient#

class scitacean.client.ScicatClient(url, token, timeout)[source]#

Low-level client to call the SciCat API.

Constructors

`from_credentials`(url, username, password[, ...])	Create a new low-level client and authenticate with username and password.
`from_token`(url, token[, timeout])	Create a new low-level client and authenticate with a token.
`without_login`(url[, timeout])	Create a new low-level client without authentication.

Methods

`create_attachment_for_dataset`(attachment, *, ...)	Create a new attachment for a dataset in SciCat.
`create_dataset_model`(dset)	Create a new dataset in SciCat.
`create_orig_datablock`(dblock, *, dataset_id)	Create a new orig datablock in SciCat.
`create_sample_model`(sample)	Create a new sample in SciCat.
`get_attachments_for_dataset`(pid[, ...])	Fetch all attachments from SciCat for a given dataset.
`get_dataset_model`(pid[, strict_validation])	Fetch a dataset from SciCat.
`get_orig_datablocks`(pid[, strict_validation])	Fetch all orig datablocks from SciCat for a given dataset.
`get_sample_model`(sample_id[, strict_validation])	Fetch a sample from SciCat.
`query_datasets`(fields, *[, limit, order, ...])	Query for datasets in SciCat.
`validate_dataset_model`(dset)	Validate a dataset in SciCat.

create_attachment_for_dataset(attachment, *, dataset_id)[source]#

Create a new attachment for a dataset in SciCat.

The attachment ID must be either

None, in which case SciCat assigns an ID.
An unused id, in which case SciCat uses it for the new attachment.

If the ID already exists, creation will fail without modification to the database.

Parameters:

attachment (UploadAttachment) – Model of the attachment to create.
dataset_id (PID) – ID of the dataset to which the attachment belongs.

Raises:

scitacean.ScicatCommError – If SciCat refuses the attachment or communication fails for some other reason.

Return type:

DownloadAttachment

create_dataset_model(dset)[source]#

Create a new dataset in SciCat.

The dataset PID must be either

None, in which case SciCat assigns an ID,
an unused id, in which case SciCat uses it for the new dataset.

If the ID already exists, creation will fail without modification to the database. Unless the new dataset is identical to the existing one, in which case, nothing happens.

Parameters:: dset (UploadDerivedDataset | UploadRawDataset) – Model of the dataset to create.
Returns:: DownloadDataset – The uploaded dataset as returned by SciCat. This is the input plus some modifications.
Raises:: scitacean.ScicatCommError – If SciCat refuses the dataset or communication fails for some other reason.

create_orig_datablock(dblock, *, dataset_id)[source]#

Create a new orig datablock in SciCat.

The datablock PID must be either

None, in which case SciCat assigns an ID.
An unused id, in which case SciCat uses it for the new datablock.

If the ID already exists, creation will fail without modification to the database.

Parameters:

dblock (UploadOrigDatablock) – Model of the orig datablock to create.
dataset_id (PID) – PID of the dataset that this datablock belongs to.

Raises:

scitacean.ScicatCommError – If SciCat refuses the datablock or communication fails for some other reason.

Return type:

DownloadOrigDatablock

create_sample_model(sample)[source]#

Create a new sample in SciCat.

The sample ID must be either

None, in which case SciCat assigns an ID,
an unused id, in which case SciCat uses it for the new sample.

If the ID already exists, creation will fail without modification to the database. Unless the new sample is identical to the existing one, in which case, nothing happens.

Parameters:: sample (UploadSample) – Model of the sample to create.
Returns:: DownloadSample – The uploaded sample as returned by SciCat. This is the input plus some modifications.
Raises:: scitacean.ScicatCommError – If SciCat refuses the sample or communication fails for some other reason.

classmethod from_credentials(url, username, password, timeout=None)[source]#

Create a new low-level client and authenticate with username and password.

Parameters:

url (str) – URL of the SciCat api. It should include the suffix api/vn where n is a number.
username (str | StrStorage) – Name of the user.
password (str | StrStorage) – Password of the user.
timeout (timedelta | None, default: None) – Timeout for all API requests.

Returns:

ScicatClient – A new low-level client.

classmethod from_token(url, token, timeout=None)[source]#

Create a new low-level client and authenticate with a token.

Parameters:

url (str) – URL of the SciCat api.
token (str | StrStorage) – User token to authenticate with SciCat.
timeout (timedelta | None, default: None) – Timeout for all API requests.

Returns:

ScicatClient – A new low-level client.

get_attachments_for_dataset(pid, strict_validation=False)[source]#

Fetch all attachments from SciCat for a given dataset.

Parameters:

pid (PID) – Unique ID of the dataset. Must include the facility ID.
strict_validation (bool, default: False) – If True, the attachments must pass validation. If False, attachments are still returned if validation fails. Note that some fields may have a bad value or type. A warning will be logged if validation fails.

Returns:

list[DownloadAttachment] – Models of the attachments.

Raises:

scitacean.ScicatCommError – If communication fails.

get_dataset_model(pid, strict_validation=False)[source]#

Fetch a dataset from SciCat.

Parameters:

pid (PID) – Unique ID of the dataset. Must include the facility ID.
strict_validation (bool, default: False) – If True, the dataset must pass validation. If False, a dataset is still returned if validation fails. Note that some dataset fields may have a bad value or type. A warning will be logged if validation fails.

Returns:

DownloadDataset – A model of the dataset.

Raises:

scitacean.ScicatCommError – If the dataset does not exist or communication fails for some other reason.

get_orig_datablocks(pid, strict_validation=False)[source]#

Fetch all orig datablocks from SciCat for a given dataset.

Parameters:

pid (PID) – Unique ID of the dataset. Must include the facility ID.
strict_validation (bool, default: False) – If True, the datablocks must pass validation. If False, datablocks are still returned if validation fails. Note that some fields may have a bad value or type. A warning will be logged if validation fails.

Returns:

list[DownloadOrigDatablock] – Models of the orig datablocks.

Raises:

scitacean.ScicatCommError – If communication fails.

get_sample_model(sample_id, strict_validation=False)[source]#

Fetch a sample from SciCat.

Parameters:

sample_id (str) – ID of the sample to fetch.
strict_validation (bool, default: False) – If True, the sample must pass validation. If False, a sample is still returned if validation fails. Note that some fields may have a bad value or type. A warning will be logged if validation fails.

Returns:

DownloadSample – A model of the sample.

Raises:

scitacean.ScicatCommError – If the sample does not exist or communication fails for some other reason.

query_datasets(fields, *, limit=None, order=None, strict_validation=False)[source]#

Query for datasets in SciCat.

Attention

This function is experimental and may change or be removed in the future. It is currently unclear how best to implement querying because SciCat provides multiple, very different APIs and there are plans for supporting queries via Mongo query language directly.

See issue #177 for a discussion.

Parameters:

fields (dict[str, Any]) – Fields to query for. Returned datasets must match all fields exactly. See examples below.
limit (int | None, default: None) – Maximum number of results to return. Requires order to be specified. If not given, all matching datasets are returned.
order (str | None, default: None) – Specify order of results. For example, "creationTime:asc" and "creationTime:desc" return results in ascending or descending order in creation time, respectively.
strict_validation (bool, default: False) – If True, the datasets must pass validation. If False, datasets are still returned if validation fails. Note that some dataset fields may have a bad value or type. A warning will be logged if validation fails.

Returns:

list[DownloadDataset] – A list of dataset models that match the query.

Examples

Get all datasets belonging to proposal abc.123:

scicat_client.query_datasets({'proposalIds': ['abc.123']})

Get all datasets that belong to proposal abc.123 and have name "ds name": (The name and proposal must match exactly.)

scicat_client.query_datasets({
    'proposalIds': ['abc.123'],
    'datasetName': 'ds name'
})

Return only the newest 5 datasets for proposal bc.123:

scicat_client.query_datasets(
    {'proposalIds': ['bc.123']},
    limit=5,
    order="creationTime:desc",
)

validate_dataset_model(dset)[source]#

Validate a dataset in SciCat.

Parameters:: dset (UploadDerivedDataset | UploadRawDataset) – Model of the dataset to validate.
Raises:: ValueError – If the dataset does not pass validation.
Return type:: None

classmethod without_login(url, timeout=None)[source]#

Create a new low-level client without authentication.

The client can only download public datasets and not upload at all.

Parameters:

url (str) – URL of the SciCat api. It should include the suffix api/vn where n is a number.
timeout (timedelta | None, default: None) – Timeout for all API requests.

Returns:

ScicatClient – A new low-level client.