add support for numberMatched in Orders response

[philvarner]

What I'm changing

• RootRouter Callable get_orders now requires an additional value in the result tuple that is a count of the total number of orders
  that will be returned from pagination. When this returns Some(int), the value is used for the numberMatched field in
  FeatureCollection returned from the /orders endpoint. If this feature is not desired, providing a function that returns
  Nothing will exclude the numberMatched field in the response.
• Removed dependency on pyrfc3339 library, since only one function from it was used in tests and that function has
  been removed in newer versions of the library.
• pydantic >= 2.12 is now required.
• bump stapi-pydantic to 0.1.0, bump stapi-fastapi to 0.8.0

How I did it

• Changed the signature on get_orders instead of adding another callable like get_orders_count. This makes it a bit cleaner. The 3-tuple returned by get_orders should be changed to a class if any more values are added.

Checklist

• Tests pass: uv run pytest
• Checks pass: uv run pre-commit run --all-files
• CHANGELOG is updated (if necessary)

[Copilot]

Pull request overview

This pull request adds support for the numberMatched field in the Orders response to indicate the total number of orders available for pagination. The implementation changes the get_orders callable signature to return a 3-tuple, removes the pyrfc3339 dependency by vendoring a single function, and updates the minimum pydantic version requirement.

• Modified get_orders callable to return a 3-tuple including an optional count for the numberMatched field
• Removed pyrfc3339 dependency and vendored the format_timezone function into test utilities
• Updated pydantic minimum version requirement to >= 2.12

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
stapi-pydantic/src/stapi_pydantic/order.py	Adds number_matched field to OrderCollection with serialization alias and conditional exclusion
stapi-pydantic/pyproject.toml	Bumps version to 0.1.0 and explicitly adds pydantic >= 2.12 dependency
stapi-pydantic/CHANGELOG.md	Documents version 0.1.0 changes (incomplete - missing main feature)
stapi-fastapi/tests/test_order.py	Updates test to verify numberMatched field in empty orders response
stapi-fastapi/tests/test_datetime_interval.py	Vendors format_timezone function from pyrfc3339 to eliminate dependency
stapi-fastapi/tests/backends.py	Updates mock_get_orders to return 3-tuple with count value
stapi-fastapi/src/stapi_fastapi/routers/root_router.py	Updates get_orders method to handle 3-tuple result and populate number_matched field
stapi-fastapi/src/stapi_fastapi/backends/root_backend.py	Updates GetOrders type signature to include Maybe[int] for count (docstring needs update)
stapi-fastapi/pyproject.toml	Bumps version to 0.8.0 and removes pyrfc3339 dependencies
stapi-fastapi/CHANGELOG.md	Documents version 0.8.0 changes including new feature and dependency removal

Comments suppressed due to low confidence (1)

stapi-fastapi/src/stapi_fastapi/backends/root_backend.py:34

• The docstring for the GetOrders type alias is incomplete and outdated. It still states "A tuple containing a list of orders and a pagination token" but doesn't mention the third element (the count). The docstring should be updated to document all three tuple elements:

1. list of orders
2. pagination token (Maybe[str])
3. total count (Maybe[int])

"""
Type alias for an async function that returns a list of existing Orders.

Args:
    next (str | None): A pagination token.
    limit (int): The maximum number of orders to return in a page.
    request (Request): FastAPI's Request object.

Returns:
    A tuple containing a list of orders and a pagination token.

    - Should return returns.result.Success[tuple[list[Order], returns.maybe.Some[str]]]
      if including a pagination token
    - Should return returns.result.Success[tuple[list[Order], returns.maybe.Nothing]]
      if not including a pagination token
    - Returning returns.result.Failure[Exception] will result in a 500.
"""

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jkeifer]

Looks good, though I agree the GetOrders return tuple is bordering on unwieldy.

I do think it is a little odd adding only this count to the orders collection response: it seems like any collection response could include such a count. But I also get being pragmatic and only adding it to this one to start, so don't feel like I'm asking for you do add that everywhere. I'll make an issue both here and in the spec to add numberMatched and numberReturned as optional to all collection responses, in line with the OGC Features API spec response definition.

[philvarner]

I'll make an issue both here and in the spec to add numberMatched and numberReturned as optional to all collection responses, in line with the OGC Features API spec response definition.

I to at least make it align with those. FWIW, I think numberReturned is dumb since there's basically no case where the response isn't transformed into a data structure where the length of the orders array can't be calculated.