goodmap 1.1.14__py3-none-any.whl → 1.3.0__py3-none-any.whl

goodmap/admin_api.py

@@ -0,0 +1,251 @@
+import logging
+import uuid
+from typing import Any, Type
+
+from flask import Blueprint, jsonify, make_response, request
+from spectree import Response, SpecTree
+from werkzeug.exceptions import BadRequest
+
+from goodmap.api_models import (
+    ErrorResponse,
+    ReportUpdateRequest,
+    SuggestionStatusRequest,
+)
+from goodmap.exceptions import (
+    LocationAlreadyExistsError,
+    LocationNotFoundError,
+    LocationValidationError,
+    ReportNotFoundError,
+)
+
+# Error message constants
+ERROR_INVALID_REQUEST_DATA = "Invalid request data"
+ERROR_INVALID_LOCATION_DATA = "Invalid location data"
+ERROR_INTERNAL_ERROR = "An internal error occurred"
+ERROR_LOCATION_NOT_FOUND = "Location not found"
+
+logger = logging.getLogger(__name__)
+
+
+def _clean_model_name(model: Type[Any]) -> str:
+    return model.__name__
+
+
+def _handle_location_validation_error(e: LocationValidationError):
+    """Handle LocationValidationError and return appropriate response."""
+    logger.warning(
+        "Location validation failed",
+        extra={"uuid": e.uuid, "errors": e.validation_errors},
+    )
+    return make_response(jsonify({"message": ERROR_INVALID_LOCATION_DATA}), 400)
+
+
+def _get_locations_handler(database):
+    """Handle GET /locations request."""
+    query_params = request.args.to_dict(flat=False)
+    if "sort_by" not in query_params:
+        query_params["sort_by"] = ["name"]
+    result = database.get_locations_paginated(query_params)
+    return jsonify(result)
+
+
+def _create_location_handler(database, location_model):
+    """Handle POST /locations request."""
+    location_data = request.get_json()
+    if location_data is None:
+        logger.warning("Empty or invalid JSON in admin create location endpoint")
+        return make_response(jsonify({"message": ERROR_INVALID_REQUEST_DATA}), 400)
+    # TODO: Catch pydantic.ValidationError separately to return 400 instead of 500
+    try:
+        location_data.update({"uuid": str(uuid.uuid4())})
+        location = location_model.model_validate(location_data)
+        database.add_location(location.model_dump())
+    except LocationValidationError as e:
+        return _handle_location_validation_error(e)
+    except Exception:
+        logger.error("Error creating location", exc_info=True)
+        return make_response(jsonify({"message": ERROR_INTERNAL_ERROR}), 500)
+    return jsonify(location.model_dump())
+
+
+def _update_location_handler(database, location_model, location_id):
+    """Handle PUT /locations/<location_id> request."""
+    location_data = request.get_json()
+    if location_data is None:
+        logger.warning("Empty or invalid JSON in admin update location endpoint")
+        return make_response(jsonify({"message": ERROR_INVALID_REQUEST_DATA}), 400)
+    # TODO: Catch pydantic.ValidationError separately to return 400 instead of 500
+    try:
+        location_data.update({"uuid": location_id})
+        location = location_model.model_validate(location_data)
+        database.update_location(location_id, location.model_dump())
+    except LocationValidationError as e:
+        return _handle_location_validation_error(e)
+    except LocationNotFoundError as e:
+        logger.info("Location not found for update", extra={"uuid": e.uuid})
+        return make_response(jsonify({"message": ERROR_LOCATION_NOT_FOUND}), 404)
+    except Exception:
+        logger.error("Error updating location", exc_info=True)
+        return make_response(jsonify({"message": ERROR_INTERNAL_ERROR}), 500)
+    return jsonify(location.model_dump())
+
+
+def _delete_location_handler(database, location_id):
+    """Handle DELETE /locations/<location_id> request."""
+    try:
+        database.delete_location(location_id)
+    except LocationNotFoundError as e:
+        logger.info("Location not found for deletion", extra={"uuid": e.uuid})
+        return make_response(jsonify({"message": ERROR_LOCATION_NOT_FOUND}), 404)
+    except Exception:
+        logger.error("Error deleting location", exc_info=True)
+        return make_response(jsonify({"message": ERROR_INTERNAL_ERROR}), 500)
+    return "", 204
+
+
+def _get_suggestions_handler(database):
+    """Handle GET /suggestions request."""
+    query_params = request.args.to_dict(flat=False)
+    result = database.get_suggestions_paginated(query_params)
+    return jsonify(result)
+
+
+def _update_suggestion_handler(database, suggestion_id):
+    """Handle PUT /suggestions/<suggestion_id> request."""
+    try:
+        data = request.get_json()
+        status = data["status"]  # Validated by Spectree
+        suggestion = database.get_suggestion(suggestion_id)
+        if not suggestion:
+            return make_response(jsonify({"message": "Suggestion not found"}), 404)
+        if suggestion.get("status") != "pending":
+            return make_response(jsonify({"message": "Suggestion already processed"}), 409)
+        if status == "accepted":
+            suggestion_data = {k: v for k, v in suggestion.items() if k != "status"}
+            database.add_location(suggestion_data)
+        database.update_suggestion(suggestion_id, status)
+    except LocationValidationError as e:
+        logger.warning(
+            "Location validation failed in suggestion",
+            extra={"uuid": e.uuid, "errors": e.validation_errors},
+        )
+        return make_response(jsonify({"message": ERROR_INVALID_LOCATION_DATA}), 400)
+    except LocationAlreadyExistsError as e:
+        logger.warning(
+            "Attempted to create duplicate location from suggestion", extra={"uuid": e.uuid}
+        )
+        return make_response(jsonify({"message": "Location already exists"}), 409)
+    except Exception:
+        logger.error("Error processing suggestion", exc_info=True)
+        return make_response(jsonify({"message": ERROR_INTERNAL_ERROR}), 500)
+    return jsonify(database.get_suggestion(suggestion_id))
+
+
+def _get_reports_handler(database):
+    """Handle GET /reports request."""
+    query_params = request.args.to_dict(flat=False)
+    result = database.get_reports_paginated(query_params)
+    return jsonify(result)
+
+
+def _update_report_handler(database, report_id):
+    """Handle PUT /reports/<report_id> request."""
+    try:
+        data = request.get_json()
+        status = data.get("status")
+        priority = data.get("priority")
+        report = database.get_report(report_id)
+        if not report:
+            return make_response(jsonify({"message": "Report not found"}), 404)
+        database.update_report(report_id, status=status, priority=priority)
+    except BadRequest:
+        logger.warning("Invalid JSON in report update endpoint")
+        return make_response(jsonify({"message": ERROR_INVALID_REQUEST_DATA}), 400)
+    except ReportNotFoundError as e:
+        logger.info("Report not found for update", extra={"uuid": e.uuid})
+        return make_response(jsonify({"message": "Report not found"}), 404)
+    except Exception:
+        logger.error("Error updating report", exc_info=True)
+        return make_response(jsonify({"message": ERROR_INTERNAL_ERROR}), 500)
+    return jsonify(database.get_report(report_id))
+
+
+def admin_pages(database, location_model) -> Blueprint:
+    """Create and return the admin API blueprint.
+
+    Args:
+        database: Database instance for data operations
+        location_model: Pydantic model for location validation
+
+    Returns:
+        Blueprint: Flask blueprint with all admin endpoints
+    """
+    admin_api_blueprint = Blueprint("admin_api", __name__, url_prefix="/api/admin")
+
+    spec = SpecTree(
+        "flask",
+        title="Goodmap Admin API",
+        version="0.1",
+        path="doc",
+        annotations=True,
+        naming_strategy=_clean_model_name,
+    )
+
+    @admin_api_blueprint.route("/locations", methods=["GET"])
+    @spec.validate()
+    def admin_get_locations():
+        """Get paginated list of all locations for admin panel."""
+        return _get_locations_handler(database)
+
+    @admin_api_blueprint.route("/locations", methods=["POST"])
+    @spec.validate(resp=Response(HTTP_400=ErrorResponse))
+    def admin_create_location():
+        """Create a new location (admin only)."""
+        return _create_location_handler(database, location_model)
+
+    @admin_api_blueprint.route("/locations/<location_id>", methods=["PUT"])
+    @spec.validate(resp=Response(HTTP_400=ErrorResponse, HTTP_404=ErrorResponse))
+    def admin_update_location(location_id):
+        """Update an existing location (admin only)."""
+        return _update_location_handler(database, location_model, location_id)
+
+    @admin_api_blueprint.route("/locations/<location_id>", methods=["DELETE"])
+    @spec.validate(resp=Response(HTTP_404=ErrorResponse))
+    def admin_delete_location(location_id):
+        """Delete a location (admin only)."""
+        return _delete_location_handler(database, location_id)
+
+    @admin_api_blueprint.route("/suggestions", methods=["GET"])
+    @spec.validate()
+    def admin_get_suggestions():
+        """Get paginated list of location suggestions (admin only)."""
+        return _get_suggestions_handler(database)
+
+    @admin_api_blueprint.route("/suggestions/<suggestion_id>", methods=["PUT"])
+    @spec.validate(
+        json=SuggestionStatusRequest,
+        resp=Response(HTTP_400=ErrorResponse, HTTP_404=ErrorResponse, HTTP_409=ErrorResponse),
+    )
+    def admin_update_suggestion(suggestion_id):
+        """Accept or reject a location suggestion (admin only)."""
+        return _update_suggestion_handler(database, suggestion_id)
+
+    @admin_api_blueprint.route("/reports", methods=["GET"])
+    @spec.validate()
+    def admin_get_reports():
+        """Get paginated list of location reports (admin only)."""
+        return _get_reports_handler(database)
+
+    @admin_api_blueprint.route("/reports/<report_id>", methods=["PUT"])
+    @spec.validate(
+        json=ReportUpdateRequest,
+        resp=Response(HTTP_400=ErrorResponse, HTTP_404=ErrorResponse),
+    )
+    def admin_update_report(report_id):
+        """Update a report's status and/or priority (admin only)."""
+        return _update_report_handler(database, report_id)
+
+    # Register Spectree with blueprint after all routes are defined
+    spec.register(admin_api_blueprint)
+
+    return admin_api_blueprint

