Refactor package structure (#247)

Author: shweta-nhs

src/eligibility_signposting_api/app.py

@@ -8,10 +8,10 @@
 from mangum.types import LambdaContext, LambdaEvent
 
 from eligibility_signposting_api import audit, repos, services
+from eligibility_signposting_api.common.error_handler import handle_exception
+from eligibility_signposting_api.common.request_validator import validate_request_params
 from eligibility_signposting_api.config.config import config, init_logging
-from eligibility_signposting_api.error_handler import handle_exception
 from eligibility_signposting_api.views import eligibility_blueprint
-from eligibility_signposting_api.wrapper import validate_request_params
 
 init_logging()
 logger = logging.getLogger(__name__)

src/eligibility_signposting_api/audit/audit_context.py

@@ -18,7 +18,7 @@
     RequestAuditQueryParams,
 )
 from eligibility_signposting_api.audit.audit_service import AuditService
-from eligibility_signposting_api.model.eligibility import (
+from eligibility_signposting_api.model.eligibility_status import (
     CohortGroupResult,
     ConditionName,
     IterationResult,

src/eligibility_signposting_api/common/__init__.py

@@ -0,0 +1,88 @@
+# How to Use the API Error Response Module
+
+This document outlines how to use the `api_error_response.py` module for standardized error handling within the Eligibility Signposting API. The module ensures that all API errors are consistent, logged appropriately, and conform to the FHIR `OperationOutcome` standard.
+
+## Core Concepts
+
+The error handling mechanism is built around the class `APIErrorResponse`.
+
+1. **`APIErrorResponse` Class**: This class is a constructor for a specific type of error. An instance of this class holds configuration for an error, such as the `HTTPStatus`, severity, and various FHIR-specific codes.
+2. **Pre-defined Error Instances**: The module defines several singleton instances of for common, application-specific errors. Examples include:
+   - `INVALID_CATEGORY_ERROR`
+   - `NHS_NUMBER_MISMATCH_ERROR`
+   - `INTERNAL_SERVER_ERROR`
+3. **`log_and_generate_response()` Method**: This is the primary method to be used. When called on an `APIErrorResponse` instance, it performs two actions:
+   - Logs the error with a detailed internal message.
+   - Generates a complete HTTP response dictionary (`statusCode`, `headers`, `body`) containing a FHIR-compliant `OperationOutcome` payload.
+
+## How to Use
+
+The primary way to handle errors is to import a pre-defined error object from `api_error_response.py` and call its `log_and_generate_response()` method.
+
+### 1. Handling Specific, Known Errors
+
+For handling validation failures or other expected error conditions, use one of the pre-defined error instances.
+The `wrapper.py` module uses this pattern to validate query parameters. If a parameter is invalid, it calls the corresponding error function.
+
+#### Example: Invalid "category" parameter
+
+``` python
+# wrapper.py
+
+from eligibility_signposting_api.api_error_response import INVALID_CATEGORY_ERROR
+
+def get_category_error_response(category: str) -> dict[str, Any]:
+    """Generates an error response for an invalid category."""
+
+    return INVALID_CATEGORY_ERROR.log_and_generate_response(
+        log_message=f"Invalid category query param: '{category}'",
+        diagnostics=f"{category} is not a category that is supported by the API",
+        location_param="category"
+    )
+```
+
+#### Key Parameters for `log_and_generate_response()`
+
+- `log_message`: A detailed message for internal logging. This should contain specific information useful for debugging.
+- `diagnostics`: The user-facing error message that will be included in the API response body.
+- `location_param` (optional): The name of the parameter that caused the error. This helps pinpoint the issue for API consumers.
+
+### 2. Handling Unexpected Exceptions (Global Error Handler)
+
+For unexpected errors, a global exception handler in `error_handler.py` catches any unhandled exception and returns a generic 500 Internal Server Error. This prevents sensitive information from leaking in stack traces.
+
+``` python
+# error_handler.py
+
+from eligibility_signposting_api.api_error_response import INTERNAL_SERVER_ERROR
+
+def handle_exception(e: Exception) -> ResponseReturnValue | HTTPException:
+    # Generate a generic, safe response for the client
+    response = INTERNAL_SERVER_ERROR.log_and_generate_response(
+        log_message=f"An unexpected error occurred: {traceback.format_exception(e)}",
+        diagnostics="An unexpected error occurred."
+    )
+    return make_response(response.get("body"), response.get("statusCode"), response.get("headers"))
+```
+
+### 3. Creating New Error Types
+
+If a new, reusable error condition is identified, you should add a new instance of `APIErrorResponse` to `api_error_response.py`
+Follow the existing pattern:
+
+``` python
+# api_error_response.py
+
+# ... (other error definitions)
+
+SOME_NEW_ERROR = APIErrorResponse(
+    status_code=HTTPStatus.BAD_REQUEST,
+    fhir_issue_code=FHIRIssueCode.VALUE,
+    fhir_issue_severity=FHIRIssueSeverity.ERROR,
+    fhir_coding_system=FHIR_SPINE_ERROR_CODE_SYSTEM,
+    fhir_error_code=FHIRSpineErrorCode.INVALID_PARAMETER,
+    fhir_display_message="A new specific error message for display",
+)
+```
+
+By centralizing error definitions, we ensure that the API provides a consistent and predictable experience for its consumers.

src/eligibility_signposting_api/common/api-error-response-readme.md

@@ -5,7 +5,7 @@
 from flask.typing import ResponseReturnValue
 from werkzeug.exceptions import HTTPException
 
-from eligibility_signposting_api.api_error_response import INTERNAL_SERVER_ERROR
+from eligibility_signposting_api.common.api_error_response import INTERNAL_SERVER_ERROR
 
 logger = logging.getLogger(__name__)
 

…ty_signposting_api/api_error_response.py …posting_api/common/api_error_response.pysrc/eligibility_signposting_api/api_error_response.py renamed to src/eligibility_signposting_api/common/api_error_response.py src/eligibility_signposting_api/api_error_response.py renamed to src/eligibility_signposting_api/common/api_error_response.py

@@ -6,7 +6,7 @@
 
 from mangum.types import LambdaContext, LambdaEvent
 
-from eligibility_signposting_api.api_error_response import (
+from eligibility_signposting_api.common.api_error_response import (
     INVALID_CATEGORY_ERROR,
     INVALID_CONDITION_FORMAT_ERROR,
     INVALID_INCLUDE_ACTIONS_ERROR,

…ibility_signposting_api/error_handler.py …_signposting_api/common/error_handler.pysrc/eligibility_signposting_api/error_handler.py renamed to src/eligibility_signposting_api/common/error_handler.py src/eligibility_signposting_api/error_handler.py renamed to src/eligibility_signposting_api/common/error_handler.py

@@ -5,7 +5,7 @@
 from boto3.resources.base import ServiceResource
 from wireup import Inject, service
 
-from eligibility_signposting_api.model.eligibility import NHSNumber
+from eligibility_signposting_api.model.eligibility_status import NHSNumber
 from eligibility_signposting_api.repos.exceptions import NotFoundError
 
 logger = logging.getLogger(__name__)

…c/eligibility_signposting_api/wrapper.py …nposting_api/common/request_validator.pysrc/eligibility_signposting_api/wrapper.py renamed to src/eligibility_signposting_api/common/request_validator.py src/eligibility_signposting_api/wrapper.py renamed to src/eligibility_signposting_api/common/request_validator.py

@@ -24,8 +24,8 @@
 
 from wireup import service
 
-from eligibility_signposting_api.model import eligibility, rules
-from eligibility_signposting_api.model.eligibility import (
+from eligibility_signposting_api.model import eligibility_status, rules
+from eligibility_signposting_api.model.eligibility_status import (
     ActionCode,
     ActionDescription,
     ActionType,
@@ -58,15 +58,15 @@ class EligibilityCalculator:
     person_data: Row
     campaign_configs: Collection[rules.CampaignConfig]
 
-    results: list[eligibility.Condition] = field(default_factory=list)
+    results: list[eligibility_status.Condition] = field(default_factory=list)
 
     @property
     def active_campaigns(self) -> list[rules.CampaignConfig]:
         return [cc for cc in self.campaign_configs if cc.campaign_live]
 
     def campaigns_grouped_by_condition_name(
         self, conditions: list[str], category: str
-    ) -> Iterator[tuple[eligibility.ConditionName, list[rules.CampaignConfig]]]:
+    ) -> Iterator[tuple[eligibility_status.ConditionName, list[rules.CampaignConfig]]]:
         """Generator that yields campaign groups filtered by condition names and campaign category."""
 
         mapping = {
@@ -100,9 +100,9 @@ def get_the_best_cohort_memberships(
         cohort_results: dict[str, CohortGroupResult],
     ) -> tuple[Status, list[CohortGroupResult]]:
         if not cohort_results:
-            return eligibility.Status.not_eligible, []
+            return eligibility_status.Status.not_eligible, []
 
-        best_status = eligibility.Status.best(*[result.status for result in cohort_results.values()])
+        best_status = eligibility_status.Status.best(*[result.status for result in cohort_results.values()])
         best_cohorts = [result for result in cohort_results.values() if result.status == best_status]
 
         best_cohorts = [
@@ -158,7 +158,7 @@ def get_action_rules_components(
 
     def evaluate_eligibility(
         self, include_actions: str, conditions: list[str], category: str
-    ) -> eligibility.EligibilityStatus:
+    ) -> eligibility_status.EligibilityStatus:
         include_actions_flag = include_actions.upper() == "Y"
         condition_results: dict[ConditionName, IterationResult] = {}
         actions: list[SuggestedAction] | None = []
@@ -186,7 +186,7 @@ def evaluate_eligibility(
                     ),
                 ) = max(iteration_results.items(), key=lambda item: item[1][1].status.value)
             else:
-                best_candidate = IterationResult(eligibility.Status.not_eligible, [], actions)
+                best_candidate = IterationResult(eligibility_status.Status.not_eligible, [], actions)
                 best_campaign_id = None
                 best_campaign_version = None
                 best_active_iteration = None
@@ -233,7 +233,7 @@ def evaluate_eligibility(
 
         # Consolidate all the results and return
         final_result = self.build_condition_results(condition_results)
-        return eligibility.EligibilityStatus(conditions=final_result)
+        return eligibility_status.EligibilityStatus(conditions=final_result)
 
     def get_iteration_results(
         self, actions: list[SuggestedAction] | None, campaign_group: list[CampaignConfig]
@@ -406,20 +406,20 @@ def evaluate_suppression_rules(
 
     def evaluate_rules_priority_group(
         self, rules_group: Iterator[rules.IterationRule]
-    ) -> tuple[eligibility.Status, list[eligibility.Reason], bool]:
+    ) -> tuple[eligibility_status.Status, list[eligibility_status.Reason], bool]:
         is_rule_stop = False
         exclusion_reasons = []
-        best_status = eligibility.Status.not_eligible
+        best_status = eligibility_status.Status.not_eligible
 
         for rule in rules_group:
             is_rule_stop = rule.rule_stop or is_rule_stop
             rule_calculator = RuleCalculator(person_data=self.person_data, rule=rule)
             status, reason = rule_calculator.evaluate_exclusion()
             if status.is_exclusion:
-                best_status = eligibility.Status.best(status, best_status)
+                best_status = eligibility_status.Status.best(status, best_status)
                 exclusion_reasons.append(reason)
             else:
-                best_status = eligibility.Status.actionable
+                best_status = eligibility_status.Status.actionable
 
         return best_status, exclusion_reasons, is_rule_stop