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

`call_endpoint`(*, cmd, url, operation[, ...])	Call a REST API endpoint of SciCat.
`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_proposal_model`(proposal)	Create a new proposal in SciCat.
`create_sample_model`(sample)	Create a new sample in SciCat.
`get_all_instrument_models`([strict_validation])	Fetch all available instruments from 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_instrument_model`(instrument_id[, ...])	Fetch an instrument from SciCat.
`get_orig_datablocks`(pid[, strict_validation])	Fetch all orig datablocks from SciCat for a given dataset.
`get_proposal_model`(proposal_id[, ...])	Fetch a proposal from SciCat.
`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.

call_endpoint(*, cmd, url, operation, data=None, params=None)[source]#

Call a REST API endpoint of SciCat.

This is a low-level function for raw API calls with SciCat. It calls a given endpoint with the stored credentials and base URL of this client. It returns the resulting JSON on success or raises a ScicatCommError on failure.

Parameters:

cmd (str) – HTTP command to use: “GET”, “POST”, etc.
url (str) – Relative URL to concatenate to the SciCat base URL.
operation (str) – A name for this operation. Used in error messages and logs.
data (BaseModel | None, default: None) – An optional Pydantic model to serialize and pass as the request body.
params (dict[str, str] | None, default: None) – Request params to encode in the URL.

Returns:

Any – The returned JSON if there is any, otherwise None.

Examples

Use the following to get a dataset by its PID.

from urllib.parse import quote_plus
ds_json = client.call_endpoint(
    cmd="get",
    url=f"datasets/{quote_plus(str(pid))}",
    operation="get_dataset_model",
)

Note the use quote_plus for the PID. You must ensure to properly escape all URL components.

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_proposal_model(proposal)[source]#

Create a new proposal in SciCat.

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

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_all_instrument_models(strict_validation=False)[source]#

Fetch all available instruments from SciCat.

Parameters:: 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:: list[DownloadInstrument] – A list of models of the instruments.
Raises:: scitacean.ScicatCommError – If communication fails.

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_instrument_model(instrument_id, strict_validation=False)[source]#

Fetch an instrument from SciCat.

Parameters:

instrument_id (str) – ID of the instrument 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:

DownloadInstrument – A model of the instrument.

Raises:

scitacean.ScicatCommError – If the instrument 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_proposal_model(proposal_id, strict_validation=False)[source]#

Fetch a proposal from SciCat.

Parameters:

proposal_id (str) – ID of the proposal 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:

DownloadProposal – A model of the proposal.

Raises:

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

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.

This Page

scitacean.client.ScicatClient#