citrine.resources.gemd_resource module

Collection class for generic GEMD objects and templates.

class citrine.resources.gemd_resource.GEMDResourceCollection(*args, dataset_id: UUID | None = None, session: Session | None = None, team_id: UUID | None = None, project_id: UUID | None = None)

Bases: DataConceptsCollection[DataConcepts]

A collection of any kind of GEMD objects/templates.

async_update(model: ResourceType, *, dry_run: bool = False, wait_for_response: bool = True, timeout: float = 120, polling_delay: float = 1.0, return_model: bool = False) → UUID | ResourceType | None

Update a particular element of the collection with data validation.

Update a particular element of the collection, doing a deeper check to ensure that the dependent data objects are still with the (potentially) changed constraints of this change. This will allow you to make bounds and allowed named/labels changes to templates.

Parameters:

model (ResourceType) – The DataConcepts object.
dry_run (bool) – Whether to actually update the item or run a dry run of the update operation. Dry run is intended to be used for validation. Default: false
wait_for_response (bool) – Whether to poll for the eventual response. This changes the return type (see below).
timeout (float) – How long to poll for the result before giving up. This is expressed in (fractional) seconds.
polling_delay (float) – How long to delay between each polling retry attempt.
return_model (bool) – Whether or not to return an updated version of the resource If wait_for_response is False, then this argument has no effect

Returns:

If wait_for_response if True, then this call will poll the backend, waiting for the eventual job result. In the case of successful validation/update, a return value of None is provided unless return_model is True, in which case the updated resource is fetched and returned. In the case of a failure validating or processing the update, an exception (JobFailureError) is raised and an error message is logged with the underlying reason of the failure.

If wait_for_response if False, A job ID (of type UUID) is returned that one can use to poll for the job completion and result with the poll_async_update_job() method.

Return type:

Optional[UUID]

batch_delete(id_list: List[LinkByUID | UUID | str | BaseEntity], *, timeout: float = 120, polling_delay: float = 1.0) → List[Tuple[LinkByUID, ApiError]]

Remove a set of GEMD objects.

You may provide GEMD objects that reference each other, and the objects will be removed in the appropriate order.

A failure will be returned if the object cannot be deleted due to an external reference.

All data objects must be associated with this dataset resource. You must also have write access on this dataset.

If you wish to delete more than 50 objects, queuing of deletes requires that the types of objects be known, and thus you _must_ provide ids in the form of BaseEntities.

Also note that Attribute Templates cannot be deleted at present.

Parameters:: id_list (List[Union[LinkByUID, UUID, str, BaseEntity]]) – A list of the IDs of data objects to be removed. They can be passed as a LinkByUID tuple, a UUID, a string, or the object itself. A UUID or string is assumed to be a Citrine ID, whereas a LinkByUID or BaseEntity can also be used to provide an external ID.
Returns:: A list of (LinkByUID, api_error) for each failure to delete an object. Note that this method doesn’t raise an exception if an object fails to be deleted.
Return type:: List[Tuple[LinkByUID, ApiError]]

build(data: dict) → DataConcepts

Build an arbitary GEMD object from a serialized dictionary.

This is an internal method, and should not be called directly by users.

Parameters:: data (dict) – A serialized data model object.
Returns:: A data model object built from the dictionary.
Return type:: DataConcepts

delete(uid: UUID | str | LinkByUID | BaseEntity, *, dry_run: bool = False)

Delete an element of the collection by its id.

Parameters:

uid (Union[UUID, str, LinkByUID, BaseEntity]) – A representation of the object (Citrine id, LinkByUID, or the object itself)
dry_run (bool) – Whether to actually delete the item or run a dry run of the delete operation. Dry run is intended to be used for validation. Default: false

get(uid: UUID | str | LinkByUID | BaseEntity) → ResourceType

Get an element of the collection by its id.

Parameters:: uid (Union[UUID, str, LinkByUID, BaseEntity]) – A representation of the object (Citrine id, LinkByUID, or the object itself)
Returns:: An object with specified scope and uid
Return type:: ResourceType

classmethod get_type() → Type[DataConcepts]: Return the resource type in the collection.

list(*, per_page: int | None = 100, forward: bool = True) → Iterator[ResourceType]

Get all visible elements of the collection.

The order of results should not be relied upon, but for now they are sorted by dataset, object type, and creation time (in that order of priority).

Parameters:

per_page (int, optional) – Max number of results to return per page. It is very unlikely that setting this parameter to something other than the default is useful. It exists for rare situations where the client is bandwidth constrained or experiencing latency from large payload sizes.
forward (bool) – Set to False to reverse the order of results (i.e., return in descending order)

Returns:

Every object in this collection.

Return type:

Iterator[ResourceType]

