Projects#

class ProjectAttachmentType[source]#

Bases: str, Enum

The type of attachment a file is for a project

other = 'other'#

__init__(*args, **kwds)#

class ProjectAttachment[source]#

Bases: ExternalFile

A file that has been uploaded to a project

Fields#
Field	Type	Required
`attachment_type`	`ProjectAttachmentType`	Yes
`created_on`	`datetime`	Yes
`description`	`str` \| `None`	Yes
`file_name`	`str`	Yes
`file_size`	`int`	Yes
`file_type`	`ExternalFileTypeEnum`	Yes
`id`	`int`	Yes
`provenance`	`dict`[`str`, `Any`]	Yes
`sha256sum`	`str`	Yes
`status`	`ExternalFileStatusEnum`	Yes
`tags`	`list`[`str`]	Yes

attachment_type: ProjectAttachmentType#

tags: list[str]#

download(destination_path, overwrite=False)#

Downloads an external file to the given path

The file size and checksum will be checked against the metadata stored on the server

Parameters:

destination_path (str) – Full path to the destination file (including filename)
overwrite (bool) – If True, allow for overwriting an existing file. If False, and a file already exists at the given destination path, an exception will be raised.

Return type:

None

get_direct_url()#

model_post_init(context, /)#

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

Return type:

None

propagate_client(client)#

id#

file_type#

created_on#

status#

file_name#

description#

provenance#

sha256sum#

file_size#

class ProjectQueryModel[source]#

Bases: RestModelBase

Fields#
Field	Type	Required	Default
`exclude`	`list`[`str`] \| `None`	No	`None`
`include`	`list`[`str`] \| `None`	No	`None`
`project_name`	`str` \| `None`	No	`None`

project_name: str | None#

include: list[str] | None#

exclude: list[str] | None#

class ProjectDeleteParams[source]#

Bases: RestModelBase

Fields#
Field	Type	Required	Default
`delete_dataset_records`	`bool`	No	`False`
`delete_datasets`	`bool`	No	`False`
`delete_records`	`bool`	No	`False`

Validators#
Validator	Mode	Fields
`validate_lists`	before	`delete_records`, `delete_datasets`, `delete_dataset_records`

delete_records: bool#

delete_datasets: bool#

delete_dataset_records: bool#

classmethod validate_lists(v)[source]#

class ProjectAddBody[source]#

Bases: RestModelBase

Fields#
Field	Type	Required	Default
`default_compute_priority`	`PriorityEnum`	Yes
`default_compute_tag`	`str`	Yes
`description`	`str`	Yes
`existing_ok`	`bool`	No	`False`
`extras`	`dict`[`str`, `Any`]	Yes
`name`	`str`	Yes
`tagline`	`str`	Yes
`tags`	`list`[`str`]	Yes

name: str#

description: str#

tagline: str#

tags: list[str]#

default_compute_tag: str#

default_compute_priority: PriorityEnum#

extras: dict[str, Any]#

existing_ok: bool#

class ProjectDatasetAddBody[source]#

Bases: RestModelBase

Fields#
Field	Type	Required	Default
`dataset_type`	`str`	Yes
`default_compute_priority`	`PriorityEnum`	Yes
`default_compute_tag`	`str`	Yes
`description`	`str`	Yes
`existing_ok`	`bool`	No	`False`
`extras`	`dict`[`str`, `Any`]	Yes
`name`	`str`	Yes
`provenance`	`dict`[`str`, `Any`]	Yes
`tagline`	`str`	Yes
`tags`	`list`[`str`]	Yes

dataset_type: str#

name: str#

description: str#

tagline: str#

tags: list[str]#

provenance: dict[str, Any]#

default_compute_tag: str#

default_compute_priority: PriorityEnum#

extras: dict[str, Any]#

existing_ok: bool#

class ProjectLinkDatasetBody[source]#

Bases: RestModelBase

Fields#
Field	Type	Required
`dataset_id`	`int`	Yes
`description`	`str` \| `None`	Yes
`name`	`str` \| `None`	Yes
`tagline`	`str` \| `None`	Yes
`tags`	`list`[`str`] \| `None`	Yes

dataset_id: int#

name: str | None#

description: str | None#

tagline: str | None#

tags: list[str] | None#

class ProjectUnlinkDatasetsBody[source]#

Bases: RestModelBase

