AccessGroupOperations¶
Access via client.access_groups. Project join requests: any signed-in user can ask to join a project, follow the request, and withdraw it. Project editors and above, and platform administrators, review requests and choose the role to grant, which must be below their own.
req = client.access_groups.request_join("thin-films", reason="XRD campaign")
queue = client.access_groups.list_join_requests(scope="reviewable", status="pending")
client.access_groups.approve_join_request(queue[0]["id"], role="viewer")
counts = client.access_groups.join_request_facets("project", scope="reviewable", status="pending")
crucible.resources.access_groups.AccessGroupOperations
¶
Operations for the project join-request workflow.
Access via: client.access_groups.*
request_join(project_ref, reason=None)
¶
Request to join a project. Any signed-in user who is not a member.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
project_ref
|
str
|
Project slug (project_id) or MFID. |
required |
reason
|
Optional[str]
|
Optional explanation for the request (at most 2000 characters). |
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 for this project, has too many pending requests, or the project is pending deletion. |
list_join_requests(group_name=None, status=None, requester_id=None, limit=DEFAULT_LIMIT, offset=0, privilege_mode=None, cursor=None, scope=None, project_mfid=None, reviewer_id=None, requested_after=None, requested_before=None, reviewed_after=None, reviewed_before=None, q=None, sort=None, direction=None)
¶
List join requests visible to the caller.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
group_name
|
Optional[str]
|
Removed in 4.0.0; passing it raises RemovedError. Use project_mfid. |
None
|
status
|
Optional[Union[str, Sequence[str]]]
|
One status or a list of them, from crucible.constants.JOIN_REQUEST_STATUSES. |
None
|
requester_id
|
Optional[str]
|
Only requests by this user (ORCID or MFID). |
None
|
limit
|
int
|
Maximum number of results (default 100, max 1000). |
DEFAULT_LIMIT
|
offset
|
int
|
Starting position in the full result set. |
0
|
privilege_mode
|
Optional[str]
|
Per-call privilege mode. Defaults to elevated for callers who can elevate, except with scope "submitted". |
None
|
cursor
|
str
|
Continuation token from a previous result's next_cursor; the listing resumes there. |
None
|
scope
|
Optional[str]
|
One of crucible.constants.JOIN_REQUEST_SCOPES. The server defaults to "accessible" (your own requests plus those you may review); "submitted" returns only yours and "reviewable" only those you may review. |
None
|
project_mfid
|
Optional[Union[str, Sequence[str]]]
|
One project MFID or a list of them. |
None
|
reviewer_id
|
Optional[str]
|
Only requests closed by this user. |
None
|
requested_after
|
Optional[TimeBound]
|
Only requests made at or after this time (datetime, date, or ISO 8601 string; naive values are UTC). |
None
|
requested_before
|
Optional[TimeBound]
|
Only requests made before this time. |
None
|
reviewed_after
|
Optional[TimeBound]
|
Only requests closed at or after this time. |
None
|
reviewed_before
|
Optional[TimeBound]
|
Only requests closed before this time. |
None
|
q
|
Optional[str]
|
Matches the requester's name, username, or ORCID. |
None
|
sort
|
Optional[str]
|
One of crucible.constants.JOIN_REQUEST_SORTS (server default: request_time). |
None
|
direction
|
Optional[str]
|
"asc" or "desc" (server default: desc). |
None
|
Returns:
| Type | Description |
|---|---|
List[Dict]
|
List[Dict]: Matching JoinRequest records. |
join_request_facets(field, limit=50, scope=None, status=None, project_mfid=None, requester_id=None, reviewer_id=None, requested_after=None, requested_before=None, reviewed_after=None, reviewed_before=None, q=None, privilege_mode=None)
¶
Count join requests by status, project, or requester.
Takes the same scope and filters as list_join_requests(). Buckets are ordered by count, largest first.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
field
|
str
|
One of crucible.constants.JOIN_REQUEST_FACET_FIELDS. |
required |
limit
|
int
|
Maximum number of buckets (default 50, max 200). |
50
|
Returns:
| Name | Type | Description |
|---|---|---|
Dict |
Dict
|
field, items (buckets with value, label, count, and a project or requester reference where applicable), limit. |
get(request_id)
¶
Fetch a single join request by ID.
Visible to its requester, to those who may review it, and to platform admins.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
request_id
|
int
|
Integer id of the JoinRequest. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Dict |
Optional[Dict]
|
The JoinRequest record, or None if it does not exist or is not visible to the caller. |
approve_join_request(request_id, reviewer_notes=None, role=None)
¶
Approve a pending join request. Project editors and above, or admin.
On approval, the requester is added to the project at role.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
request_id
|
int
|
Integer id of the JoinRequest to approve. |
required |
reviewer_notes
|
Optional[str]
|
Optional notes explaining the decision. |
None
|
role
|
Optional[str]
|
Role to grant, one of crucible.constants.PROJECT_MEMBER_ROLES and strictly below your own role in the project. The server defaults to contributor. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
Dict |
Dict
|
The updated JoinRequest record. |
Raises:
| Type | Description |
|---|---|
HTTPError 403
|
Not allowed to review, or the role is not below yours. |
HTTPError 409
|
Request is already closed, or the project is gone or pending deletion. |
reject_join_request(request_id, reviewer_notes=None)
¶
Reject a pending join request. Project editors and above, or admin.
No membership change occurs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
request_id
|
int
|
Integer id of the JoinRequest to reject. |
required |
reviewer_notes
|
Optional[str]
|
Optional notes explaining the decision. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
Dict |
Dict
|
The updated JoinRequest record. |
Raises:
| Type | Description |
|---|---|
HTTPError 409
|
Request is already closed. |
withdraw_join_request(request_id)
¶
Withdraw your own pending join request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
request_id
|
int
|
Integer id of the JoinRequest to withdraw. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Dict |
Dict
|
The updated JoinRequest record (status "withdrawn"). |
Raises:
| Type | Description |
|---|---|
HTTPError 403
|
Only the requester can withdraw. |
HTTPError 409
|
Request is already closed. |