Skip to content

feat: extensible write support for accessors - #2658

Merged
flying-sheep merged 11 commits into
feat/write-compat-profilesfrom
feat/json-io
Nov 6, 2026
Merged

flying-sheep merged 11 commits into
feat/write-compat-profilesfrom
feat/json-io

Conversation

@flying-sheep

@flying-sheep flying-sheep commented Sep 22, 2026 •

Copy link
Copy Markdown
Member

TODO:

  • go over it and figure out if it’s robust, clean up slop, …
  • maybe split up into multiple PRs

  • Release note not necessary because:

@codecov

codecov Bot commented Sep 22, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 93.40659% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.04%. Comparing base (7699105) to head (81a869a).
✅ All tests successful. No failed tests found.

Files with missing lines Patch % Lines
src/anndata/acc/_entry_points.py 88.63% 5 Missing ⚠️
src/anndata/_io/specs/registry.py 83.33% 1 Missing ⚠️
Additional details and impacted files
@@                      Coverage Diff                       @@
##           feat/write-compat-profiles    #2658      +/-   ##
==============================================================
+ Coverage                       85.89%   86.04%   +0.15%     
==============================================================
  Files                              50       51       +1     
  Lines                            8358     8444      +86     
==============================================================
+ Hits                             7179     7266      +87     
+ Misses                           1179     1178       -1     
Files with missing lines Coverage Δ
src/anndata/_core/anndata.py 86.61% <100.00%> (+0.17%) ⬆️
src/anndata/_io/specs/methods.py 92.30% <100.00%> (+0.28%) ⬆️
src/anndata/_write_compat.py 96.55% <100.00%> (+11.36%) ⬆️
src/anndata/types.py 92.85% <100.00%> (ø)
src/anndata/_io/specs/registry.py 94.69% <83.33%> (-0.34%) ⬇️
src/anndata/acc/_entry_points.py 88.63% <88.63%> (ø)

... and 1 file with indirect coverage changes

Comment thread src/anndata/_io/specs/methods.py Resolved
@flying-sheep
flying-sheep marked this pull request as ready for review September 24, 2026 15:35
@flying-sheep flying-sheep added this to the 0.14.0 milestone Sep 24, 2026
@flying-sheep flying-sheep mentioned this pull request Sep 25, 2026
2 of 3 tasks
@flying-sheep
flying-sheep force-pushed the feat/json-io branch 3 times, most recently from 7b46343 to 3027d25 Compare September 25, 2026 10:57
@flying-sheep flying-sheep changed the title feat: write lists, any keys and accessors feat: write lists and accessors Sep 25, 2026
@flying-sheep flying-sheep changed the title feat: write lists and accessors feat: write support for sequences and accessors Sep 25, 2026

@ilan-gold ilan-gold left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So I'm not sure I like this design...I'd like to ask in the zarr Zulip about this...

Comment thread docs/fileformat-prose.md Resolved
@ilan-gold

ilan-gold commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

It might be worth jamming zarr-developers/zarr-extensions#9 through in advance of this if there is appetite from the zarr maintainers (which there seems to be)

@flying-sheep

flying-sheep commented Oct 1, 2026 •

Copy link
Copy Markdown
Member Author

Can you link to your zarr zulip post please? /edit: found it #Zarr-Python > json in zarr

I think I’d be totally OK with not having heterogeneous sequences but instead a JSON type. The only question is how to decide when to use it. adata.uns["foo"]["ad"] = AnnData(...) stays serializable, so when looking at the .uns["foo"] dict, how do we decide if we store it as JSON or not? And of course that doesn’t mean we don’t need #2662.

Regarding zarr-developers/zarr-extensions#9: I’m not looking forward to adding more blockers to the stack. I planned to finish up this PR stack during the conference, then scanpy 1.13 right after. If they can commit to this next week I’d say that’s fine, but I don’t want to wait in case that issue is asleep for a few more months.

@flying-sheep flying-sheep changed the title feat: write support for sequences and accessors feat: write support for accessors Oct 26, 2026
Comment thread docs/fileformat-prose.md

In zarr v3, this is byte-for-byte the layout of the `json` data type ({pr}`zarr-developers/zarr-extensions#9`)
(which also uses the `vlen-utf8` codec),
so only the `data_type` metadata will need to change once zarr implementations support it.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that can be a v0.1.1 then since it doesn’t change anything about the actual semantics of our spec.

@ilan-gold ilan-gold left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This raises the question of whether this is a convention or should be a part of our spec (mainly just a notion of interpretation since unlike everything else in our spec, it would break old versions, which this won't)

Comment thread docs/write-compat.md Resolved
Comment thread src/anndata/_io/specs/methods.py Resolved
Comment thread src/anndata/_io/specs/methods.py Resolved
@flying-sheep flying-sheep changed the title feat: write support for accessors feat: extensible write support for accessors Nov 5, 2026

@ilia-kats ilia-kats left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Awesome, thank you!

Unrelated to this PR: A similar design would probably work for writing extra elements of AnnData subclasses (see discussion in scverse/mudata#210).

@ilan-gold ilan-gold left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mostly worried about the language in the spec (thinking of what if TreeData comes along etc.). What if two accessors have the same json schema but different in-memory behaviors? Is that possible? It's a bit pedantic maybe, and maybe non-existent but I often err on the side of caution so I'm just crossing t's and dotting i's here. As it stands now, it's already great :)

Comment thread docs/fileformat-prose.md Resolved
Comment thread docs/fileformat-prose.md Outdated
(accessor)=
### Accessor specifications (v0.1.0)

- Each accessor MUST be stored as a scalar {ref}`string <scalars>`,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we specify that extenders must do this as well or is that clear?

@flying-sheep flying-sheep Nov 5, 2026 •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

here too I think that it doesn’t hurt to be explicit. Can be added in the “extending” section probably.

Comment thread docs/fileformat-prose.md Resolved
@flying-sheep

Copy link
Copy Markdown
Member Author

What if two accessors have the same json schema but different in-memory behaviors? Is that possible?

then they still need to set their accessor-project attribute differently right?

@ilan-gold

Copy link
Copy Markdown
Contributor

then they still need to set their accessor-project attribute differently right?

Right, so then (to my point about reserved namespaces), what if two people go for the same name? An additional UUID? That's what zarr-conventions does.

@ilia-kats

Copy link
Copy Markdown
Contributor

Right, so then (to my point about reserved namespaces), what if two people go for the same name? An additional UUID? That's what zarr-conventions does.

PyPI is enforcing unique package names, so as long as people name their accessor-project after their package, I think we're fine.

@flying-sheep
flying-sheep enabled stacked auto-merge (squash) November 6, 2026 09:24
@flying-sheep
flying-sheep merged commit e5cbba9 into main Nov 6, 2026
26 checks passed
@flying-sheep
flying-sheep deleted the feat/json-io branch November 6, 2026 11:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Allow storing heterogeneous lists in .uns (as JSON or so)

4 participants