Fields#
Field	Type	Required
`dataset_ids`	`list`[`int`]	Yes
`delete_dataset_records`	`bool`	Yes
`delete_datasets`	`bool`	Yes

dataset_ids: list[int]#

delete_datasets: bool#

delete_dataset_records: bool#

class ProjectRecordAddBody[source]#

Bases: RecordAddBodyBase

Fields#
Field	Type	Required	Default
`compute_priority`	`PriorityEnum`	Yes
`compute_tag`	`str`	Yes
`description`	`str`	Yes
`find_existing`	`bool`	No	`True`
`name`	`str`	Yes
`record_input`	`SinglepointInput` \| `OptimizationInput` \| `TorsiondriveInput` \| `GridoptimizationInput` \| `ReactionInput` \| `ManybodyInput` \| `NEBInput`	Yes
`tags`	`list`[`str`]	Yes

record_input: AllInputTypes#

name: str#

description: str#

tags: list[str]#

compute_tag#

compute_priority#

find_existing#

class ProjectRecordImportBody[source]#

Bases: RestModelBase

Fields#
Field	Type	Required
`description`	`str`	Yes
`name`	`str`	Yes
`record_data`	`FailedOperation` \| `AtomicResult` \| `OptimizationResult` \| `GenericTaskResult` \| `SinglepointRecord` \| `OptimizationRecord` \| `TorsiondriveRecord` \| `GridoptimizationRecord` \| `ReactionRecord` \| `ManybodyRecord` \| `NEBRecord`	Yes
`tags`	`list`[`str`]	Yes

record_data: AllResultTypes#

name: str#

description: str#

tags: list[str]#

class ProjectLinkRecordBody[source]#

Bases: RestModelBase

Fields#
Field	Type	Required
`description`	`str`	Yes
`name`	`str`	Yes
`record_id`	`int`	Yes
`tags`	`list`[`str`]	Yes

record_id: int#

name: str#

description: str#

tags: list[str]#

class ProjectUnlinkRecordsBody[source]#

Bases: RestModelBase

Fields#
Field	Type	Required	Default
`delete_records`	`bool`	Yes
`record_ids`	`list`[`int`]	Yes

record_ids: list[int]#

delete_records: bool#

class ProjectAttachmentUploadBody[source]#

Bases: ExternalFileUploadBase

Fields#
Field	Type	Required
`attachment_type`	`ProjectAttachmentType`	Yes
`description`	`str`	Yes
`file_name`	`str`	Yes
`provenance`	`dict`[`str`, `Any`]	Yes
`tags`	`list`[`str`]	Yes

attachment_type: ProjectAttachmentType#

tags: list[str]#

file_name#

description#

provenance#

class ProjectRecordMetadata[source]#

Bases: BaseModel

Information about a record contained in a project

This is the lightweight information about a record that a project stores, and does not include the record itself. Use Project.get_record() to obtain the full record.

Fields#
Field	Type	Required
`description`	`str`	Yes
`name`	`str`	Yes
`record_id`	`int`	Yes
`record_type`	`str`	Yes
`status`	`RecordStatusEnum`	Yes
`tags`	`list`[`str`]	Yes

record_id: int#

name: str#

description: str#

tags: list[str]#

record_type: str#

status: RecordStatusEnum#

class ProjectDatasetMetadata[source]#

Bases: BaseModel

Information about a dataset contained in a project

This is the lightweight information about a dataset that a project stores, and does not include the dataset itself. Use Project.get_dataset() to obtain the full dataset.

Fields#
Field	Type	Required
`dataset_id`	`int`	Yes
`dataset_type`	`str`	Yes
`description`	`str`	Yes
`name`	`str`	Yes
`tagline`	`str`	Yes
`tags`	`list`[`str`]	Yes

dataset_id: int#

dataset_type: str#

name: str#

description: str#

tagline: str#

tags: list[str]#

class ProjectQueryRecords[source]#

Bases: RestModelBase

Fields#
Field	Type	Required	Default
`record_id`	`list`[`int`]	Yes

record_id: list[int]#

class ProjectQueryDatasets[source]#

Bases: RestModelBase

Fields#
Field	Type	Required	Default
`dataset_id`	`list`[`int`]	Yes

dataset_id: list[int]#

class Project[source]#

Bases: BaseModel

A named collection of records, datasets, and files

A project groups together the records and datasets belonging to a single piece of work. Within a project, records and datasets are given names, and most methods here accept either that name or the underlying ID.

