adding enhanced skeleton features by fcollman · Pull Request #335 · CAVEconnectome/CAVEclient

fcollman · 2026-03-14T00:51:40Z

Client-side support for the two new SkeletonService endpoints, plus a convenience download method. Together these allow users to fetch hundreds of pre-existing skeletons far faster than the previous get_bulk_skeletons() 10-skeleton limit allowed.

Changes

get_cached_skeletons_bulk(root_ids, ...) — mirrors the new server endpoint. Accepts up to 500 root IDs, skips client-side chunkedgraph validation, and returns {"skeletons": {rid: skeleton}, "missing": [...], "async_queued": [...]}. Decodes server responses using the same hex+gzip pipeline as get_bulk_skeletons().

get_skeleton_access_token(root_ids, ...) — requests a short-lived downscoped GCS Bearer token. Returns the token, expiry, bucket name, GCS object paths for cached RIDs, and a missing list. Token is valid for up to 60 minutes (GCP IAM limit).

download_skeletons_with_token(token_response) — convenience method that takes the response from get_skeleton_access_token() and downloads + parses all skeleton H5 files directly from GCS, returning the same dict format as get_skeleton(output_format="dict"). Files are gzip-compressed HDF5; parsed with h5py.

New endpoints in endpoints.py: get_cached_skeletons_bulk_as_post, get_skeleton_token_as_post

New dependency: h5py (added to pyproject.toml)

Documentation: updated docs/tutorials/skeletonization.md with new sections for both features, updated the async polling workflow to use get_cached_skeletons_bulk(), updated docs/api/skeleton.md to expose the three new methods, and added a 8.1.0 changelog entry.

Requires server-side SkeletonService >= v0.22.51

codecov · 2026-03-14T00:53:33Z

Codecov Report

❌ Patch coverage is 6.49351% with 72 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
caveclient/skeletonservice.py	6.49%	72 Missing ⚠️

Files with missing lines	Coverage Δ
caveclient/endpoints.py	`100.00% <ø> (ø)`
caveclient/skeletonservice.py	`70.56% <6.49%> (-10.90%)`	⬇️

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot

Pull request overview

This PR adds client-side support for two new SkeletonService server endpoints plus a convenience download method, enabling users to retrieve large numbers of pre-cached skeletons much faster than the existing 10-skeleton-limit get_bulk_skeletons(). It also adds h5py as a new required dependency.

Changes:

Added get_cached_skeletons_bulk() and get_skeleton_access_token() methods with corresponding endpoint definitions for bulk cached skeleton retrieval (up to 500 IDs) and GCS token-based direct downloads
Added download_skeletons_with_token() convenience method that downloads and parses gzip-compressed HDF5 skeleton files from GCS using the access token
Updated documentation with tutorials, API reference, and a changelog entry for version 8.1.0

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
caveclient/skeletonservice.py	Three new public methods: `get_cached_skeletons_bulk`, `get_skeleton_access_token`, `download_skeletons_with_token`
caveclient/endpoints.py	Two new endpoint URL templates for the cached bulk and token endpoints
pyproject.toml	Added `h5py` as a required dependency
uv.lock	Lock file updates for h5py and related dependencies
docs/tutorials/skeletonization.md	New tutorial sections for cached bulk retrieval and token-based download; updated async polling example
docs/api/skeleton.md	Exposed the three new methods in API docs
docs/changelog.md	Added 8.1.0 changelog entry

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/changelog.md

 ---
 title: Changelog
 ---
+## 8.1.0 (March 13, 2026)


caveclient/skeletonservice.py


        return estimated_async_time_secs_upper_bound_sum