goodmap/api_models.py

@@ -0,0 +1,105 @@
+"""Pydantic models for API request/response validation.
+
+This module defines request and response models for the Goodmap REST API.
+These models are used by Spectree for automatic OpenAPI schema generation
+and request/response validation.
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class LocationReportRequest(BaseModel):
+    """Request model for reporting a location issue."""
+
+    id: str = Field(..., description="Location UUID to report")
+    description: str = Field(..., min_length=1, description="Description of the problem")
+
+
+class LocationReportResponse(BaseModel):
+    """Response model for location report submission."""
+
+    message: str = Field(..., description="Success message")
+
+
+class SuggestionStatusRequest(BaseModel):
+    """Request model for updating suggestion status."""
+
+    status: Literal["accepted", "rejected"] = Field(
+        ..., description="Status to set for the suggestion"
+    )
+
+
+class ReportUpdateRequest(BaseModel):
+    """Request model for updating a report's status and priority."""
+
+    status: Literal["resolved", "rejected"] | None = Field(
+        None, description="New status for the report"
+    )
+    priority: Literal["critical", "high", "medium", "low"] | None = Field(
+        None, description="New priority for the report"
+    )
+
+
+class VersionResponse(BaseModel):
+    """Response model for version endpoint."""
+
+    backend: str = Field(..., description="Backend version")
+
+
+class CSRFTokenResponse(BaseModel):
+    """Response model for CSRF token endpoint (deprecated)."""
+
+    csrf_token: str = Field(..., description="CSRF token")
+
+
+class PaginationParams(BaseModel):
+    """Common pagination and filtering parameters."""
+
+    page: int | None = Field(None, ge=1, description="Page number (1-indexed)")
+    per_page: int | None = Field(None, ge=1, le=100, description="Items per page")
+    sort_by: str | None = Field(None, description="Field to sort by")
+    sort_order: Literal["asc", "desc"] | None = Field(None, description="Sort direction")
+
+
+class ClusteringParams(BaseModel):
+    """Parameters for clustering request."""
+
+    zoom: int = Field(7, ge=0, le=16, description="Map zoom level for clustering")
+
+
+class ErrorResponse(BaseModel):
+    """Standard error response."""
+
+    message: str = Field(..., description="Error message")
+    error: str | None = Field(None, description="Detailed error information")
+
+
+class SuccessResponse(BaseModel):
+    """Standard success response."""
+
+    message: str = Field(..., description="Success message")
+
+
+class BasicLocationInfo(BaseModel):
+    """Basic location information (uuid + position)."""
+
+    uuid: str = Field(..., description="Location UUID")
+    position: tuple[float, float] = Field(
+        ..., description="Location coordinates as (latitude, longitude)"
+    )
+    remark: bool = Field(False, description="Whether location has a remark")
+
+
+class ClusterInfo(BaseModel):
+    """Cluster information for map display."""
+
+    uuid: str | None = Field(None, description="Location UUID (None for multi-point clusters)")
+    position: tuple[float, float] = Field(..., description="Cluster center coordinates")
+    count: int = Field(..., description="Number of locations in cluster")
+
+
+# Note: Full location model is dynamically created from LocationBase
+# and cannot be statically defined here. API endpoints will use the
+# dynamically created location_model passed to core_pages() function.

