scitacean.Client#

class scitacean.Client(*, client, file_transfer)[source]#

SciCat client to communicate with a server.

Clients hold all information needed to communicate with a SciCat instance and a filesystem that holds data files (via file_transfer).

Use Client.from_token() or Client.from_credentials() to initialize a client instead of the constructor directly.

See the user guide for typical usage patterns. In particular, Downloading Datasets and Uploading Datasets.

Constructors

`from_credentials`(*, url, username, password)	Create a new client and authenticate with username and password.
`from_token`(*, url, token[, file_transfer])	Create a new client and authenticate with a token.
`without_login`(*, url[, file_transfer])	Create a new client without authentication.

Methods

`download_attachments_for`(target)	Download all attachments for a given object.
`download_files`(dataset, *, target[, select, ...])	Download files of a dataset.
`get_dataset`(pid[, strict_validation, ...])	Download a dataset from SciCat.
`get_sample`(sample_id[, strict_validation])	Download a sample from SciCat.
`upload_new_dataset_now`(dataset)	Upload a dataset as a new entry to SciCat immediately.
`upload_new_sample_now`(sample)	Upload a sample as a new entry to SciCat immediately.

Attributes

`file_transfer`	Stored handler for file down-/uploads.
`scicat`	Low-level client for SciCat.

download_attachments_for(target)[source]#

Download all attachments for a given object.

The target object must have an ID, that is, it must represent an entry in SciCat and not just a locally created object.

If the input already has attachments, they will be overwritten and a UserWarning will be raised.

Parameters:: target (Dataset) – Download attachments for this object.
Returns:: Dataset – A copy of the input dataset with attachments replaced with the downloaded models.

download_files(dataset, *, target, select=True, checksum_algorithm=None, force=False)[source]#

Download files of a dataset.

Makes selected files available on the local filesystem using the file transfer object stored in the client.

Parameters:

dataset (Dataset) – Download files of this dataset.
target (str | Path) – Files are stored to this path on the local filesystem.
select (bool | str | list[str] | tuple[str] | Pattern[str] | Callable[[File], bool], default: True) –
A file f is downloaded if select is
- True: downloaded
- False: not downloaded
- A string: if f.remote_path equals this string
- A list[str] or tuple[str]: if f.remote_path equals any of these strings
- An re.Pattern as returned by re.compile(): if this pattern matches f.remote_path using re.search()
- A Callable[File]: if this callable returns True for f
checksum_algorithm (str | None, default: None) – Select an algorithm for computing file checksums. The data block normally determines the algorithm, but this argument can override the stored value if the data block is broken or no algorithm has been set.
force (bool, default: False) – If True, download files regardless of whether they already exist locally. This bypasses the checksum computation of pre-existing local files.

Returns:

Dataset – A copy of the input dataset with files replaced to reflect the downloads. That is, the local_path of all downloaded files is set.

Examples

Download all files

client.download_files(dataset, target="./data", select=True)

Download a specific file

client.download_files(dataset, target="./data", select="my-file.dat")

Download all files with a nxs extension

import re
client.download_files(
    dataset,
    target="./data",
    select=re.compile(r"\.nxs$")
)
# or
client.download_files(
    dataset,
    target="./data",
    select=lambda file: file.remote_path.suffix == ".nxs"
)

property file_transfer: FileTransfer | None#: Stored handler for file down-/uploads.

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

Create a new 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.
file_transfer (FileTransfer | None, default: None) – Handler for down-/uploads of files.

Returns:

Client – A new client.

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

Create a new client and authenticate with a token.

Parameters:

url (str) – URL of the SciCat api.
token (str | StrStorage) – User token to authenticate with SciCat.
file_transfer (FileTransfer | None, default: None) – Handler for down-/uploads of files.

Returns:

Client – A new client.

get_dataset(pid, strict_validation=False, attachments=False)[source]#

Download a dataset from SciCat.

Does not download any files.

Parameters:

pid (str | PID) – ID of the dataset. Must include the prefix, i.e. have the form prefix/dataset-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.
attachments (bool, default: False) – Select whether to download attachments. If this is False, the attachments of the returned dataset are None. They can be downloaded later using Client.download_attachments_for().

Returns:

Dataset – A new dataset.

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

Download a sample from SciCat.

Parameters:

sample_id (str) – ID of the sample.
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 sample fields may have a bad value or type. A warning will be logged if validation fails.

Returns:

Sample – The downloaded sample.

property scicat: ScicatClient#

Low-level client for SciCat.

Should typically not be used by users of Scitacean!

upload_new_dataset_now(dataset)[source]#

Upload a dataset as a new entry to SciCat immediately.

The dataset is inserted as a new entry in the database and will never overwrite existing data.

Attachments are also uploaded automatically. This happens after the upload of files and the dataset itself. So if uploading the attachments fails, check the dataset in SciCat to determine which attachments you need to re-upload (using ScicatClient.create_attachment_for_dataset()).

Parameters:

dataset (Dataset) – The dataset to upload.

Returns:

Dataset – A copy of the input dataset with fields adjusted according to the response of the server.

Raises:

scitacean.ScicatCommError – If the upload to SciCat fails.
RuntimeError – If the file upload fails or if a critical error is encountered and some files or a partial dataset are left on the servers. Note the error message if that happens.

upload_new_sample_now(sample)[source]#

Upload a sample as a new entry to SciCat immediately.

The sample is inserted as a new entry in the database and will never overwrite existing data. To this end, the input sample’s ID is ignored and a new one is assigned automatically.

Parameters:: sample (Sample) – The sample to upload.
Returns:: Sample – A copy of the input sample with fields adjusted according to the response of the server.
Raises:: scitacean.ScicatCommError – If the upload to SciCat fails.

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

Create a new 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.
file_transfer (FileTransfer | None, default: None) – Handler for down-/uploads of files.

Returns:

Client – A new client.