ProjectOperations¶
Access via client.projects.
crucible.resources.projects.ProjectOperations
¶
Project-related API operations.
Access via: client.projects.get(), client.projects.list(), etc.
get(project_ref=None, include_metadata=False, include_members=False, project_id=None, project_mfid=None)
¶
Get a project by canonical MFID or human-readable project slug.
The response always includes project_id, organization, status, title.
The lead field is a public-safe user record containing canonical
identity, username, and name, but never email.
scientific_metadata is only ever populated for members/admins —
include_metadata is silently ignored for non-members. Same gating
applies to members (list of {unique_id, username, first_name,
last_name, role}) with include_members - non-members always get
members: None regardless of the flag.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
project_ref
|
str
|
Project MFID or project slug. Lookup accepts legacy slugs outside the current write limits. |
None
|
project_id
|
str
|
Explicit project slug |
None
|
project_mfid
|
str
|
Explicit project MFID |
None
|
include_metadata
|
bool
|
Whether to include scientific metadata (members/admins only) |
False
|
include_members
|
bool
|
Whether to include the member list (members/admins only) |
False
|
Returns:
| Name | Type | Description |
|---|---|---|
Dict |
Dict
|
Project information, with membership-gated fields as described above |
list(orcid=None, include_metadata=False, limit=DEFAULT_LIMIT, offset=0, accessible_to_user=None, accessible_to_project=None, sort=None, direction=None, member_ref=None, member_role=None, cursor=None, mfid=None, owner_ref=None)
¶
List all accessible projects.
Each project dict includes an owner key with the owner's
public-safe user record and a role key with the caller's
membership role (None when the project is only visible through
platform role or resource grants).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
orcid
|
Optional[str]
|
Removed in 4.0.0; passing it raises RemovedError. Use member_ref or client.users.list_projects(). |
None
|
include_metadata
|
bool
|
Include scientific metadata in results |
False
|
limit
|
int
|
Maximum number of results to return (default: 100) |
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
|
accessible_to_user
|
Optional[Union[str, Sequence[str]]]
|
User reference or references whose effective access must include every result |
None
|
accessible_to_project
|
Optional[Union[str, Sequence[str]]]
|
Project reference or references whose direct access must include every result |
None
|
sort
|
Optional[str]
|
Explicit ordering, one of crucible.constants.PROJECT_SORTS. |
None
|
direction
|
Optional[str]
|
Sort direction, asc or desc. Requires sort. Without it, dates default to desc and everything else to asc. |
None
|
member_ref
|
Optional[Union[str, Sequence[str]]]
|
User reference or references (ORCID, service-account MFID, username, or email) whose membership must include every result. Repeated values use AND semantics. |
None
|
member_role
|
Optional[Union[str, Sequence[str]]]
|
Restrict member_ref to these project roles. Repeated values use OR semantics and require member_ref. |
None
|
mfid
|
Optional[Union[str, Sequence[str]]]
|
Only these project MFIDs (up to 100). Applies to /projects only. Unreadable or missing MFIDs are left out. |
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]: Project metadata including project_id, title, organization, owner, role |
create(project, scientific_metadata=None)
¶
Create a new project.
Any authenticated user may create a project they own; only platform administrators may name someone else as the owner.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
project
|
Union[Project, Dict]
|
A Project model instance or a dict with project_id, organization, and owner (ORCID, MFID, username, or email). The project_lead* fields still work but are deprecated. |
required |
scientific_metadata
|
Dict
|
Scientific metadata to attach after creation. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
Dict |
Dict
|
Created project object |
Example
from crucible.models import Project project = Project( ... project_id="my-project", ... organization="Molecular Foundry", ... owner="lead@lbl.gov" ... ) result = client.projects.create(project)
update(proj_id, **kwargs)
¶
Partially update a project record.
Requires admin permissions.
Leadership changes are not accepted here (422) - use transfer_ownership() instead, which moves owner standing and the denormalized lead pointer atomically.
Note the identifying parameter is named proj_id, not project_id -
project_id is itself now a valid field in **kwargs (it renames the
project), and the two would collide if both were named the same.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
proj_id
|
str
|
Unique project identifier |
required |
**kwargs
|
Any
|
Fields to update. Accepted: project_id (renames the project), organization, status, title. |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
Dict |
Dict
|
Updated project object |
search(q, limit=20, owner_ref=None)
¶
Fuzzy search across all projects (not just the caller's). Available to all authenticated users — supports project discovery ahead of request_join().
Matches against both title and project_id. Results never include lead or scientific_metadata, regardless of membership.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
q
|
str
|
Search term (min 3 chars). Typo-tolerant. |
required |
limit
|
int
|
Max results (default 20, max 50). |
20
|
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 ProjectRead records, ranked by relevance. |
list_users(project_id, limit=DEFAULT_LIMIT, offset=0, cursor=None)
¶
Get users associated with a project.
Requires admin permissions.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
project_id
|
str
|
Unique project identifier |
required |
limit
|
int
|
Maximum number of results to return (default: 100) |
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
|
Returns:
| Type | Description |
|---|---|
List[ProjectMember]
|
List[ProjectMember]: Project team members (excludes project lead) |
add_user(user_ref=None, project_id=None, email=None, username=None, role=None)
¶
Add a user to a project.
Requires editor or above in the project. The granted role must be strictly below the caller's role. Editors may grant contributor or viewer, admins may also grant editor, and owners may also grant admin. Platform administrators retain their bypass. Ownership changes use transfer_ownership().
Email and username inputs are resolved before the canonical membership request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
user_ref
|
str
|
Canonical user ORCID or MFID |
None
|
project_id
|
str
|
Unique project identifier |
None
|
email
|
str
|
User's email address |
None
|
username
|
str
|
User's username |
None
|
role
|
str
|
Role to grant (default: contributor) |
None
|
Returns:
| Type | Description |
|---|---|
List[ProjectMember]
|
List[ProjectMember]: Updated list of project users |
update_user_role(project_id, user_ref, role)
¶
Change a member's role in a project.
Requires editor or above in the project. Both the member's current role and their requested role must be strictly below the caller's role. Platform administrators retain their bypass. Ownership changes use transfer_ownership().
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
project_id
|
str
|
Unique project identifier |
required |
user_ref
|
str
|
Canonical user ORCID or MFID |
required |
role
|
str
|
New role to grant |
required |
Returns:
| Type | Description |
|---|---|
List[ProjectMember]
|
List[ProjectMember]: Updated list of project users |
remove_user(project_id, user_ref=None, email=None, username=None)
¶
Remove a user from a project.
Project owners and platform administrators may remove members. A member may also remove themselves.
Email and username inputs are resolved before the canonical membership request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
project_id
|
str
|
Unique project identifier |
required |
user_ref
|
str
|
Canonical user ORCID or MFID |
None
|
email
|
str
|
User's email address |
None
|
username
|
str
|
User's username |
None
|
Returns:
| Type | Description |
|---|---|
List[ProjectMember]
|
List[ProjectMember]: Updated list of project users |
request_join(project_id, reason=None)
¶
Request to join this project. Any authenticated user.
Delegates to client.access_groups.request_join() — see there for full list/approve/reject operations on join requests.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
project_id
|
str
|
Project slug or MFID. |
required |
reason
|
Optional[str]
|
Optional explanation for the request. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
Dict |
Dict
|
The created JoinRequest record (status will be "pending"). |
Raises:
| Type | Description |
|---|---|
HTTPError 404
|
Project doesn't exist. |
HTTPError 409
|
Already a member, already has a pending request, or the project is pending deletion. |
list_join_requests(project_id, status=None, limit=DEFAULT_LIMIT, offset=0, **filters)
¶
List join requests for this project visible to the caller.
Project editors and above (and platform admins) see every request; others see only their own. Delegates to client.access_groups.list_join_requests(project_mfid=...), which takes the other filters and sorts.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
project_id
|
str
|
Project slug or MFID. |
required |
status
|
Optional[str]
|
One status or a list of them, from crucible.constants.JOIN_REQUEST_STATUSES. |
None
|
limit
|
int
|
Maximum number of results. |
DEFAULT_LIMIT
|
offset
|
int
|
Starting position in the full result set. |
0
|
**filters
|
Any
|
Any other list_join_requests() keyword, such as scope, sort, direction, or cursor. |
{}
|
Returns:
| Type | Description |
|---|---|
List[Dict]
|
List[Dict]: Matching JoinRequest records, most recent first. |
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_access(mfid, kind, principal, permission)
¶
Grant or change a principal's non-owner access to a resource.
revoke_access(mfid, kind, principal)
¶
Revoke a principal's access to a resource.
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.