Models

Record list

class RecordList(identifier, name, created_timestamp, created_user, published, is_revision, awaiting_approval, internal_use, description=None, notes=None, last_modified_timestamp=None, last_modified_user=None, published_timestamp=None, published_user=None, parent_record_list_identifier=None)

Describes a RecordList as obtained from the API.

Read-only - do not directly instantiate or modify instances of this class.

property name: str

Name of the Record List. Read-only.

Can be updated via update_list().

property description: str | None

Description of the Record List. Read-only.

Can be updated via update_list().

property notes: str | None

Notes about the Record List. Read-only.

Can be updated via update_list().

property identifier: str

Identifier of the Record List. Read-only.

property created_timestamp: datetime

Datetime at which the Record List was created. Read-only.

property created_user: UserOrGroup

User who created the Record List. Read-only.

property last_modified_timestamp: datetime | None

Datetime at which the Record List was last modified. Read-only.

property last_modified_user: UserOrGroup | None

User who last modified the Record List. Read-only.

property published_timestamp: datetime | None

Datetime at which the Record List was published. Read-only.

property published_user: UserOrGroup | None

User who published/withdrew the Record List. Read-only.

property published: bool

Whether the Record List has been published or not. Read-only.

property is_revision: bool

Whether the Record List is a revision. Read-only.

property awaiting_approval: bool

Whether the Record List is awaiting approval to be published or withdrawn. Read-only.

property internal_use: bool

Whether the Record List is for internal use only. Read-only.

Lists flagged as for internal use are periodically deleted from the system.

property parent_record_list_identifier: str | None

Identifier of the parent record list. Read-only.

Is populated if the record list is a revision of another record list.

Record list item

class RecordListItem(database_guid, table_guid, record_history_guid, record_version=None)

Describes a RecordList item, generally a reference to a record in a Granta MI database.

If this item was returned by the RecordListsApiClient.get_resolvable_list_items() method, then it guaranteed to be resolvable by the current user at the time it was generated. If this item was returned by the RecordListsApiClient.get_list_items() then it is not guaranteed to be resolvable and care should be taken to ensure that the reference to the record is valid before using it.

Parameters:

database_guidstr

GUID of the database.

table_guidstr

GUID of the table.

record_history_guidstr

Record History GUID.

record_versionint, optional

Record version number - for records in version-controlled tables. If provided, the requested version of the record is added to the list. If not provided, the list tracks the latest available version of the record.

property database_guid: str

Database GUID.

property table_guid: str

Table GUID.

property record_history_guid: str

Record History GUID.

property record_version: int | None

Record version number.

property record_guid: str | None

Record GUID.

Only populated if the RecordListItem has both been obtained via an API request and represents a specific version of a record. See the note on the record_version parameter for this class for more details.

User and user groups

class UserOrGroup

Description of a Granta MI User or Group.

Read-only - do not directly instantiate or modify instances of this class.

property identifier: str | None

Read-only identifier of the user or group.

property display_name: str | None

Read-only display name of the user or group.

property name: str | None

Read-only name of the user or group.

Search criteria

class SearchCriterion(name_contains=None, user_role=None, is_published=None, is_awaiting_approval=None, is_internal_use=None, is_revision=None, contains_records_in_databases=None, contains_records_in_integration_schemas=None, contains_records_in_tables=None, contains_records=None, user_can_add_or_remove_items=None)

Search criterion to use in a search_for_lists() operation.

The properties in this class represent an AND search - only lists that match all the non-null properties will be returned.

Examples

To filter record lists based on their name and status:

>>> criterion = SearchCriterion(
...     name_contains="Approved materials",
...     is_published=True,
... )

To filter record lists based on whether they include items from specific databases:

>>> criterion = SearchCriterion(
...     contains_records_in_databases=["9f6182ee-1f49-4ba9-9bd7-d4c0a392e94e"],
... )

To filter record lists based on whether they include items from specific tables:

>>> criterion = SearchCriterion(
...     contains_records_in_tables=["9f6182ee-1f49-4ba9-9bd7-d4c0a392e94e"],
... )

property name_contains: str | None

Limits results to lists whose name contains the provided string.

property user_role: UserRole | None

Limits results to lists on which the user has the specified role.

property is_published: bool | None

Limits results to lists with a specific publication status.

Set to True to include only record lists that are published. Set to False to include only record lists that are not published. Default value None will include both.

property is_awaiting_approval: bool | None

Limits results to lists with a specific approval status.

Set to True to include only record lists that are awaiting approval. Set to False to include only record lists that are not awaiting approval. Default value None will include both.

property is_internal_use: bool | None

Limits results to lists which are internal.

Set to True to include only internal record lists. Set to False to include only non-internal record lists. Default value None will include both.

property is_revision: bool | None

Limits results to lists which are revisions.

Set to True to include only record lists that are revisions of another list. Set to False to include only record lists that are not revisions. Default value None will include both.

property contains_records_in_databases: List[str] | None

Limits results to lists containing records in databases specified by GUIDs.

property contains_records_in_integration_schemas: List[str] | None

Limits results to lists containing records in integration schemas specified by GUIDs.

property contains_records_in_tables: List[str] | None

Limits results to lists containing records in tables specified by GUIDs.

property contains_records: List[str] | None

Limits results to lists containing records specified by their history GUIDs.

property user_can_add_or_remove_items: bool | None

Limits results to lists where the current user can add or remove items.

class BooleanCriterion(match_any=None, match_all=None)

Search criterion to use in a search operation search_for_lists().

Use this class to combine multiple SearchCriterion or BooleanCriterion objects together as either AND or OR searches. When both match_any and match_all are used together, results match all criterion from match_all AND at least one criterion from match_any.

Examples

Search record lists and obtain the union of multiple criteria (OR):

>>> criterion = BooleanCriterion(
...     match_any=[
...         SearchCriterion(name_contains="Approved materials"),
...         SearchCriterion(is_published=True),
...     ]
... )

Search record lists and obtain the intersection of multiple criteria (AND):

>>> criterion = BooleanCriterion(
...     match_all=[
...         SearchCriterion(name_contains="Approved materials"),
...         SearchCriterion(is_published=True),
...     ]
... )

property match_any: List[BooleanCriterion | SearchCriterion] | None

Limits results to lists which satisfy one or more provided criteria.

Returns:

list of BooleanCriterion | SearchCriterion, or None

property match_all: List[BooleanCriterion | SearchCriterion] | None

Limits results to lists which satisfy all provided criteria.

Returns:

list of BooleanCriterion | SearchCriterion, or None

class UserRole(value)

Roles a user can have on a record list.

Can be used in SearchCriterion.user_role.

NONE = 'None'

UserRole is currently only supported in searches. Searching for lists with user role = NONE as criteria would exclude all lists from the results.

OWNER = 'Owner'

SUBSCRIBER = 'Subscriber'

CURATOR = 'Curator'

ADMINISTRATOR = 'Administrator'

PUBLISHER = 'Publisher'

Search results

class SearchResult(record_list, items)

Describes the result of a search.

Read-only - do not directly instantiate or modify instances of this class.

property record_list: RecordList

Details of the record list associated with the search result.

property items: List[RecordListItem] | None

Items of the record list associated with the search result.

Will be None unless include_items has been specified in search_for_lists()