Restrict playtime reports to Blackstone Unlimited and Unlimited Listens (PP-4346)

[dbernstein]

Description

Introduces PLAYTIME_REPORT_ELIGIBLE_DATA_SOURCE_NAMES, a hard-coded frozenset allowlist of the two Blackstone audio platforms for which playtime summary reports should be generated: "Blackstone Unlimited" and "Unlimited Listens".

Rewrites _fetch_distinct_eligible_data_source_names to intersect eligible-protocol collection data source names with this allowlist, removing the previous unfiltered SELECT DISTINCT data_source_name FROM playtime_summaries query entirely.

Motivation and Context

JIRA: PP-4346
The previous implementation queried all collections using eligible protocols (OPDS2API / OPDSForDistributorsAPI) and unioned in every distinct data_source_name from the entire playtime_summaries table. This caused reports — and Google Drive folders — to be created for every data source that had ever accumulated a summary row, including non-Blackstone providers and historical names from other library installations.

Reports should only ever be generated for the two Blackstone audio platforms. A two-layer filter is applied:

1. Allowlist — only names in PLAYTIME_REPORT_ELIGIBLE_DATA_SOURCE_NAMES are considered.
2. Protocol guard — the name must also be backed by at least one collection using an eligible protocol (OPDS2API or OPDSForDistributorsAPI), preventing accidental reports if an unrelated collection is given one of the allowlisted names.

Empty reports are still generated when no playtime data exists for the reporting period.

How Has This Been Tested?

• Updated test_generate_playtime_reports to use "Blackstone Unlimited" and "Unlimited Listens" as collection data source names.
• Replaced the old parametrized discovery tests with new ones covering: both allowlisted names returned, non-allowlisted eligible collection excluded, allowlisted name with ineligible protocol excluded.
• Added test_fetch_distinct_eligible_data_source_names_ignores_playtime_summaries verifying that PlaytimeSummary records no longer influence the result.
• Added test_playtime_report_eligible_data_source_names_constant pinning the frozenset contents.
• All tests pass.

Checklist

• I have updated the documentation accordingly.
• All new and existing tests passed.

[claude]

Claude finished @dbernstein's task in 4m 8s —— View job

---

Summary

Clean, well-scoped fix. Replacing the UNION of eligible-collection names with the full SELECT DISTINCT data_source_name FROM playtime_summaries table with a set intersection against a hard-coded allowlist is the right approach — it eliminates report sprawl from historical noise and makes the permitted set explicit and auditable. The two-layer guard (allowlist + protocol check) is sound. Test coverage is thorough: parametrized cases cover every filtering combination, and the new test_fetch_distinct_eligible_data_source_names_ignores_playtime_summaries test directly verifies that PlaytimeSummary rows no longer influence discovery.

Details

Nit: src/palace/manager/celery/tasks/playtime_entries.py:157-159

frozenset({"Blackstone Unlimited", "Unlimited Listens"}) passes a mutable set literal into frozenset(), creating and immediately discarding the intermediate set. A list or tuple avoids the redundant allocation:

PLAYTIME_REPORT_ELIGIBLE_DATA_SOURCE_NAMES: frozenset[str] = frozenset(
    ["Blackstone Unlimited", "Unlimited Listens"]
)

circulation/src/palace/manager/celery/tasks/playtime_entries.py

Lines 157 to 159 in 68fb984

	PLAYTIME_REPORT_ELIGIBLE_DATA_SOURCE_NAMES: frozenset[str] = frozenset(
	{"Blackstone Unlimited", "Unlimited Listens"}
	)

Nit: Placeholder Jira ticket number in PR title and commit message

Both the PR title and the commit message contain PP-XXXX rather than an actual Jira ticket number. Per the contributing guidelines, the real ticket ID should replace the placeholder before merging.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.34%. Comparing base (5315bfb) to head (68fb984).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3383   +/-   ##
=======================================
  Coverage   93.34%   93.34%           
=======================================
  Files         507      507           
  Lines       46434    46432    -2     
  Branches     6336     6336           
=======================================
- Hits        43345    43344    -1     
  Misses       1999     1999           
+ Partials     1090     1089    -1     

☔ 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.