Pass the user list filters, row listings and sign-in identity as one value each

The PLR0913 findings in the code #3891 added:

- The user-household and user-policy services, their route Protocols and
  routes take an optional UserHouseholdFilter or UserPolicyFilter (the
  v2 and v1 ids to narrow a listing to) instead of two keyword
  arguments, as the metadata layers take a ParameterValueFilter. The
  routes build the filter from the same query fields.
- read_user_report_rows and read_user_simulation_rows take a
  UserReportListing or UserSimulationListing, as the household and
  policy row readers take their listings.
- create_user_identity takes the UserPrincipal whose issuer, subject and
  email it stores, instead of the three fields.

The statements, their parameters and the OpenAPI documents are
unchanged. The route and service tests, and the concurrent sign-in
test's stand-in, use the new arguments.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: anth-volk

policyengine_api/fastapi_routes/dependencies.py

@@ -62,12 +62,14 @@
     )
     from policyengine_api.services.v2.user_households.types import (
         UserHouseholdCreateFields,
+        UserHouseholdFilter,
         UserHouseholdPage,
         UserHouseholdRead,
         UserHouseholdUpdateInput,
     )
     from policyengine_api.services.v2.user_policies.types import (
         UserPolicyCreateFields,
+        UserPolicyFilter,
         UserPolicyPage,
         UserPolicyRead,
         UserPolicyUpdateInput,
@@ -408,8 +410,7 @@ def list_user_policies(
         *,
         principal: AccountPrincipal,
         country_id: str,
-        policy_id: UUID | None = None,
-        legacy_policy_id: int | None = None,
+        policy_filter: UserPolicyFilter | None = None,
         offset: int = 0,
         limit: int = 100,
     ) -> UserPolicyPage:
@@ -468,8 +469,7 @@ def list_user_households(
         *,
         principal: AccountPrincipal,
         country_id: str,
-        household_id: UUID | None = None,
-        legacy_household_id: int | None = None,
+        household_filter: UserHouseholdFilter | None = None,
         offset: int = 0,
         limit: int = 100,
     ) -> UserHouseholdPage:

policyengine_api/fastapi_routes/v2/user_households/routes.py

@@ -38,6 +38,7 @@
     UserHouseholdUpdateQuery,
 )
 from policyengine_api.services.v2.identity.types import AccountPrincipal
+from policyengine_api.services.v2.user_households.types import UserHouseholdFilter
 
 UserHouseholdCreateQueryDependency = Annotated[
     UserHouseholdCreateQuery, Depends(query_dependency(UserHouseholdCreateQuery))
@@ -160,8 +161,10 @@ def read() -> UserHouseholdPageResponse:
             page = service_factory().list_user_households(
                 principal=principal,
                 country_id=query.country_id,
-                household_id=query.household_id,
-                legacy_household_id=query.legacy_household_id,
+                household_filter=UserHouseholdFilter(
+                    household_id=query.household_id,
+                    legacy_household_id=query.legacy_household_id,
+                ),
                 offset=query.offset,
                 limit=query.limit,
             )

policyengine_api/fastapi_routes/v2/user_policies/routes.py

@@ -35,6 +35,7 @@
     UserPolicyCollectionQuery,
 )
 from policyengine_api.services.v2.identity.types import AccountPrincipal
