Service

domain.report.ports.service

Summary

Report service: validate snapshot queries, precompute sparse cubes, and synthesize sliced report views.

---

A snapshot is keyed by the canonical signature of its normalized query; the sparse cube data lives in the configured :class:ReportStore while snapshot metadata is persisted through the report repository.

Classes

ReportService

ReportService(
    expense_svc: ExpenseCrudsService,
    tag_svc: TagCrudsService,
    store: ReportStore,
    report_repo=None,
)

Build, persist, and serve precomputed report snapshots.

Notes

Instances are created by :func:get_report_service. The service scans expenses in batches, expands tag hierarchies, and persists period series into the configured :class:ReportStore.

Initialize the report service with its dependencies.

Parameters:

Name	Type	Description	Default
expense_svc	ExpenseCrudsService	Expense CRUD service used as the cube source.	required
tag_svc	TagCrudsService	Tag CRUD service used to expand tag hierarchies and resolve ignore tags.	required
store	ReportStore	Key-value store for cube period data.	required
report_repo	Any	Report snapshot repository; defaults to :func:create_report_repo when omitted.	None

Functions

delete_snapshot async

delete_snapshot(report_id: str) -> bool

Delete a snapshot and all of its cube keys from the store.

Parameters:

Name	Type	Description	Default
report_id	str	Snapshot ID to delete.	required

Returns:

Name	Type	Description
bool	bool	True when the snapshot existed and was deleted.

fetch_report async

fetch_report(
    report_id: str,
    granularities: Optional[List[str]] = None,
    period_ids: Optional[List[str]] = None,
    flow: str = "outflows",
    payees: Optional[List[str]] = None,
    tags: Optional[List[str]] = None,
) -> Optional[Report]

Slice a stored snapshot into a report API response.

"*" in payees or tags expands to every value stored in the cube meta.

Parameters:

Name	Type	Description	Default
report_id	str	Snapshot ID to slice.	required
granularities	Optional[List[str]]	Granularities to include; defaults to the snapshot's own.	None
period_ids	Optional[List[str]]	Period labels to filter to.	None
flow	str	Flow to serve; both includes inflows and outflows.	'outflows'
payees	Optional[List[str]]	Payee filters applied per bucket.	None
tags	Optional[List[str]]	Tag path filters applied per bucket.	None

Returns:

Type	Description
Optional[Report]	Optional[Report]: The sliced report view, or None when the snapshot does not exist.

generate_snapshot async

generate_snapshot(
    query: ReportQuery,
) -> ReportSnapshotDocument

Validate a query and return an existing or newly built snapshot.

If a snapshot with the same canonical signature already exists it is returned directly; otherwise a fresh cube is built and persisted.

Parameters:

Name	Type	Description	Default
query	ReportQuery	Raw snapshot definition.	required

Returns:

Name	Type	Description
ReportSnapshotDocument	ReportSnapshotDocument	The existing or newly created snapshot.

list_snapshots async

list_snapshots(
    offset: int = 0, limit: int = DEFAULT_LIMIT
) -> List[ReportSnapshotDocument]

List stored snapshots, newest first.

Parameters:

Name	Type	Description	Default
offset	int	Number of snapshots to skip.	0
limit	int	Maximum number of snapshots to return.	DEFAULT_LIMIT

Returns:

Type	Description
List[ReportSnapshotDocument]	List[ReportSnapshotDocument]: Snapshots ordered by creation time, newest first.

Functions

get_report_service

get_report_service(
    expense_svc, tag_svc, store, report_repo=None
) -> ReportService

Build a report service with the given dependencies.

Parameters:

Name	Type	Description	Default
expense_svc	Any	Expense CRUD service used as the cube source.	required
tag_svc	Any	Tag CRUD service used to expand tag hierarchies.	required
store	Any	Report store backing cube data.	required
report_repo	Any	Report snapshot repository; defaults to :func:create_report_repo when omitted.	None

Returns:

Name	Type	Description
ReportService	ReportService	Ready-to-use report service.

query_signature

query_signature(query: ReportQuery) -> str

Canonical fingerprint of a snapshot definition (list order-insensitive).

Parameters:

Name	Type	Description	Default
query	ReportQuery	Snapshot definition to fingerprint.	required

Returns:

Name	Type	Description
str	str	SHA-256 hex digest of the normalized definition.