Blosc/python-blosc2

[DOC] Tutorial: variable-length columns (ListArray and BatchArray)

Open

#649 opened on Jun 2, 2026

View on GitHub
 (0 comments) (0 reactions) (0 assignees)Python (47 forks)auto 404
documentationgood first issue

Repository metrics

Stars
 (207 stars)
PR merge metrics
 (PR metrics pending)

Description

12.batcharray.ipynb covers BatchArray basics but there is no tutorial for ListArray — the newer, more flexible varlen column type. Users working with nested or ragged data (e.g. GPS waypoints, tags, embeddings of varying length) have no worked example to follow.

Suggested work: Extend 12.batcharray.ipynb or add 12b.listarray.ipynb covering:

  • Creating a ListArray with item_spec
  • Appending, extending, and fancy-indexing
  • Embedding a ListArray as a column inside a CTable (using the dataclass schema API)
  • Arrow round-trip (from_arrow / to_arrow)
  • When to prefer ListArray over BatchArray

Contributor guide

Research direction
Extend the existing notebook 12.batcharray.ipynb by adding a new section or creating a separate notebook for ListArray, covering creation with item spec, appending, indexing, embedding in CTable, and Arrow round trip. Include code examples and explanations for each step.
Tech stack
python
Domain
backend
Issue type
Documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
Pythonblosc2Jupyter Notebooks
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
70