Skip to main content

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.

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)

Source distribution for clio-py 0.1.1
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)

Table of built distributions (wheels) for clio-py 0.1.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page