NeuroMorphoClient

class braincell.io.NeuroMorphoClient(session=None, *, timeout=30.0, cache_dir=None, retries=3, backoff_base=0.5)

Stateful client for the NeuroMorpho.Org REST API.

The client wraps a requests.Session (lazily imported on first construction so the package can be imported without requests installed) and adds retry/backoff for transient failures, an optional NeuroMorphoCache, and typed return values.

Parameters:

• session (Any) – Session-like object exposing get(url, params=..., timeout=..., stream=...). Pass a configured requests.Session to control proxies, headers, or HTTPS verification. None constructs a fresh requests.Session (importing requests lazily).

• timeout (float) – Per-request timeout in seconds. Defaults to DEFAULT_TIMEOUT.

• cache_dir (str | Path | None) – Root directory for cached downloads. When provided, the client creates a NeuroMorphoCache accessible via cache.

• retries (int) – Number of attempts for JSON API calls. Must be >= 1. Streaming file downloads are not retried.

• backoff_base (float) – Base delay (seconds) for exponential backoff between retries.

Variables:

• session (object)

• timeout (float)

• cache (NeuroMorphoCache or None) – Set when cache_dir was provided.

• retries (int)

• backoff_base (float)

Examples

>>> client = NeuroMorphoClient(cache_dir="~/data/neuromorpho")
>>> page = client.search("species:mouse", size=5)
>>> for neuron in client.iter_search("species:mouse", limit=20):
...     client.download(neuron)

property cache: NeuroMorphoCache | None

Return the attached NeuroMorphoCache, if configured.

property cache_dir: Path | None

Convenience accessor for the cache root directory.

describe(neuron, *, include_measurement=True)

Return an aggregate NeuroMorphoDetail for a neuron.

Combines get_neuron() (when an id is passed), get_measurement(), get_urls(), and get_cache_status() in one call.

Parameters:

• neuron (NeuroMorphoNeuron | int)

• include_measurement (bool) – If False, the measurement field of the result is None and no measurement request is issued.

Return type:

NeuroMorphoDetail

download(neuron, output_dir=None, *, mode='both', overwrite=False, dry_run=False)

Download files for neuron into the cache layout.

When output_dir is None the client falls back to cache_dir. Either output_dir or a configured cache

is required.

Parameters:

• neuron (NeuroMorphoNeuron | int)

• output_dir (str | Path | None) – Cache root. None uses the client’s configured cache.

• mode (Literal['standard', 'original', 'both'])

• overwrite (bool) – Re-download files that are already on disk.

• dry_run (bool) – If True, do not touch the network or filesystem. Returns a populated NeuroMorphoDownloadRecord whose items have downloaded_now=False and reason="dry_run".

Return type:

NeuroMorphoDownloadRecord

Raises:

ValueError – If neither output_dir nor a client cache is provided.

file_plan(neuron, *, mode='both')

Build the typed download plan for neuron.

Parameters:

• neuron (NeuroMorphoNeuron)

• mode (Literal['standard', 'original', 'both'])

Return type:

tuple[NeuroMorphoFilePlan, ...]

get_cache_status(neuron)

Return on-disk cache status for neuron.

Parameters:

neuron (NeuroMorphoNeuron | int)

Returns:

configured=False when this client has no cache attached.

Return type:

NeuroMorphoCacheStatus

get_measurement(neuron)

Fetch the morphometry record for a neuron.

Parameters:

neuron (NeuroMorphoNeuron | int) – Either a previously-fetched neuron or its id.

Return type:

NeuroMorphoMeasurement

get_neuron(neuron_id)

Fetch the neuron record for neuron_id.

Parameters:

neuron_id (int)

Return type:

NeuroMorphoNeuron

Raises:

NeuroMorphoNotFoundError – If the upstream returns 404 for the id.

get_urls(neuron)

Return the resolved URLs for neuron.

Parameters:

neuron (NeuroMorphoNeuron)

Return type:

NeuroMorphoUrls

iter_search(query, *, fq=None, size=20, limit=None, start_page=0, sort='neuron_id,asc')

Yield every neuron matching query, paging lazily.

Stops when the upstream reports the last page, when an empty page is returned, or when limit neurons have been yielded. Duplicates are filtered out across pages.

Parameters:

• query (str | NeuroMorphoQuery)

• fq (list[str] | None)

• size (int) – Page size for each request.

• limit (int | None) – Maximum number of neurons to yield. None means unlimited.

• start_page (int) – Zero-based page index to start from.

• sort (str)

Yields:

NeuroMorphoNeuron

search(query, *, fq=None, size=20, page=0, sort='neuron_id,asc')

Run a single search request against /api/neuron/select.

Parameters:

• query (str | NeuroMorphoQuery) – Either a raw Solr q string or a typed NeuroMorphoQuery. When a query object is passed, its raw_fq is merged with the explicit fq argument.

• fq (list[str] | None) – Extra Solr filter strings to append to fq.

• size (int) – Page size requested from the API.

• page (int) – Zero-based page index.

• sort (str) – Sort string forwarded to the API.

Return type:

NeuroMorphoSearchPage