Developer Docs (Python Package)#

This section is the developer-facing documentation for the cellucid Python package (repo folder: cellucid-python/).

It explains how the Python side works (export format, servers, Jupyter embedding, hooks/events, sessions), how to contribute safely, and how to ship releases + docs.

Important

If you are using Cellucid as an end user (wet lab / analyst / “I just want to view my data”), this is not the best starting point. Start with the Python user guide landing page: Python Package Guide and the Web App user guide: Web App Guide.

Fast path (pick your goal)#

You want to…	Start here	Then read
Understand the big picture	Codebase architecture	Server mode architecture, endpoints, and security
Find “where in the repo is X?”	Repo layout and entry points	CLI architecture and commands
Set up a local dev environment	Local development setup	Testing and CI
Change `prepare()` or the export format	prepare() / export pipeline architecture	Export format spec and invariants → Extension point: add a new export feature
Work on servers (`cellucid serve`, `serve_anndata`)	Server mode architecture, endpoints, and security	Performance profiling and scaling
Work on notebook embedding + hooks	Jupyter embedding architecture	Hooks/events protocol and schema → Debugging playbook
Cut a release	Release process	Docs development and style guide

Scope and mental model#

Cellucid is an ecosystem:

Cellucid (web app): UI + rendering + interaction + sessions + exports. Code lives in the cellucid/ repo.
cellucid-python (this repo): export format + servers + notebook embedding + hooks + Python/CLI APIs.
cellucid-annotation: community annotation repo template + schema (web app feature, not primarily Python).
cellucid-datasets: demo datasets (exports) used for examples/hosting.
cellucid-r (future): R exporter (not ready yet).

This developer section focuses on the Python repo but links to the web app developer docs when the behavior is frontend-driven: Developer Documentation (Web App Architecture).