Back-port the key-only attributes search and optional criteria to the older clients (#40, #41)

[craigmcchesney]

Back-ports the two criteria conventions #6 introduced to the five older criterion helpers and six older query/iter methods, so every criteria-based client in the library now spells them the same way.

Two commits, each with its own plan under plan/tickets/.

#40 — key-only attributes() search

The protos document an empty values list on every AttributesCriterion as a key-only existence search. Five helpers made it unreachable: PvMetadataQuery.attributes, ConfigurationQuery.attributes, ConfigurationActivationQuery.attributes, PvQuery.attr, ConfigQuery.attr. They now take values: list[str] | None = None, matching DataSetQuery/AnnotationQuery from #6 — all seven attribute helpers agree.

The empty-key rejection stays, and matters more on the two v2 selectors: the server does not validate the key there, so a blank one would reach Mongo as an existence test on "attributes." and silently match nothing.

Worth doing rather than leaving as a documented workaround:

• conventions.md justified the guard as refusing "a criterion that would silently match everything." True of tags([]), false here — a key-only attributes criterion narrows the result set. The rule was generalized onto the one criterion it does not describe.
• pv-metadata.md carried a whole section teaching users to drop through to the raw protobuf classes, a snippet needing # cookbook:no-mypy because the escape hatch is not statically checkable. It is now a positive recipe, and the checker type-checks all 107 snippets with none skipped for that reason.

Triage also found the guard was not upstream-driven: it arrived in c101964 (2026-07-14) applying one rule across pv_name/aliases/tags/attributes at once, and all five proto comments predate it.

#41 — optional criteria on the query/iter methods

Six methods took criteria as a required positional argument, a shape dating from when the server rejected an empty list. It is now match-all, so iter_pv_metadata() with no arguments is the browse-all form. criteria stays the first positional parameter, so existing callers are unaffected.

Also adds a _ActivationCriterion TypeAlias — the fully-qualified name is 109 characters and overflows the line limit in an annotated parameter. Using TypeAlias rather than a bare assignment keeps mypy happy in an annotation position, and net drops one pre-existing mypy error.

Verification

Server behavior was verified in dp-service source rather than taken from the tickets, since both rest on a server-behavior claim:

• Criterion helpers reject the key-only attributes search the protos document #40: four of five criteria route to MongoQueryFilterBuilder.attributeFilter(), which returns Filters.exists("attributes.<key>") on an empty list — not an $in: [] that would match nothing. MongoQueryFilterBuilderTest.java:114-139 covers that path for both emptyList() and null. Validation checks a blank key and deliberately does not check values: the TAGSCRITERION arm immediately above each attributes arm does reject empty values, so the omission is a decision.
• Make criteria optional on the annotation-service query/iter methods (empty list now matches all) #41: each validation site carries a deliberate "match-all by contract (#245), not an error" comment. Paging still applies unconditionally (DEFAULT_QUERY_LIMIT = 100), which is why the docstrings point at iter_* for browsing.

Both ticket bodies were corrected before implementation. Notably, #41 claimed the default page size is server-configurable — it is a hardcoded constant, so the client docs deliberately do not promise it is tunable — and over-attributed the change to dp-grpc PR #147, which covers only three of the five RPCs.

725 unit tests pass (719 baseline + 6 net), ruff lint and format clean, 107 cookbook snippets checked.

Closes #40
Closes #41

🤖 Generated with Claude Code

https://claude.ai/code/session_019he3UCsAnqTDE2VQ73Djwn

[Copilot]

🟡 Changes recommended

Two documentation nits remain: stale helper docstrings and invalid blank-key examples.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Back-ports key-only attribute searches and optional criteria to older client APIs.

Changes:

• Added key-only attribute searches.
• Made query criteria optional for match-all browsing.
• Added tests and updated documentation, plans, and conventions.

File summaries

File	Reviewed changes
tests/unit/test_query_client.py	Added coverage for key-only attribute criteria.
tests/unit/test_pv_metadata_client.py	Added coverage for key-only searches and optional criteria.
tests/unit/test_machine_config_client.py	Added configuration query coverage.
tests/unit/test_machine_config_activation_client.py	Added activation query coverage.
src/dp_python_lib/client/query_client.py	Updated v2 attribute helpers.
src/dp_python_lib/client/pv_metadata_client.py	Added key-only searches and optional criteria.
src/dp_python_lib/client/machine_config_client.py	Updated configuration APIs and type aliases.
plan/tickets/41/plan.md	Documents optional criteria implementation.
plan/tickets/40/plan.md	Documents key-only search implementation.
doc/cookbook/query.md	Documents key-only searches.
doc/cookbook/pv-metadata.md	Documents browsing and existence searches; contains examples needing explicit empty keys.
doc/cookbook/machine-configuration.md	Documents optional criteria and attributes.
doc/cookbook/conventions.md	Updates shared API conventions.
CLAUDE.md	Records unified conventions; related helper docstrings remain stale.

Review details

• Files reviewed: 14/14 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.