Refactor the application package within ruff's complexity limits

changelog.d/ruff-complexity-application.changed.md

@@ -0,0 +1 @@
+Refactored the rest of the application under ruff's complexity rules (C901, PLR): the ASGI shell, Flask migration logging, household and policy routes, v1 and v2 household translation and validation, saved-policy mirrors, catalog extraction and the metadata layers are split into named steps, related arguments travel as small value objects, and magic numbers are named, with characterization tests pinning the behaviour first; responses, error messages, logs and published schemas are unchanged.

policyengine_api/constants.py

@@ -197,6 +197,10 @@ def get_bundle_default_dataset_option(country_id: str) -> dict:
     "economy_impact": 3,
     "report_output": 3,
 }
+# Runtime cache versions are stored in legacy VARCHAR(10) columns, and keep at
+# least this many digest characters after their scope prefix and schema version.
+RUNTIME_CACHE_VERSION_LENGTH = 10
+MINIMUM_RUNTIME_CACHE_DIGEST_LENGTH = 4
 
 
 def _build_runtime_cache_version(
@@ -209,8 +213,8 @@ def _build_runtime_cache_version(
     """
     schema_version = str(RUNTIME_CACHE_SCHEMA_VERSIONS[scope])
     prefix = "e" if scope == "economy_impact" else "r"
-    digest_length = 10 - len(prefix) - len(schema_version)
-    if digest_length < 4:
+    digest_length = RUNTIME_CACHE_VERSION_LENGTH - len(prefix) - len(schema_version)
+    if digest_length < MINIMUM_RUNTIME_CACHE_DIGEST_LENGTH:
         msg = f"Runtime cache version for {scope} does not fit in VARCHAR(10)"
         raise ValueError(msg)
 

policyengine_api/country.py

@@ -9,7 +9,7 @@
 from datetime import date, datetime
 from importlib.metadata import version as get_package_version
 from pathlib import Path
-from typing import Any
+from typing import Any, NamedTuple
 
 import dpath
 import pandas as pd
@@ -87,21 +87,33 @@ def _serialize_axis_result(
     return entity_values
 
 
+class _HouseholdCell(NamedTuple):
+    """One requested household value: an entity's variable in one period."""
+
+    entity_plural: str
+    entity_id: str
+    variable_name: str
+    period: str
+
+
 def _record_calculation_failure(
     household: dict,
     calculation_warnings: list[str],
+    cell: _HouseholdCell,
     *,
-    has_axes: bool,
-    population: Population,
-    entity_plural: str,
-    entity_id: str,
-    variable_name: str,
-    period: str,
+    axis_population: Population | None,
     error: Exception,
 ) -> None:
-    if has_axes:
+    """Record a household value that could not be calculated.
+
+    ``axis_population`` is the cell's population when the household has axes:
+    the cell then holds one null per axis point and a warning is added.
+    Otherwise the cell is null and the failure is only logged.
+    """
+    entity_plural, entity_id, variable_name, period = cell
+    if axis_population is not None:
         count_entities = len(household[entity_plural])
-        axis_point_count = population.count // count_entities
+        axis_point_count = axis_population.count // count_entities
         household[entity_plural][entity_id][variable_name][period] = [
             None
         ] * axis_point_count
@@ -548,12 +560,8 @@ def calculate(
                 _record_calculation_failure(
                     household,
                     calculation_warnings,
-                    has_axes=has_axes,
-                    population=population,
-                    entity_plural=entity_plural,
-                    entity_id=entity_id,
-                    variable_name=variable_name,
-                    period=period,
+                    _HouseholdCell(entity_plural, entity_id, variable_name, period),
+                    axis_population=population if has_axes else None,
                     error=error,
                 )
 

policyengine_api/data/congressional_districts.py

@@ -585,6 +585,11 @@ class CongressionalDistrictMetadataItem(BaseModel):
 ]
 
 
+# Numbers whose last two digits are 10 through 20 always take "th" (11th, 12th).
+_ALWAYS_TH_REMAINDER_MIN = 10
+_ALWAYS_TH_REMAINDER_MAX = 20
+
+
 def _get_ordinal_suffix(number: int) -> str:
     """Get the ordinal suffix for a number (st, nd, rd, th).
 
@@ -598,7 +603,7 @@ def _get_ordinal_suffix(number: int) -> str:
         22 -> "nd"
 
     """
-    if 10 <= number % 100 <= 20:
+    if _ALWAYS_TH_REMAINDER_MIN <= number % 100 <= _ALWAYS_TH_REMAINDER_MAX:
         # Special case for 11th, 12th, 13th, etc.
         suffix = "th"
     else:

policyengine_api/data/places.py

@@ -6,6 +6,8 @@
 
 from policyengine_api.data.congressional_districts import get_valid_state_codes
 
+PLACE_FIPS_CODE_LENGTH = 5
+
 
 def parse_place_code(place_code: str) -> tuple[str, str]:
     """Parse a place code into its state abbreviation and FIPS components.
@@ -45,6 +47,6 @@ def validate_place_code(place_code: str) -> None:
         msg = f"Invalid state in place code: '{state_abbrev}'"
         raise ValueError(msg)
 
-    if not place_fips.isdigit() or len(place_fips) != 5:
+    if not place_fips.isdigit() or len(place_fips) != PLACE_FIPS_CODE_LENGTH:
         msg = f"Invalid FIPS code in place: '{place_fips}'. Expected 5-digit FIPS code"
         raise ValueError(msg)

policyengine_api/data/v2/catalog/catalog_selection.py

@@ -14,6 +14,7 @@
 )
 
 SUPPORTED_V2_COUNTRY_IDS = frozenset({"us", "uk"})
+MAXIMUM_POLICYENGINE_VERSION_LENGTH = 128
 
 
 class MetadataCatalogUnavailableError(RuntimeError):
@@ -47,8 +48,11 @@ def validate_policyengine_version(value: str) -> str:
     if not isinstance(value, str) or not value or value != value.strip():
         msg = "policyengine_version must be a non-empty canonical version"
         raise InvalidPolicyEngineVersionError(msg)
-    if len(value) > 128:
-        msg = "policyengine_version must be at most 128 characters"
+    if len(value) > MAXIMUM_POLICYENGINE_VERSION_LENGTH:
+        msg = (
+            "policyengine_version must be at most "
+            f"{MAXIMUM_POLICYENGINE_VERSION_LENGTH} characters"
+        )
         raise InvalidPolicyEngineVersionError(msg)
     try:
         parsed = Version(value)