Upgrading to 4.0¶
nano-crucible 4.0 removes everything that 3.x deprecated, follows the Crucible API 4.0 contract, and changes a few defaults. This page lists what existing scripts and habits need to change; the changelog has every change.
Before you upgrade¶
- Use Python 3.11 or later.
- Use a Crucible API at version 4.0 or later. The client relies on routes that older servers lack, such as signed multipart uploads, project join requests, instrument members, and
owner_ref; keep nano-crucible 3.3 for a 3.x server. - Run your scripts on 3.3 with
python -W default::DeprecationWarning. Every method and keyword it warns about is removed in 4.0; the few removals that never warned are listed below.
Removed¶
Calling a removed method, keyword, or setting raises crucible.RemovedError, a TypeError whose message names the replacement. Removed CLI commands and options stop with the one to use; the CLI reference lists them.
These were removed without an earlier deprecation:
| Removed | Use instead |
|---|---|
datasets.request_carrier_segmentation(), request_insitu_aggregation(), request_rga_analysis(), request_mosaic_stitch() |
datasets.postprocess(dataset_mfid, pipeline) |
users.verify_api_key() |
users.get(user)['api_key_status'] |
instruments.set_access(), instruments.revoke_access() |
instruments.add_user(), update_user_role(), remove_user() |
upload_file_gcs_multipart(), upload_file_gcs_resumable() |
upload_file_gcs(), or datasets.add_file() |
google-cloud-storage, installed with nano-crucible |
install it yourself if your code imports it |
| The basic shell used when prompt_toolkit is missing | reinstall nano-crucible |
The settings graph_explorer_url, current_session, upload_protocol, and upload_chunk_size_mb are ignored; config show lists them and config unset removes them. Setting CRUCIBLE_CURRENT_PROJECT stops the CLI; pass --project-id instead.
Results with a new shape¶
- Instrument member methods and
Instrument.membersreturnProjectMemberrecords (username, name, role) instead ofAccessGrantrecords. samples.get()andclient.get()no longer include a sample's datasets. Passinclude_links=True, or calldatasets.list(sample_mfid=...).datasets.create()results name the new datasetdataset_mfidinstead ofdsid, andget_links()results usedirectioninstead ofrelationship.AccessGrantexposesprincipal_id,principal_type, andpermissioninstead ofprincipal,kind, andeffective_permission.- Records carry nested
owner,project, andinstrumentreferences. The API deprecates the flatowner_orcid,project_id,instrument_id, andinstrument_nameresponse fields, andleadandproject_lead_orcidon projects. - API errors raise
crucible.CrucibleAPIErrorwithstatus,code,detail, andrequest_id. It is arequests.HTTPError, so existingexceptblocks still catch it. A client created without an API key or stored sign-in raisescrucible.NotSignedInError, aValueErroras before.
New defaults¶
- Instrument
add_user()andinstrument add-usergive new membersviewerinstead ofeditor. - A signed-in platform administrator runs in normal mode; an administrator's API key still runs elevated. Set
privilege_modeto choose explicitly, and checkclient.is_elevatedorcrucible whoami. - Create and update requests (POST and PATCH) without an
Idempotency-Keyare not retried after a 502, 503, 504, or lost response, so a retry cannot create a duplicate record. - Links and
crucible opengo to the Crucible Hub (hub_url) instead of the Graph Explorer. - A cast recipe's
instrumentis an instrument ID or MFID, not a name.
Renamed, still working¶
Old names keep working with a warning (a DeprecationWarning in Python, a notice on stderr in the CLI) and will be removed in a later release. The ones scripts meet most often:
| Old | New |
|---|---|
owner_id, owner_id_is_null filters |
owner_ref (up to 10 owners), owner_is_null |
project_lead, project_lead_orcid, project_lead_email, project_lead_username on project create |
owner |
project create --lead |
project create --owner |
datasets.graph(), samples.graph() |
graphs.get() |
include_datasets=True on samples.get() |
include_links=True |
The changelog's "Changed" section lists the remaining method, parameter, and command renames.