Stabilize temporal allocation records as a public API
- Dominant language
- Python
- Stars
- 15.2k
- Forks
- 461
- Avg merge
- 5d 3h
- Merged PRs (30d)
- 10
Description
### Is there an existing proposal for this?
- [x] I have searched the existing proposals
### Is your feature request related to a problem?
This is a narrower follow-up to #637. `FileReader.get_temporal_allocation_records()` already exposes the allocation lifetime data used by the temporal flamegraph, and `TemporalAllocationRecord` and `Interval` are declared in `_memray.pyi`. However, the temporal interface is not documented in the public API documentation, and its record types are not exported from the top-level `memray` namespace.
As a result, users who want machine-readable temporal allocation data cannot tell whether this interface is intended to be supported or whether they must depend on private implementation details or parse the generated HTML reports.
### Describe the solution you'd like
Clarify and stabilize the existing temporal allocation interface as a supported public API, without changing the capture format or introducing a new indexing engine.
A narrow first version could include:
- documenting `FileReader.get_temporal_allocation_records()` and the semantics of its snapshot intervals;
- exposing `TemporalAllocationRecord` and `Interval` through an approved public import path, or defining another public representation if that is preferred;
- documenting `merge_threads`, open-ended lifetimes, and the relationship between interval indices and memory snapshots; and
- adding tests that treat the machine-readable temporal records as a supported interface and validate them against the data consumed by the existing temporal flamegraph.
Would you prefer to stabilize the existing record classes directly, or introduce a separate documented wrapper or result type? I would be happy to implement the narrower approach you prefer, including type declarations, API documentation, and regression tests.
This proposal intentionally does not include persistent indexes, a new capture format, module or function grouping, or a higher-level query engine. Those could be considered separately after the underlying temporal data interface is supported.
### Alternatives you considered
Users can currently call the existing method and rely on types from `memray._memray`, but that depends on an underscored implementation module and undocumented semantics. Parsing temporal flamegraph HTML is another workaround, but it couples downstream analysis to a presentation format. Implementing the broader analysis API proposed in #637 all at once would address more use cases, but would require substantially more API and architectural design than this narrower first step.
Contributor guide
Research direction
Start with FileReader.get_temporal_allocation_records(), the declarations in _memray.pyi, and the existing temporal flamegraph consumer. Determine whether the existing record classes or a documented wrapper should be public, then trace the interval and snapshot semantics, merge_threads, and open-ended lifetimes. Done means documented public access, type declarations, and regression tests validating the records against the flamegraph data.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- api, documentation, testing
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100