list_by_name(name: str, *, exact: bool = False, forward: bool = True, per_page: int = 100) → Iterator[ResourceType]

Get all objects with specified name in this dataset.

Parameters:

name (str) – case-insensitive object name prefix to search.
exact (bool) – Set to True to change prefix search to exact search (but still case-insensitive). Default is False.
forward (bool) – Set to False to reverse the order of results (i.e., return in descending order).
per_page (int) – Controls the number of results fetched with each http request to the backend. Typically, this is set to a sensible default and should not be modified. Consider modifying this value only if you find this method is unacceptably latent.

Returns:

List of every object in this collection whose name matches the search term.

Return type:

Iterator[ResourceType]

list_by_tag(tag: str, *, per_page: int = 100) → Iterator[ResourceType]

Get all objects bearing a tag prefixed with tag in the collection.

The order of results is largely not meaningful. Results from the same dataset will be grouped together but no other meaningful ordering can be relied upon. Duplication in the result set may (but needn’t) occur when one object has multiple tags matching the search tag. For this reason, it is inadvisable to put 2 tags with the same prefix (e.g., ‘foo::bar’ and ‘foo::baz’) in the same object when it can be avoided.

Parameters:

tag (str) – The prefix with which to search. Must fully match up to the first delimiter (ex. ‘foo’ and ‘foo::b’ both match ‘foo::bar’ but ‘fo’ is insufficient.
per_page (int) – Controls the number of results fetched with each http request to the backend. Typically, this is set to a sensible default and should not be modified. Consider modifying this value only if you find this method is unacceptably latent.

Returns:

Every object in this collection.

Return type:

Iterator[ResourceType]

poll_async_update_job(job_id: UUID, *, timeout: float = 120, polling_delay: float = 1.0) → None

Poll for the result of the async_update call.

This call will poll the backend given the Job ID that came from a call to async_update(), waiting for the eventual job result. In the case of successful validation/update, a return value of None is provided which indicates success. In the case of a failure validating or processing the update, an exception (JobFailureError) is raised and an error message is logged with the underlying reason of the failure.

Parameters:

job_id (UUID) – The job ID for the asynchronous update job we wish to poll.
timeout – How long to poll for the result before giving up. This is expressed in (fractional) seconds.
polling_delay – How long to delay between each polling retry attempt.

Returns:

This method will raise an appropriate exception if the job failed, else it will return None to indicate the job was successful.

Return type:

None

register(model: ResourceType, *, dry_run=False)

Create a new element of the collection or update an existing element.

If the input model has an ID that corresponds to an existing object in the database, then that object will be updated. Otherwise a new object will be created.

Only the top-level object in model itself is written to the database with this method. References to other objects are persisted as links, and the object returned by this method has all instances of data objects replaced by instances of LinkByUid. Registering an object which references other objects does NOT implicitly register those other objects. Rather, those other objects’ values are ignored, and the pre-existence of objects with their IDs is asserted before attempting to write model.

Parameters:

model (ResourceType) – The DataConcepts object.
dry_run (bool) – Whether to actually register the item or run a dry run of the register operation. Dry run is intended to be used for validation. Default: false

Returns:

A copy of the registered object as it now exists in the database.

Return type:

ResourceType

register_all(models: Iterable[DataConcepts], *, dry_run=False, status_bar=False, include_nested=False) → List[DataConcepts]

Register multiple GEMD objects to each of their appropriate collections.

Does so in an order that is guaranteed to store all linked items before the item that references them.

If the GEMD objects have no UIDs, Citrine IDs will be assigned to them prior to passing them on to the server. This is required as otherwise there is no way to determine how objects are related to each other. When the registered objects are returned from the server, the input GEMD objects will be updated with whichever uids & _citr_auto:: tags are on the returned objects. This means GEMD objects that already exist on the server will be updated with all their on-platform uids and tags.

This method has the same behavior as register, except that no models will be written if any one of them is invalid. Using this method should yield significant improvements to write speed over separate calls to register.

Parameters:

models (Iterable[DataConcepts]) – The data model objects to register. Can be different types.
dry_run (bool) – Whether to actually register the item or run a dry run of the register operation. Dry run is intended to be used for validation. Default: false
status_bar (bool) – Whether to display a status bar using the tqdm module to track progress in registration. Requires installing the optional tqdm module. Default: false
include_nested (bool) – Whether to just register the objects passed in the list, or include nested objects (e.g., obj.process, obj.spec.template, …). Default: false

Returns:

The registered versions

Return type:

List[DataConcepts]

update(model: ResourceType) → ResourceType

Update a data object model.

Update a particular element of the collection, first attempting a simple update using register and falling back to async_update if the changes require it (e.g., updating template bounds).

model: ResourceType: The DataConcepts object.