goodmap/core.py

@@ -1,9 +1,20 @@
+"""Core data filtering and sorting utilities for location queries."""
+
 from typing import Any, Dict, List
 
 # TODO move filtering to db site
 
 
 def does_fulfill_requirement(entry, requirements):
+    """Check if an entry fulfills all category requirements.
+
+    Args:
+        entry: Location data entry to check
+        requirements: List of (category, values) tuples to match
+
+    Returns:
+        bool: True if entry matches all non-empty requirements
+    """
     matches = []
     for category, values in requirements:
         if not values:
@@ -13,6 +24,15 @@ def does_fulfill_requirement(entry, requirements):
 
 
 def sort_by_distance(data: List[Dict[str, Any]], query_params: Dict[str, List[str]]):
+    """Sort locations by distance from query coordinates.
+
+    Args:
+        data: List of location dictionaries
+        query_params: Query parameters containing 'lat' and 'lon'
+
+    Returns:
+        List[Dict[str, Any]]: Sorted data (or original if no coordinates provided)
+    """
     try:
         if "lat" in query_params and "lon" in query_params:
             lat = float(query_params["lat"][0])
@@ -25,6 +45,15 @@ def sort_by_distance(data: List[Dict[str, Any]], query_params: Dict[str, List[st
 
 
 def limit(data, query_params):
+    """Limit number of results based on query parameter.
+
+    Args:
+        data: List of data to limit
+        query_params: Query parameters containing optional 'limit'
+
+    Returns:
+        Limited data (or original if no limit specified)
+    """
     try:
         if "limit" in query_params:
             limit = int(query_params["limit"][0])
@@ -36,6 +65,16 @@ def limit(data, query_params):
 
 
 def get_queried_data(all_data, categories, query_params):
+    """Filter, sort, and limit location data based on query parameters.
+
+    Args:
+        all_data: Complete list of location data
+        categories: Available categories for filtering
+        query_params: Query parameters for filtering, sorting, and limiting
+
+    Returns:
+        Filtered, sorted, and limited location data
+    """
     requirements = []
     for key in categories.keys():
         requirements.append((key, query_params.get(key)))