Package: unicatdb
UniCatDB API libraryPython library for accessing API of the UniCatDB - Universal Catalog Database for biological findings.UniCatDB is a coherent yet flexible interdisciplinary storage solution for cataloging findings data of various research groups, focused mainly on green biology. Configurable by the researchers themselves, provides shared access enabling interoperability if desired, and is accessible by user-friendly interface on either desktop, laptop or tablet - both in the lab and on the go.Seewww.unicatdb.orgfor more details and contact.Getting startedInstall the library to your Python environment.Typically, for local Python on your desktop, run pip install command in shell:pipinstallunicatdbFor other environments, such as Jupiter notebook, see respective documentation for instructions on how to install pip packages.For example, in Jupiter notebook, paste this snippet the top (source:here for details):# Install a pip package in the current Jupyter kernelimportsys!{sys.executable}-mpipinstallunicatdbLogin to the UniCatDB (https://app.unicatdb.org)Obtain your API credentials (API key and Personal access token) - click on your profile in toolbar, then onAPI AccessbuttonUse credentials in API client configuration, see usage examples bellowStructureThe core of the library is in moduleunicatdb.opeapi_clientwhich consists of code generated via the modifiedOpenAPI Generatorand the interface corresponds to the UniCatDB API specifications available athttps://api.unicatdb.orgFor more convenient access, wrappers are provided inunicatdb.apimodule - this is your entrypoint for most common tasks.Usage examplesThe "Hello world"What this does:Get first ten findings from the databaseimportunicatdbfromtypingimportListfrompprintimportpprint# %% Paste your API key and Personal access token from https://account.unicatdb.org/configuration=unicatdb.Configuration(access_token='<PASTE YOUR API KEY TOKEN HERE>')# %% Query some datafromunicatdb.openapi_clientimportUserScopedTenant,FindingArrayResponsewithunicatdb.Client(configuration)asclient:# list my available workspaces (a.k.a tenants) ...my_workspaces:List[UserScopedTenant]=client.tenants.api_tenants_available_get()pprint(my_workspaces)# ... and if I have one, list some of it's findingifmy_workspaces:selected_workspace=my_workspaces[0]findings:FindingArrayResponse=client.findings.api_findings_get(selected_workspace.id)pprint(findings)Advanced query exampleWhat this does:Get only thename,amountanddynamic dataof the top 10 findings sorted byamountgreatest-first,
of which taxonomy's genus contains 'vulgare':importunicatdbfromtypingimportListfrompprintimportpprint# %% Paste your API key and Personal access token from https://app.unicatdb.org/configuration=unicatdb.Configuration(access_token='<PASTE YOUR API KEY TOKEN HERE>')# %% Query some data - e.g. apply filtering, sorting and paging during the API call to leave the heavy-lifting to the serverfromunicatdb.openapi_clientimportUserScopedTenant,FindingArrayResponse,FindingFieldsQuery,PageQuerywithunicatdb.Client(configuration)asclient:# list my available workspaces (a.k.a tenants) ...my_workspaces:List[UserScopedTenant]=client.tenants.api_tenants_available_get()pprint(my_workspaces)# ... and if I have one, list some of it's findingifmy_workspaces:selected_workspace=my_workspaces[0]filter_expressions={"taxonomyName.species":"like:vulgare"}fetch_only_fields=FindingFieldsQuery(findings="documentName,amount,dynamicData")findings:FindingArrayResponse=client.findings.api_findings_get(selected_workspace.id,sort="-amount",filter=filter_expressions,fields=fetch_only_fields,page=PageQuery(number=1,size=10))pprint(findings)Uploading attachments with TUS protocolPreferable method of uploading (large) files is to use UniCatDBTUS protocolendpoint.
The TUS protocol uses chunking and allows for resumable uploads.This library includes wrapper for official Python TUS clienttuspy.
For advanced usage, please refer totheir documentation.Simple TUS upload exampleWhat this does:Upload a JPEG image namedmy_image_attachment.jpgto specified Finding.importunicatdb# %% Paste your API key and Personal access token from https://account.unicatdb.org/configuration=unicatdb.Configuration(access_token='<PASTE YOUR API KEY TOKEN HERE>')# %% Upload a single file to a Findingwithunicatdb.Client(configuration)asclient:# suppose we already have some Finding in a workspacefinding_id="<PASTE TARGET FINDING ID HERE>"workspace_id="<PASTE TARGET WORKSPACE ID OF THE FINDING HERE>"# get prepared TUS protocol for uplading filestus_client=client.get_tus_client_for_finding(workspace_id,finding_id)# create uploader for our file, don't forget to provide required metadatauploader=tus_client.uploader('path/to/my_image_attachment.jpg',metadata={"fileName":"my_image_attachment.jpg","contentType":"image/jpeg"},chunk_size=unicatdb.Constants.DEFAULT_CHUNK_SIZE,# set chunk size in Bytes (1MB is the default)log_func=lambdamsg:print(msg)# optional - print the progress to console)# Uploads the entire file.# This uploads chunk by chunk.uploader.upload()Resumable TUS upload exampleWhat this does:Upload a video filevery_large_video_file.mp4to specified Finding with
ability to resume uploading if it was interrupted.importunicatdbfromtusclient.storageimportfilestoragefromtusclient.fingerprintimportfingerprint# %% Paste your API key and Personal access token from https://account.unicatdb.org/configuration=unicatdb.Configuration(access_token='<PASTE YOUR API KEY TOKEN HERE>')# %% Upload a single file to a Finding, with resume capability# To make upload resumable, first create file-based cache storagetus_storage=filestorage.FileStorage('tus_resumable_temp.json')tus_fingerprinter=fingerprint.Fingerprint()withunicatdb.Client(configuration)asclient:# suppose we already have some Finding in a workspacefinding_id="<PASTE TARGET FINDING ID HERE>"workspace_id="<PASTE TARGET WORKSPACE ID OF THE FINDING HERE>"# get prepared TUS protocol for uplading filestus_client=client.get_tus_client_for_finding(workspace_id,finding_id)# create uploader for our file, don't forget to provide required metadatauploader=tus_client.uploader('path/to/very_large_video_file.mp4',metadata={"fileName":"very_large_video_file.mp4","contentType":"video/mp4"},chunk_size=unicatdb.Constants.DEFAULT_CHUNK_SIZE,# set chunk size in Bytes (1MB is the default)log_func=lambdamsg:print(msg),# optional - print the progress to console# enable resumability:store_url=True,url_storage=tus_storage,fingerprinter=tus_fingerprinter)# Uploads the entire file.# This uploads chunk by chunk.uploader.upload()# (Now try force-stopping the script during upload, then restart it. The upload should continue where it left off)# clear uploaded file from cache on successfile_key=tus_fingerprinter.get_fingerprint(uploader.get_file_stream())tus_storage.remove_item(file_key)# (or simply remove the 'tus_resumable_temp.json' file)