clio-py: Python client for clio-store
Install
$ pip3 install git+https://github.com/schlegelp/clio-py@main
Token
To access Clio programmatically you need an API token. You can get and set your token in a few ways — the first is recommended and requires no extra dependencies.
Option 1 (recommended): clio.login()
Run clio.login(). This opens the Clio settings page in your browser so you can
copy your token (the "ClioStore Token"), then prompts you to paste it. The token
is saved to disk, so this is a one-off until it expires:
>>> import clio
>>> clio.login() # opens the browser and prompts you to paste your token
>>> client = clio.Client(dataset='VNC')
Option 2: pass or save the token yourself
Get your token from the Clio website (settings in the top right → "ClioStore Token") and either pass it directly:
>>> import clio
>>> client = clio.Client(dataset='VNC', token="eyJhb.....")
...or save it to disk once so it's picked up automatically:
>>> import clio
>>> clio.set_token("eyJhb.....") # one-off until the token expires
>>> client = clio.Client(dataset='VNC')
Option 3 (advanced): auto-refresh via gcloud
If you have the gcloud CLI
installed and linked to the Google account you use for Clio, clio-py will use
it to fetch and refresh your token automatically. This is convenient for
long-running/automated use but installing gcloud is a heavy dependency most
users won't need.
>>> import clio
>>> client = clio.Client(dataset='VNC') # uses gcloud if a token isn't already saved
Usage
Setup
>>> import clio
>>> # You can get a list of available datasets by just invoking the client
>>> clio.Client()
...
RuntimeError: Please specify a dataset from the following list: ['CNS', 'MANC', 'VNC', 'hemibrain', 'manc:v1.0', 'medulla7column']
>>> # Initialize client with a specific dataset
>>> client = clio.Client(dataset='VNC')
Pulling annotations
>>> # Fetch annotations for given ID(s)
>>> clio.fetch_annotations([154109])
hemilineage long_tract description user soma_side ... to_review bodyid entry_nerve soma_neuromere position
0 7B 7B in T3 LHS xxxxxxxxxx@gmail.com LHS ... 154109 None T3 [17429, 21568, 21811]
>>> # Fetch annotations by a given field
>>> clio.fetch_annotations(hemilineage='07B')
avg_location birthtime bodyid ... transmission old_bodyids tosoma_position
0 18910, 35515, 55240 primary 10010 ... NaN NaN NaN
1 26128, 38807, 55528 primary 10018 ... NaN NaN NaN
2 15749, 33362, 38398 primary 10087 ... NaN NaN NaN
3 26128, 38807, 55528 primary 10090 ... NaN NaN NaN
4 NaN early secondary 10148 ... NaN NaN NaN
...
>>> # Fetch all annotations
>>> clio.fetch_annotations()
avg_location birthtime bodyid ... subclassabbr tosoma_position source
0 20293, 15901, 10843 secondary 26896 ... NaN NaN NaN
1 NaN NaN 139486 ... NaN NaN NaN
2 27443, 20049, 23897 secondary 158190 ... NaN NaN NaN
3 16884, 19674, 35784 secondary 165660 ... NaN NaN NaN
4 13227, 35591, 30152 secondary 20366 ... NaN NaN NaN
...
Please see help(clio.fetch_annotations) for further details and examples.
Pushing annotations
⚠️ Clio has little in the way of guard rails when it comes to writing annotations to the database. It's easy to accidentally overwrite existing annotations. Do not use this functionality unless you know exactly what you are doing! Please check in with a a senior person/postdoc before writing to any field.
>>> # Use a {bodyid: {field: value}} dictionary to update fields
>>> clio.set_annotations({154109: {"soma_side": "LHS"}})
>>> # Alternatively, use a dataframe dictionary to update fields
>>> import pandas as pd
>>> new_ann = pd.DataFrame([[154109, "LHS", "ascending neuron"]],
... columns=["bodyid", "soma_side", "class"])
>>> new_ann.head()
bodyid soma_side class
0 154109 LHS ascending neuron
>>> clio.set_annotations(new_ann)
Please see help(clio.set_annotations) for details.
References
List of API endpoints for Clio.
Metadata
Release files for clio-py 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| clio_py-0.1.1.tar.gz | 15.7 kB | With provenance | Details for clio_py-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| clio_py-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for clio_py-0.1.1-py3-none-any.whl |
Total release size: 31.1 kB
Release files / clio_py-0.1.1.tar.gz
| Download URL | clio_py-0.1.1.tar.gz |
|---|---|
| Size | 15.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f2bd2f2fa3a3298209168e0bdb85dc321f29ea1e6e0e7d5d21b07124e641f0c3
|
|
BLAKE2b-256 checksum How to use checksums |
59a82b1426b6fa071aa14def005a69cc71b12c5ab24a8070a58c300d569d03f9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.
Transparency logRelease files / clio_py-0.1.1-py3-none-any.whl
| Download URL | clio_py-0.1.1-py3-none-any.whl |
|---|---|
| Size | 15.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b11fce61a0af1d654a778326f6d0be984b586b9ee530af1dc16fa8f1ec0e6619
|
|
BLAKE2b-256 checksum How to use checksums |
d54053f2fc467dfce3dcffae5b06a9c1f3de9fa57b33152d92162bd6eb06bb9c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.
Transparency logSecurity for clio-py 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for clio_py-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.