umpyre.storage

Storage operations for metrics.

Functions

serialize_metrics(data, output_path[, format])	Serialize metrics to file.
deserialize_metrics(file_path[, format])	Deserialize metrics from file.
parse_metric_filename(filename)	Parse metric filename into components.
find_metrics_by_commit(history_dir, commit_sha)	Find metrics file for a specific commit.
find_metrics_by_version(history_dir, version)	Find all metrics files for a specific PyPI version.
get_latest_metric_for_version(history_dir, ...)	Get the most recent metrics file for a version.
get_all_versions(history_dir)	Get all unique PyPI versions found in metrics.
filter_by_date_range(history_dir[, ...])	Get metrics files within a date range.

Classes

GitBranchStorage(repo_path[, remote, token])

Store metrics in a separate git branch.

Exceptions

GitBranchStorageError

Raised when git branch storage operations fail.

class umpyre.storage.GitBranchStorage(repo_path, remote='origin', *, token=None)

Bases: object

Store metrics in a separate git branch.

This provides versioned, branch-based storage without polluting the main branch or requiring external artifacts.

Example

>>> storage = GitBranchStorage(repo_path="/path/to/repo")
>>> metrics = {"lines": 100, "functions": 10}
>>> storage.store_metrics(metrics, "abc123", branch="code-metrics")

store_metrics(metrics, commit_sha, branch='code-metrics', formats=None)

Store metrics to git branch.

Parameters:

• metrics (dict) – Metric dictionary to store

• commit_sha (str) – Git commit SHA

• branch (str) – Target branch name

• formats (Optional[list[str]]) – List of formats (‘json’, ‘csv’)

exception umpyre.storage.GitBranchStorageError

Bases: Exception

Raised when git branch storage operations fail.

umpyre.storage.deserialize_metrics(file_path, format='json')

Deserialize metrics from file.

Parameters:

• file_path (Path) – Path to input file

• format (str) – Format (‘json’ or ‘csv’)

Return type:

dict

Returns:

Metric dictionary

umpyre.storage.filter_by_date_range(history_dir, start_date=None, end_date=None)

Get metrics files within a date range.

Parameters:

• history_dir (Path) – Path to history directory

• start_date (Optional[datetime]) – Start datetime (inclusive)

• end_date (Optional[datetime]) – End datetime (inclusive)

Return type:

list[Path]

Returns:

List of paths within date range (sorted chronologically)

Example

>>> from datetime import datetime, timedelta
>>> end = datetime.now()
>>> start = end - timedelta(days=7)
>>> recent = filter_by_date_range(Path("history"), start, end)
>>> print(f"Found {len(recent)} metrics from last 7 days")

umpyre.storage.find_metrics_by_commit(history_dir, commit_sha)

Find metrics file for a specific commit.

Parameters:

• history_dir (Path) – Path to history directory

• commit_sha (str) – Commit SHA (7 chars or full)

Return type:

Optional[Path]

Returns:

Path to metrics file or None

Example

>>> metrics = find_metrics_by_commit(Path("history"), "700e012")
>>> print(metrics.name)
2025_11_14_22_45_00__700e012__0.1.0.json

umpyre.storage.find_metrics_by_version(history_dir, version)

Find all metrics files for a specific PyPI version.

Parameters:

• history_dir (Path) – Path to history directory

• version (str) – PyPI version string (e.g., “0.1.0”)

Return type:

list[Path]

Returns:

List of paths (sorted by timestamp, latest first)

Example

>>> metrics = find_metrics_by_version(Path("history"), "0.1.0")
>>> for m in metrics:
...     print(m.name)
2025_11_14_22_50_00__abc1234__0.1.0.json
2025_11_14_22_45_00__700e012__0.1.0.json

umpyre.storage.get_all_versions(history_dir)

Get all unique PyPI versions found in metrics.

Parameters:

history_dir (Path) – Path to history directory

Return type:

list[str]

Returns:

Sorted list of versions (excluding ‘none’)

Example

>>> versions = get_all_versions(Path("history"))
>>> print(versions)
['0.1.0', '0.1.1', '0.2.0']

umpyre.storage.get_latest_metric_for_version(history_dir, version)

Get the most recent metrics file for a version.

Parameters:

• history_dir (Path) – Path to history directory

• version (str) – PyPI version string

Return type:

Optional[Path]

Returns:

Path to latest metrics file or None

Example

>>> latest = get_latest_metric_for_version(Path("history"), "0.1.0")
>>> info = parse_metric_filename(latest.name)
>>> print(f"Latest 0.1.0 metrics from {info['timestamp_str']}")

umpyre.storage.parse_metric_filename(filename)

Parse metric filename into components.

Parameters:

filename (str) – Filename like “2025_11_14_22_45_00__700e012__0.1.0.json”

Returns:

{

“timestamp”: datetime object, “timestamp_str”: “2025-11-14T22:45:00”, “commit_sha”: “700e012”, “pypi_version”: “0.1.0” or None, “has_version”: bool,

}

Return type:

dict

Example

>>> info = parse_metric_filename("2025_11_14_22_45_00__700e012__0.1.0.json")
>>> info['commit_sha']
'700e012'
>>> info['pypi_version']
'0.1.0'

umpyre.storage.serialize_metrics(data, output_path, format='json')

Serialize metrics to file.

Parameters:

• data (dict) – Metric dictionary

• output_path (Path) – Path to output file

• format (str) – Format (‘json’ or ‘csv’)

Modules

formats	JSON and CSV serialization for metrics.
git_branch	Git branch-based storage operations.
query_utils	Helper utilities for working with umpyre metrics storage.