+from policyengine_api.services.v2.user_policies.types import UserPolicyFilter
 
 CountryQueryDependency = Annotated[
     CountryQuery, Depends(query_dependency(CountryQuery))
@@ -151,8 +152,10 @@ def read() -> UserPolicyPageResponse:
             page = service_factory().list_user_policies(
                 principal=principal,
                 country_id=query.country_id,
-                policy_id=query.policy_id,
-                legacy_policy_id=query.legacy_policy_id,
+                policy_filter=UserPolicyFilter(
+                    policy_id=query.policy_id,
+                    legacy_policy_id=query.legacy_policy_id,
+                ),
                 offset=query.offset,
                 limit=query.limit,
             )

policyengine_api/services/v2/identity/database_connectors/creates.py

@@ -13,6 +13,8 @@
     from datetime import datetime
     from uuid import UUID
 
+    from policyengine_api.services.v2.identity.types import UserPrincipal
+
 
 def create_provisioned_user(session: Session, *, primary_country: str) -> User:
     """Insert a standard user for a new sign-in identity and return it with its ID."""
@@ -42,19 +44,17 @@ def create_user_identity(
     session: Session,
     *,
     user_id: UUID,
-    issuer: str,
-    subject: str,
-    email: str | None,
+    principal: UserPrincipal,
     seen_at: datetime,
 ) -> UUID | None:
-    """Insert one identity, returning its user unless another request won."""
+    """Insert the principal's identity; return its user unless another request won."""
     return session.execute(
         insert(UserIdentity)
         .values(
             user_id=user_id,
-            issuer=issuer,
-            subject=subject,
-            email=email,
+            issuer=principal.issuer,
+            subject=principal.subject,
+            email=principal.email,
             last_seen_at=seen_at,
         )
         .on_conflict_do_nothing(constraint="uq_user_identities_issuer_subject")

policyengine_api/services/v2/identity/services.py

@@ -141,9 +141,7 @@ def resolve_in_session(
             created_user_id = create_user_identity(
                 session,
                 user_id=user.id,
-                issuer=principal.issuer,
-                subject=principal.subject,
-                email=principal.email,
+                principal=principal,
                 seen_at=seen_at,
             )
             if created_user_id is None:
@@ -339,9 +337,7 @@ def convert_unauthenticated_user_in_session(
         and create_user_identity(
             session,
             user_id=unauthenticated_user.id,
-            issuer=principal.issuer,
-            subject=principal.subject,
-            email=principal.email,
+            principal=principal,
             seen_at=seen_at,
         )
         is not None

policyengine_api/services/v2/user_households/services.py

@@ -39,7 +39,10 @@
     user_household_page,
     user_household_read,
 )
-from policyengine_api.services.v2.user_households.types import UserHouseholdListing
+from policyengine_api.services.v2.user_households.types import (
+    UserHouseholdFilter,
+    UserHouseholdListing,
+)
 from policyengine_api.services.v2.user_households.validators import (
     require_user_household,
     resolve_association_household_id,
@@ -223,16 +226,18 @@ def list_user_households(
         *,
         principal: AccountPrincipal,
         country_id: str,
-        household_id: UUID | None = None,
-        legacy_household_id: int | None = None,
+        household_filter: UserHouseholdFilter | None = None,
         offset: int = 0,
         limit: int = 100,
     ) -> UserHouseholdPage:
         """Return a page of the principal's associations in this country.
 
-        ``household_id`` and ``legacy_household_id`` narrow it to one household. A
-        signed-out browser that has not saved anything yet gets an empty page.
+        ``household_filter`` narrows it to one household. A signed-out browser
+        that has not saved anything yet gets an empty page.
         """
+        selected = (
+            household_filter if household_filter is not None else UserHouseholdFilter()
+        )
         with self._database_session.transaction() as session:
             owner = resolve_principal_user_for_read_in_session(
                 session, principal, country_id=country_id
@@ -244,8 +249,8 @@ def list_user_households(
                 UserHouseholdListing(
                     country_id=country_id,
                     user_id=owner.user_id,
-                    household_id=household_id,
-                    legacy_household_id=legacy_household_id,
+                    household_id=selected.household_id,
+                    legacy_household_id=selected.legacy_household_id,
                     offset=offset,
                     limit=limit,
                 ),

policyengine_api/services/v2/user_households/types.py

@@ -104,6 +104,18 @@ class UserHouseholdRead:
     updated_at: datetime
 
 
+@dataclass(frozen=True)
+class UserHouseholdFilter:
+    """Which of the caller's saved households a listing keeps.
+
+    ``household_id`` keeps links to one v2 household and ``legacy_household_id``
+    links to one v1 household; with neither, every saved household is kept.
+    """
+
+    household_id: UUID | None = None
+    legacy_household_id: int | None = None
+
+
 @dataclass(frozen=True)
 class UserHouseholdListing:
     """One page of a user's associations to read, optionally for one household.

policyengine_api/services/v2/user_policies/services.py

@@ -60,6 +60,7 @@
     LegacyUserPolicySnapshot,
     UserPolicyCreateFields,
     UserPolicyCreationInput,
+    UserPolicyFilter,
     UserPolicyListing,
     UserPolicyPage,
     UserPolicyRead,
@@ -460,16 +461,16 @@ def list_user_policies(
         *,
         principal: AccountPrincipal,
         country_id: str,
-        policy_id: UUID | None = None,
-        legacy_policy_id: int | None = None,
+        policy_filter: UserPolicyFilter | None = None,
         offset: int = 0,
         limit: int = 100,
     ) -> UserPolicyPage:
         """Return a page of the principal's associations in this country.
 
-        ``policy_id`` and ``legacy_policy_id`` narrow it to one policy. A signed-out
-        browser that has not saved anything yet gets an empty page.
+        ``policy_filter`` narrows it to one policy. A signed-out browser that has
+        not saved anything yet gets an empty page.
         """
+        selected = policy_filter if policy_filter is not None else UserPolicyFilter()
         with self._database_session.transaction() as session:
             owner = resolve_principal_user_for_read_in_session(
                 session, principal, country_id=country_id
@@ -481,10 +482,10 @@ def list_user_policies(
                 UserPolicyListing(
                     country_id=country_id,
                     user_id=owner.user_id,
-                    policy_id=policy_id,
+                    policy_id=selected.policy_id,
                     offset=offset,
                     limit=limit,
-                    legacy_policy_id=legacy_policy_id,
+                    legacy_policy_id=selected.legacy_policy_id,
                 ),
             )
 

policyengine_api/services/v2/user_policies/types.py

@@ -163,6 +163,18 @@ class UserPolicyRead:
     updated_at: datetime
 
 
+@dataclass(frozen=True)
+class UserPolicyFilter:
+    """Which of the caller's saved policies a listing keeps.
+
+    ``policy_id`` keeps links to one v2 policy and ``legacy_policy_id`` links to
+    one v1 policy; with neither, every saved policy is kept.
+    """
+
+    policy_id: UUID | None = None
+    legacy_policy_id: int | None = None
+
+
 @dataclass(frozen=True)
 class UserPolicyListing:
     """One page of a user's associations to read, optionally for one policy.

policyengine_api/services/v2/user_reports/database_connectors/reads.py

@@ -11,6 +11,8 @@
 if TYPE_CHECKING:
     from uuid import UUID
 
+    from policyengine_api.services.v2.user_reports.types import UserReportListing
+
 
 def read_owned_user_report_row(
     session: Session,
@@ -46,34 +48,30 @@ def read_user_report_row(
 
 def read_user_report_rows(
     session: Session,
-    *,
-    country_id: str,
-    user_id: UUID,
-    legacy_report_id: int | None,
-    offset: int,
-    limit: int,
+    listing: UserReportListing,
 ) -> list[UserReportAssociation]:
     """Return up to ``limit + 1`` of a user's associations in creation order.
 
-    With ``legacy_report_id``, only associations to that v1 report output are
-    returned. The extra row lets the caller report whether another page exists.
+    With the listing's ``legacy_report_id``, only associations to that v1 report
+    output are returned. The extra row lets the caller report whether another
+    page exists.
     """
     statement = select(UserReportAssociation).where(
-        UserReportAssociation.country_id == country_id,
-        UserReportAssociation.user_id == user_id,
+        UserReportAssociation.country_id == listing.country_id,
+        UserReportAssociation.user_id == listing.user_id,
     )
-    if legacy_report_id is not None:
+    if listing.legacy_report_id is not None:
         statement = statement.where(
-            UserReportAssociation.legacy_report_id == legacy_report_id
+            UserReportAssociation.legacy_report_id == listing.legacy_report_id
         )
     return list(
         session.exec(
             statement.order_by(
                 col(UserReportAssociation.created_at),
                 col(UserReportAssociation.id),
             )
-            .offset(offset)
-            .limit(limit + 1)
+            .offset(listing.offset)
+            .limit(listing.limit + 1)
         ).all()
     )