+
+    def get_cached_skeletons_bulk(


caveclient/skeletonservice.py

1. Bump version from 8.0.0 to 8.1.0 in pyproject.toml to match changelog 2. Add per-skeleton error handling in download_skeletons_with_token 3. Add @_check_version_compatibility(method_constraint=">=0.22.51") to get_cached_skeletons_bulk and get_skeleton_access_token 4. Remove redundant verbose_level from URL query params (keep in JSON body) 5. Add skeleton version validation via self.get_versions() to both new methods 6. Add comprehensive tests for all three new methods Co-authored-by: fcollman <782341+fcollman@users.noreply.github.com>

…ndling, tests (#336)

Copilot

Pull request overview

This PR adds faster bulk retrieval of already-cached skeletons to the SkeletonClient, including an option to download skeleton files directly from GCS using a short-lived access token, and updates docs/tests plus project dependencies accordingly. It also includes an unrelated enhancement to AnnotationClient.get_tables() to support a timestamp query parameter.

Changes:

Add SkeletonClient.fetch_skeletons() with method="server" (POST + server decode) and method="gcs" (direct GCS download + HDF5 parse).
Add h5py as a dependency and expand skeleton-related documentation and tests.
Add timestamp support to AnnotationClient.get_tables() (server-version gated).

Reviewed changes

Copilot reviewed 8 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`caveclient/skeletonservice.py`	Implements `fetch_skeletons()` and supporting server/GCS retrieval paths plus token caching.
`caveclient/endpoints.py`	Adds two new skeleton bulk/token endpoints.
`tests/test_skeletons.py`	Adds unit tests covering server decoding, truncation behavior, and GCS download parsing.
`pyproject.toml`	Adds `h5py` dependency and bumps version to `8.1.0`.
`uv.lock`	Updates lock to include `h5py` (but currently has a version mismatch for `caveclient`).
`docs/tutorials/skeletonization.md`	Documents `fetch_skeletons()` usage and updates async polling workflow.
`docs/changelog.md`	Adds `8.1.0` release notes describing the new skeleton bulk retrieval feature.
`docs/api/skeleton.md`	Exposes `fetch_skeletons` in generated API docs.
`caveclient/annotationengine.py`	Adds optional `timestamp` parameter to `get_tables()` with version compatibility gating.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

caveclient/annotationengine.py

+        query_d = {}
+        if timestamp is not None:
+            query_d["timestamp"] = datetime.strftime(timestamp, "%Y-%m-%dT%H:%M:%S.%f")
+        response = self.session.get(url, params = query_d)
        return handle_response(response)


docs/api/skeleton.md

        show_bases: false
-        members: ['server_version', 'get_skeleton', 'get_cache_contents', 'skeletons_exist', 'get_bulk_skeletons', 'generate_bulk_skeletons_async']
+        members: ['server_version', 'get_skeleton', 'get_cache_contents', 'skeletons_exist', 'get_bulk_skeletons', 'generate_bulk_skeletons_async', 'fetch_skeletons']


caveclient/skeletonservice.py

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

…e/CAVEclient into skeleton_bulk_improvements

adding enhanced skeleton features

8c1f105

fcollman requested a review from Copilot March 14, 2026 12:21

Copilot started reviewing on behalf of fcollman March 14, 2026 12:22 View session

Copilot AI reviewed Mar 14, 2026

View reviewed changes

Copilot AI mentioned this pull request Mar 14, 2026

Address PR #335 review feedback: version compat, validation, error handling, tests #336

Merged

Copilot AI and others added 3 commits March 14, 2026 06:03

Address PR #335 review feedback: version compat, validation, error ha…

658fc3a

…ndling, tests (#336)

fix annotation engine bugs

cd684c3

improve skeleton interface

e60247e

fcollman requested a review from Copilot March 18, 2026 02:57

Copilot started reviewing on behalf of fcollman March 18, 2026 02:57 View session

Copilot AI reviewed Mar 18, 2026

View reviewed changes

fcollman and others added 3 commits March 18, 2026 02:49

Potential fix for pull request finding

7d4ae25

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

bumping uv.lock file

4bb2cff

Merge branch 'skeleton_bulk_improvements' of github.com:CAVEconnectom…

92d6a45

…e/CAVEclient into skeleton_bulk_improvements

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

adding enhanced skeleton features#335

adding enhanced skeleton features#335
fcollman wants to merge 7 commits intomasterfrom
skeleton_bulk_improvements

fcollman commented Mar 14, 2026 •

edited

Loading

Uh oh!

codecov bot commented Mar 14, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		return estimated_async_time_secs_upper_bound_sum

		def get_cached_skeletons_bulk(

Conversation

fcollman commented Mar 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Mar 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fcollman commented Mar 14, 2026 •

edited

Loading

codecov bot commented Mar 14, 2026 •

edited

Loading