Dict-like metadata interface & private metadata

[yfukai]

Solves #192

This pull request refactors the metadata API for graph backends, introducing a new MetadataView class to provide a dictionary-like interface for metadata that synchronizes mutations directly with the graph.

Metadata API udpate:

• Introduced the MetadataView class in src/tracksdata/graph/_base_graph.py, which provides a dictionary-like interface for metadata and ensures that updates, removals, and other mutations are synchronized with the graph backend. This replaces the previous metadata() and update_metadata() methods.
• Refactored the BaseGraph class and its subclasses to expose metadata via the metadata property (public) and _private_metadata property (private), with enforced validation to prevent accidental modification of private metadata from public APIs. Backend-specific methods for updating and removing metadata are now internal (_update_metadata, _remove_metadata).

Private metadata handling and validation:

• Added strict validation and separation of public and private metadata keys, preventing accidental modification of internal metadata from public APIs and providing a dedicated _private_metadata property for internal use. A new test ensures that private metadata is hidden from public APIs and that validation errors are raised for improper access.

API and import changes:

• Updated src/tracksdata/graph/__init__.py to export MetadataView and reflect the new API, ensuring consistent imports and usage across the package.
• Adjusted logging and documentation strings to reference the new property-based metadata API.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 69.87952% with 25 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.87%. Comparing base (e10d8c3) to head (8028c52).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
src/tracksdata/graph/_base_graph.py	68.11%	20 Missing and 2 partials ⚠️
src/tracksdata/graph/_graph_view.py	66.66%	2 Missing ⚠️
src/tracksdata/nodes/_regionprops.py	50.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #260      +/-   ##
==========================================
- Coverage   88.18%   87.87%   -0.32%     
==========================================
  Files          56       56              
  Lines        4308     4395      +87     
  Branches      749      761      +12     
==========================================
+ Hits         3799     3862      +63     
- Misses        319      340      +21     
- Partials      190      193       +3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

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

[JoOkuma]

Hi @yfukai , thanks for the PR.
I left a single comment for you.

[JoOkuma]

Private metadata is lost during conversion to geff. Is this correct?
Wouldn't it make sense to keep it?

[yfukai]

Oh yeah, thanks for notifying this. It should survive.

[yfukai]

Done! I used _private_metadata_for_copy so that the backends can decide which metadata to send, since SQLGraph will use the private metadata to persistently store the AttrSchema, which should not be used when creating the graph by from_other etc., and thus should be excluded to avoid confusion. I'd be happy to hear your opinion.