Add runnable examples to CTable where and sort_by

[armutlutost]

Summary

Add runnable examples to the CTable.where() and CTable.sort_by() docstrings.

The examples demonstrate filtering, column projection, compound predicates, plain sorting, lazy sorting of a filtered view, and multi-key sorting.

Closes #650

Changes

• Add a complete sample CTable setup to both docstrings.
• Demonstrate where() with a simple predicate and selected columns.
• Demonstrate a compound column predicate.
• Demonstrate materialized and lazy sorting.
• Add a multi-key sorting example.
• Include printed results that clarify lazy view behavior.

Validation

• python -m py_compile src/blosc2/ctable.py
• git diff --check

The repository’s required blosc2 Conda environment was unavailable locally, so the documentation examples were not executed against the compiled extension.

AI disclosure

AI assistance was used to draft the documentation examples. I reviewed the changes before submitting this pull request.

[Copilot]

🟡 Changes recommended

Address the two documentation nits before approval.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds runnable examples to CTable.where() and CTable.sort_by() docstrings.

Changes:

• Demonstrates filtering, projection, compound predicates, and sorting.
• Adds materialized, lazy, and multi-key sorting examples.
• Includes expected outputs clarifying view behavior.

File summaries

File	Summary
src/blosc2/ctable.py	Adds where() and sort_by() examples; needs an explicit blosc2 import and clearer eager sort-key computation wording.

Review details

Suppressed comments (2)

src/blosc2/ctable.py:13944

• This wording implies that sorting is deferred until the result is read, but sort_by() has already scanned the view and materialized the sort-key column(s) to compute the full permutation before returning; only the returned row/column data remains lazy. Please clarify that this creates a lazy view while the sort order is computed eagerly.

        Sorting a filtered table stays lazy until rows are read::

src/blosc2/ctable.py:15748

• This advertised runnable example uses blosc2.field, blosc2.string, and blosc2.CTable, but only imports dataclass. It happens to pass when doctested from ctable.py because blosc2 is already a module global, but copying the example into a fresh REPL or script raises NameError; add the package import as the other runnable examples in this file do.

            >>> from dataclasses import dataclass

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[FrancescAlted]

Hi @armutlutost . Thanks for your contribution. Copilot is suggesting a couple of improvements; please have a closer look.