InstrumentOperations¶
Access via client.instruments.
Store instruments by MFID (unique_id). The instrument slug (instrument_id) is for human lookup and ignores case; every method that takes an instrument reference accepts either. instrument_name is free-text display, may repeat, and must not be used to identify an instrument.
Instrument members work like project members (list_users(), add_user(), remove_user(), update_user_role(), each returning ProjectMember records): every member reads the instrument's datasets, editor also edits details, and admin also changes status, binds service accounts, and manages members. Service accounts are bound with bind_service_account() instead. set_access() and revoke_access() raise RemovedError for instruments; list_access(), set_public(), and set_private() still work.
crucible.resources.instruments.InstrumentOperations
¶
Instrument-related API operations.
Access via: client.instruments.get(), client.instruments.list(), etc.
list(include_metadata=False, limit=DEFAULT_LIMIT, offset=0, include_owner=False, status=None, affiliation=None, sort=None, direction=None, cursor=None, mfid=None, **filters)
¶
List instruments, defaulting to the active lifecycle state.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
include_metadata
|
bool
|
Include scientific metadata in results |
False
|
limit
|
int
|
Maximum number of results to return |
DEFAULT_LIMIT
|
offset
|
int
|
Starting position in the full result set (default: 0) |
0
|
cursor
|
str
|
Continuation token from a previous result's next_cursor; the listing resumes there. |
None
|
include_owner
|
bool
|
Resolve the owner into a public-safe user object |
False
|
status
|
str
|
Filter by active, maintenance, or decommissioned. When omitted, the API defaults to active (or every status for an instrument_id lookup). |
None
|
affiliation
|
Optional[Union[str, Sequence[str]]]
|
Caller relationship: 'owner', 'maintainer' (editor or admin member), or 'member' (any role), combined with OR, to list the caller's instruments. |
None
|
sort
|
Optional[str]
|
Explicit ordering, one of crucible.constants.INSTRUMENT_SORTS. |
None
|
direction
|
Optional[str]
|
Sort direction, asc or desc. Requires sort. Without it, dates default to desc and everything else to asc. |
None
|
mfid
|
str or list
|
Only these instrument MFIDs (up to 100). |
None
|
**filters
|
Any
|
Exact-match filters accepted by GET /instruments, such as instrument_id (case-insensitive slug), manufacturer, model, location, instrument_type, owner_ref (up to 10 owners), other_id. |
{}
|
Returns:
| Type | Description |
|---|---|
List[Dict]
|
List[Dict]: Instrument objects with specifications, the caller's
effective |
get(instrument_ref=None, instrument_id=None, include_metadata=False, include_owner=True, *, instrument_mfid=None, instrument_name=None, include_members=False)
¶
Get an instrument by canonical MFID or human-readable slug.
instrument_id explicitly selects the human-readable API identifier.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
instrument_ref
|
str
|
Instrument MFID or slug |
None
|
instrument_id
|
str
|
Explicit instrument slug |
None
|
include_metadata
|
bool
|
Whether to include scientific metadata |
False
|
include_owner
|
bool
|
Resolve the owner into a public-safe user object (default: True) |
True
|
instrument_mfid
|
str
|
Explicit instrument MFID |
None
|
instrument_name
|
str
|
Removed in 4.0.0; passing it raises RemovedError. |
None
|
include_members
|
bool
|
Include the members, owner first, as
|
False
|
Returns:
| Type | Description |
|---|---|
Optional[Dict]
|
Dict or None: Instrument information if found, None otherwise |
Raises:
| Type | Description |
|---|---|
ValueError
|
If no reference or multiple references are provided |
search(q, limit=20, include_owner=False, status=None, affiliation=None, owner_ref=None)
¶
Fuzzy search across instruments. Available to all authenticated users.
Matches against instrument_name, instrument_type, and manufacturer (best score across the three).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
q
|
str
|
Search term (min 3 chars). Typo-tolerant. |
required |
limit
|
int
|
Max results (default 20, max 50). |
20
|
include_owner
|
bool
|
Resolve the owner into a public-safe user object. |
False
|
status
|
Optional[str]
|
Restrict results to active, maintenance, or decommissioned. |
None
|
affiliation
|
Optional[Union[str, Sequence[str]]]
|
'owner', 'maintainer' (editor or admin member), or 'member' (any role), to search only the caller's instruments. |
None
|
owner_ref
|
Optional[Union[str, Sequence[str]]]
|
Owner or owners (up to 10, any matches): unique_id, linked ORCID, username, or email. |
None
|
Returns:
| Type | Description |
|---|---|
List[Dict]
|
List[Dict]: Matching instrument records, ranked by relevance. |
create(instrument, scientific_metadata=None)
¶
Create a new instrument as an authenticated human caller.
Service accounts cannot create instruments. If the instrument already exists, this method returns the existing record.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
instrument
|
Union[Instrument, Dict]
|
Instrument model or dict with instrument details. Required fields: instrument_id, instrument_name, and location. Owner defaults to the authenticated identity. |
required |
scientific_metadata
|
Dict
|
Scientific metadata to attach after creation. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
Dict |
Dict
|
Created (or existing) instrument object |
Raises:
| Type | Description |
|---|---|
ValueError
|
If instrument_id is missing |
update(instrument_ref, **kwargs)
¶
Partially update an instrument record.
Requires editor permission.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
instrument_ref
|
str
|
Instrument unique identifier (MFID) |
required |
**kwargs
|
Any
|
Fields to update. Accepted: instrument_id, instrument_name, location, manufacturer, model, instrument_type, description, other_id, other_id_source. |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
Dict |
Dict
|
Updated instrument object |
set_status(instrument_mfid, status)
¶
Change an instrument lifecycle status.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
instrument_mfid
|
str
|
Instrument unique identifier (MFID) |
required |
status
|
str
|
One of active, maintenance, or decommissioned |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Dict |
Dict
|
Updated instrument response |
list_users(instrument_ref, limit=DEFAULT_LIMIT, offset=0, cursor=None)
¶
List the instrument's members, highest role first, owner first.
Every member reads the datasets assigned to the instrument.
Returns:
| Type | Description |
|---|---|
Optional[List[ProjectMember]]
|
List[ProjectMember] or None: None when the caller is not a member |
Optional[List[ProjectMember]]
|
and not a platform administrator. |
add_user(instrument_ref, user, role='viewer')
¶
Add a member: 'viewer' reads the instrument's datasets, 'editor' also edits details, 'admin' also changes status, binds service accounts, and manages members.
Requires admin on the instrument; you cannot grant above your own role.
user accepts an ORCID, MFID, or username; service accounts are
bound with bind_service_account() instead.
Returns:
| Type | Description |
|---|---|
List[ProjectMember]
|
List[ProjectMember]: The instrument's members after the change. |
remove_user(instrument_ref, user)
¶
Remove a member. Requires admin on the instrument, except to remove yourself. Returns the remaining members.
update_user_role(instrument_ref, user, role)
¶
Change a member's role (same rules as add_user()). Returns the members.
list_service_accounts(instrument_mfid)
¶
List service accounts bound to an instrument.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
instrument_mfid
|
str
|
Instrument unique identifier (MFID) |
required |
Returns:
| Type | Description |
|---|---|
List[ProjectMember]
|
List[ProjectMember]: Bound service accounts and their operator roles |
bind_service_account(instrument_ref, service_account_ref)
¶
Bind a service account as an operator of an instrument.
Requires admin on the instrument (its owner or an admin member). A bound service account gets contributor on every dataset assigned to the instrument.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
instrument_ref
|
str
|
Instrument unique identifier (MFID) |
required |
service_account_ref
|
str
|
Service account unique identifier (MFID) |
required |
Returns:
| Type | Description |
|---|---|
List[ProjectMember]
|
List[ProjectMember]: The instrument's operator group members |
unbind_service_account(instrument_ref, service_account_ref)
¶
Remove a service account as an operator of an instrument.
Requires admin on the instrument (its owner or an admin member).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
instrument_ref
|
str
|
Instrument unique identifier (MFID) |
required |
service_account_ref
|
str
|
Service account unique identifier (MFID) |
required |
Returns:
| Type | Description |
|---|---|
List[ProjectMember]
|
List[ProjectMember]: The instrument's operator group members |
list_access(mfid)
¶
List every principal with access to a resource.
Readable by anyone with a role on the resource (not through public
access alone); the resource's capabilities.can_view_access says
whether you can. Each grant's capabilities says whether you may
remove it or change its role, and to which roles.
set_public(mfid)
¶
Grant public viewer access to a resource.
set_private(mfid)
¶
Revoke public access to a resource.
transfer_ownership(mfid, new_owner, confirm=False)
¶
Preview or apply a resource ownership transfer.