etestore

A standalone Python library for storing and accessing annotated phylogenetic trees. SQLite-backed, single-file, schema-versioned.

The format extension is .ete. The library is the single source of truth for the .ete v1 format and is designed to be consumed by ETE4, PhyloCloud, treeprof, and any other tool that needs efficient access to large annotated trees.

Status: v0.1.0 scaffold — schema initialization works; reads and writes are stubbed pending the next implementation phase. See BUILD_SPEC.md and task-log.md for the build plan.

---

Install

pip install -e .
# Optional: array dtype support
pip install -e .[arrays]
# Optional: sparse-array dtype support
pip install -e .[sparse]
# Optional: ete4 bridge (from_ete4/to_ete4)
pip install -e .[ete4]
# Optional: full developer environment
pip install -e .[dev]

Python 3.10+ required.

---

Quickstart

from etestore import TreeStore

# Create a new .ete file at the latest schema version.
store = TreeStore.create("example.ete")
print(store.schema_version)  # 1
store.close()

# Open read-only.
with TreeStore("example.ete", mode="r") as store:
    print(store.newick())
    print(store.list_properties())

The full API surface lives in etestore.api. See docs/api.md for the reference and docs/format-v1.md for the on-disk schema.

---

Project layout

etestore/
  src/etestore/        # Package source
  tests/                # Unit, integration, benchmark
  docs/                 # Schema spec, API, codecs, performance
  BUILD_SPEC.md         # Build specification (single source of truth)
  CLAUDE.md             # Workflow, style, commit policy
  task-log.md           # Append-only decision log

---

Contributing

The build follows the multi-phase workflow defined in CLAUDE.md:

1. Specification (planner)
2. Technical design (software-engineer)
3. Implementation (coder)
4. Review (code-reviewer)
5. Validation (tester)
6. Documentation (documenter)

Every decision lands in task-log.md. Read CLAUDE.md before opening a PR.

---

License

MIT — see LICENSE.