Add InvalidPaginationInfo and pagination_info_from_proto2

[llucax]

pagination_info_from_proto() calls the PaginationInfo constructor directly, so the ValueError that #217 added for a negative total_items can escape from a conversion function. That breaks the wrapping rule that loading from the wire never raises on invalid content: the caller loses the whole message over one bad field.

This adds the usual valid/invalid pair and the replacement converter:

• BasePaginationInfo holds the two shared fields and refuses direct instantiation.
• PaginationInfo keeps its ValueError unchanged. There is deliberately no _raise_on_invalid-style escape hatch: unlike DeliveryArea, it has always been strict here, so there is no released behavior to transition away from.
• InvalidPaginationInfo takes the same fields with no invariants, so a malformed count survives for inspection.
• pagination_info_from_proto2() returns PaginationInfo | InvalidPaginationInfo; pagination_info_from_proto() is deprecated and points at it, mirroring delivery_area_from_proto and bounds_from_proto.

Two things worth a second look while reviewing:

The new converter reads next_page_token through HasField() instead of testing it for truth. The field has presence, so the old truthiness test collapses "the server sent an empty token" into "the server sent no token", and only the second means there are no more pages. Changing that in place would be a silent behavior change, so it only happens under the new name.

total_items is a uint32 on the wire, so a decoded message cannot actually carry a negative count today and the invalid branch is unreachable through the generated bindings. It is still there because the converter's contract is not to raise regardless of what it is handed, and because the wire type is not the wrapper's to assume; the test exercises it with a message-like stand-in.

Both leaves also gain a __str__, which neither had. The pair only reads well if the invalid marker composes with a valid form, and the dataclass repr is too long for a log line. The rule is per-field, so the marker goes on the count (items=<invalid:-1>,next=None) rather than around the whole object, as in InvalidDeliveryArea.

The release notes document the deprecation and, separately, the breaking change from #217: PaginationInfo(total_items=-1) raised nothing in v0.4.0 and raises ValueError now.

Part of #239 and #251.

[Copilot]

🟡 Changes recommended

The deprecation warning must follow the repository’s required fully qualified message format.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds typed handling for malformed pagination metadata while preserving wire values.

Changes:

• Adds valid/invalid pagination types and compact string forms.
• Adds pagination_info_from_proto2() with field-presence handling.
• Adds documentation, release notes, and tests.

File summaries

File	Description
src/.../pagination/_pagination_info.py	Adds the pagination class hierarchy.
src/.../pagination/__init__.py	Exports the new types.
src/.../proto/v1alpha8/_pagination_info.py	Adds and deprecates converters.
src/.../proto/v1alpha8/__init__.py	Exports the new converter.
tests/pagination/test_pagination_info.py	Tests pagination types.
tests/pagination/proto/v1alpha8/test_pagination_info.py	Tests conversion behavior.
docs/user-guide/overview.md	Documents malformed pagination data.
docs/client-developer-guide/shipped-converters.md	References the replacement converter.
RELEASE_NOTES.md	Records API and behavior changes.

Review details

• Files reviewed: 9/9 changed files
• Comments generated: 1
• Review effort level: Balanced

---

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