Fields#
Field	Type	Required	Default	Alias
`attachments_`	`list`[`ProjectAttachment`] \| `None`	No	`None`	`attachments`
`default_compute_priority`	`PriorityEnum`	Yes
`default_compute_tag`	`str`	Yes
`description`	`str`	Yes
`extras`	`dict`[`str`, `Any`]	Yes
`id`	`int`	Yes
`name`	`str`	Yes
`owner_user`	`str` \| `None`	Yes
`tagline`	`str`	Yes
`tags`	`list`[`str`]	Yes

id: int#

name: str#

description: str#

tagline: str#

tags: list[str]#

default_compute_tag: str#

default_compute_priority: PriorityEnum#

owner_user: str | None#

extras: dict[str, Any]#

attachments_: list[ProjectAttachment] | None#

property offline: bool#: True if this project is not connected to a server

assert_online()[source]#: Raises a RuntimeError if this project is not connected to a server

__init__(client=None, **kwargs)[source]#

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:: client (PortalClient | None)

propagate_client(client)[source]#

Propagates a client to this record to any fields within this record that need it

This may also be called from derived class propagate_client functions as well

property dataset_metadata: list[ProjectDatasetMetadata]#

Information about the datasets in this project

This is fetched from the server the first time it is accessed, and then cached. Use fetch_dataset_metadata() to fetch it again.

property record_metadata: list[ProjectRecordMetadata]#

Information about the records in this project

This is fetched from the server the first time it is accessed, and then cached. Use fetch_record_metadata() to fetch it again.

status()[source]#

Obtain a summary of the status of everything in this project

The returned dictionary has two keys - records and datasets. Each maps to a dictionary of record status to the number of records with that status. The records entry counts only the records added directly to the project; the datasets entry counts the records of all the datasets in the project, summed together.

Returns:: Counts of record statuses, split into records and datasets
Return type:: dict[str, dict[RecordStatusEnum, int]]

fetch_record_metadata()[source]#

Fetches information about the records in this project from the server

This overwrites what is stored locally, and is available through the record_metadata property.

add_record(name, record_input, *, description=None, tags=None, compute_tag=None, compute_priority=None, find_existing=True)[source]#

Creates a new record in this project and submits it for computation

Unlike the add_* methods of the client, this takes a single record input object (for example, a SinglepointInput) and creates a single record.

Parameters:

name (str) – Name to give this record within the project. Must be unique within the project
record_input (Annotated[SinglepointInput | OptimizationInput | TorsiondriveInput | GridoptimizationInput | ReactionInput | ManybodyInput | NEBInput, FieldInfo(annotation=NoneType, required=True, discriminator='record_type')]) – The specification and input molecule(s), as a record input object
description (str | None) – Optional longer description of this record
tags (list[str]) – Optional list of tags to attach to this record within the project
compute_tag (str | None) – The compute tag to use. Defaults to the project’s default_compute_tag
compute_priority (PriorityEnum | None) – The priority to run this computation at. Defaults to the project’s default_compute_priority
find_existing (bool) – If True, and a matching record already exists on the server, use that record rather than creating a new one. See Record Deduplication

Returns:

The new record, attached to the project and server

Return type:

BaseRecord

import_record(name, record, *, description=None, tags=None)[source]#

Imports an already-computed record into this project

The record is not run on this server - the existing results are stored as-is. This is used for ingesting records computed elsewhere (on another server, or by hand).

Parameters:

name (str) – Name to give this record within the project. Must be unique within the project
record (FailedOperation | AtomicResult | OptimizationResult | GenericTaskResult | SinglepointRecord | OptimizationRecord | TorsiondriveRecord | GridoptimizationRecord | ReactionRecord | ManybodyRecord | NEBRecord) – The completed record or result to import
description (str | None) – Optional longer description of this record
tags (list[str]) – Optional list of tags to attach to this record within the project

Returns:

The record, attached to the project and server

Return type:

BaseRecord

link_record(record_id, name, description, tags)[source]#

Adds an existing record on the server to this project

The record itself is not copied or modified - the project gains a reference to it, along with a project-local name, description, and tags.

Parameters:

record_id (int) – ID of an existing record on the server
name (str) – Name to give this record within the project. Must be unique within the project
description (str) – Longer description of this record
tags (list[str]) – List of tags to attach to this record within the project

Returns:

The linked record

Return type:

BaseRecord

unlink_records(record_ids, delete_records=False)[source]#

Removes records from this project

By default the records remain on the server and only the association with this project is removed.

Parameters:

record_ids (int | str | list[int | str]) – Record IDs or project-local record names to remove from the project
delete_records (bool) – If True, also delete the records themselves from the server

get_record(record_id, include=None)[source]#

Obtain a record contained in this project

Parameters:

record_id (int | str) – The record ID, or the name the record was given within this project
include (Sequence[str] | None) – Additional fields to include in the returned record

Returns:

The record, of the appropriate type for the computation

Return type:

BaseRecord

fetch_dataset_metadata()[source]#

Fetches information about the datasets in this project from the server

This overwrites what is stored locally, and is available through the dataset_metadata property.

add_dataset(dataset_type, name, description=None, tagline=None, tags=None, provenance=None, default_compute_tag=None, default_compute_priority=None, extras=None, existing_ok=False)[source]#

Creates a new dataset within this project

Parameters:

dataset_type (str) – The type of dataset to create (singlepoint, optimization, and so on)
name (str) – Name to give this dataset. Must be unique within the project
description (str | None) – Optional longer description of this dataset
tagline (str | None) – Optional short description of this dataset
tags (list[str] | None) – Optional list of tags to attach to this dataset
provenance (dict[str, Any] | None) – Optional dictionary describing the source of this dataset
default_compute_tag (str | None) – The default compute tag for computations submitted from this dataset. Defaults to the project’s default_compute_tag
default_compute_priority (PriorityEnum | None) – The default priority for computations submitted from this dataset. Defaults to the project’s default_compute_priority
extras (dict[str, Any] | None) – Optional dictionary of arbitrary additional information
existing_ok (bool) – If True, return the existing dataset if one with this name is already in the project, rather than raising an exception

Returns:

The new dataset, of the appropriate type for dataset_type

Return type:

BaseDataset

link_dataset(dataset_id, name=None, description=None, tagline=None, tags=None)[source]#

Adds an existing dataset on the server to this project

The dataset itself is not copied. The project gains a reference to it, optionally under a different name and description.

Parameters:

dataset_id (int) – ID of an existing dataset on the server
name (str | None) – Name to give this dataset within the project. If None, the dataset’s existing name is kept
description (str | None) – Longer description of this dataset. If None, the existing description is kept
tagline (str | None) – Short description of this dataset. If None, the existing tagline is kept
tags (list[str] | None) – List of tags for this dataset. If None, the existing tags are kept

Returns:

The linked dataset

Return type:

BaseDataset

unlink_datasets(dataset_ids, delete_datasets=False, delete_dataset_records=False)[source]#

Removes datasets from this project

By default the datasets remain on the server and only the association with this project is removed.

Parameters:

dataset_ids (int | str | list[int | str]) – Dataset IDs or project-local dataset names to remove from the project
delete_datasets (bool) – If True, also delete the datasets themselves from the server
delete_dataset_records (bool) – If True, also delete the records contained in those datasets

get_dataset(dataset_id)[source]#

Obtain a dataset contained in this project

Parameters:: dataset_id (int | str) – The dataset ID, or the name the dataset was given within this project
Returns:: The dataset, of the appropriate type for the dataset
Return type:: BaseDataset

fetch_attachments()[source]#

Fetches the metadata for this project’s attachments from the server

This overwrites what is stored locally, and is available through the attachments property.

property attachments: list[ProjectAttachment]#

The files that have been uploaded to this project

This is fetched from the server the first time it is accessed, and then cached. The returned objects contain only the file metadata - use download() to obtain the contents.

upload_attachment(file_path, attachment_type, tags, description=None, provenance=None, new_file_name=None)[source]#

Uploads a file to this project

Parameters:

file_path (str) – Path to the local file to upload
attachment_type (ProjectAttachmentType) – The kind of attachment this is. Currently only other is available
tags (list[str]) – List of tags to attach to this file
description (str | None) – Optional longer description of this file
provenance (dict[str, Any] | None) – Optional dictionary describing the source of this file
new_file_name (str | None) – Store the file under this name instead of the base name of file_path

Returns:

ID of the newly-created attachment

Return type:

int

delete_attachment(file_id)[source]#

Deletes an attachment from this project

Parameters:: file_id (int) – ID of the attachment to delete

model_post_init(context, /)#

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

Return type:

None