goodmap 0.5.2__tar.gz → 1.3.0__tar.gz

{goodmap-0.5.2 → goodmap-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: goodmap
-Version: 0.5.2
+Version: 1.3.0
 Summary: Map engine to serve all the people :)
 Author: Krzysztof Kolodzinski
 Author-email: krzysztof.kolodzinski@problematy.pl
@@ -10,6 +10,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: docs
 Requires-Dist: Babel (>=2.10.3,<3.0.0)
 Requires-Dist: Flask (==3.0.3)
 Requires-Dist: Flask-Babel (>=4.0.0,<5.0.0)
@@ -17,16 +18,23 @@ Requires-Dist: Flask-WTF (>=1.2.1,<2.0.0)
 Requires-Dist: PyYAML (>=6.0,<7.0)
 Requires-Dist: aiohttp (>=3.8.4,<4.0.0)
 Requires-Dist: deprecation (>=2.1.0,<3.0.0)
-Requires-Dist: flask-restx (>=1.3.0,<2.0.0)
 Requires-Dist: google-cloud-storage (>=2.7.0,<3.0.0)
 Requires-Dist: gql (>=3.4.0,<4.0.0)
-Requires-Dist: gunicorn (>=20.1.0,<21.0.0)
+Requires-Dist: gunicorn (>=20.1,<24.0)
 Requires-Dist: humanize (>=4.6.0,<5.0.0)
-Requires-Dist: platzky (>=0.3.6,<0.4.0)
+Requires-Dist: myst-parser (>=4.0.0,<5.0.0) ; extra == "docs"
+Requires-Dist: numpy (>=2.2.0,<3.0.0)
+Requires-Dist: platzky (>=1.0.0,<2.0.0)
 Requires-Dist: pydantic (>=2.7.1,<3.0.0)
+Requires-Dist: pysupercluster-problematy (>=0.7.8,<0.8.0)
+Requires-Dist: scipy (>=1.15.1,<2.0.0)
+Requires-Dist: spectree (>=2.0.1,<3.0.0)
+Requires-Dist: sphinx (>=8.0.0,<9.0.0) ; extra == "docs"
+Requires-Dist: sphinx-rtd-theme (>=3.0.0,<4.0.0) ; extra == "docs"
+Requires-Dist: tomli (>=2.0.0,<3.0.0) ; extra == "docs"
 Description-Content-Type: text/markdown
 
-![Github Actions](https://github.com/problematy/goodmap/actions/workflows/tests.yml/badge.svg?event=push&branch=main)
+![Github Actions](https://github.com/problematy/goodmap/actions/workflows/release.yml/badge.svg?event=push&branch=main)
 [![Coverage Status](https://coveralls.io/repos/github/Problematy/goodmap/badge.png)](https://coveralls.io/github/Problematy/goodmap)
 
 # Good Map
@@ -75,9 +83,9 @@ poetry run <command>
 
 ### TL;DR
 If you don't want to go through all the configuration, e.g. you just simply want to test if everything works,
-you can simply run app with test dataset provided in `tests/e2e_tests` directory:
+you can simply run app with test dataset provided in `examples` directory:
 
-> poetry run flask --app 'goodmap.goodmap:create_app(config_path="./tests/e2e_tests/e2e_test_config.yml")' run
+> poetry run flask --app 'goodmap.goodmap:create_app(config_path="./examples/e2e_test_config.yml")' run
 
 ### Configuration
 
@@ -95,7 +103,7 @@ Afterwards run it with:
 
 ## Database
 
-The database is stored in JSON, in the `map` section. For an example database see `tests/e2e_tests/e2e_test_data.json`. The first subsection `data` consists of the actual datapoints, representing points on a map.
+The database is stored in JSON, in the `map` section. For an example database see `examples/e2e_test_data.json`. The first subsection `data` consists of the actual datapoints, representing points on a map.
 
 Datapoints have fields. The next subsections define special types of fields:
 - `obligatory_fields` - here are explicitely stated all the fields that the application assumes are presnt in all datapoints. E.g.
@@ -123,9 +131,11 @@ You can define the fields in all these subsections. Besides these types of field
 
 ## Examples
 
-You can find examples of working configuration and database in `tests/e2e_tests` named:
-- `e2e_test_config.yml`
-- `e2e_test_data.json`
+You can find examples of working configuration and database in `examples/` directory:
+- `e2e_test_config.yml` - Basic configuration example
+- `e2e_test_data.json` - Example database with sample location data
+- `mongo_e2e_test_config.yml` - MongoDB configuration example
 
 
+# final test
 

{goodmap-0.5.2 → goodmap-1.3.0}/README.md

@@ -1,4 +1,4 @@
-![Github Actions](https://github.com/problematy/goodmap/actions/workflows/tests.yml/badge.svg?event=push&branch=main)
+![Github Actions](https://github.com/problematy/goodmap/actions/workflows/release.yml/badge.svg?event=push&branch=main)
 [![Coverage Status](https://coveralls.io/repos/github/Problematy/goodmap/badge.png)](https://coveralls.io/github/Problematy/goodmap)
 
 # Good Map
@@ -47,9 +47,9 @@ poetry run <command>
 
 ### TL;DR
 If you don't want to go through all the configuration, e.g. you just simply want to test if everything works,
-you can simply run app with test dataset provided in `tests/e2e_tests` directory:
+you can simply run app with test dataset provided in `examples` directory:
 
-> poetry run flask --app 'goodmap.goodmap:create_app(config_path="./tests/e2e_tests/e2e_test_config.yml")' run
+> poetry run flask --app 'goodmap.goodmap:create_app(config_path="./examples/e2e_test_config.yml")' run
 
 ### Configuration
 
@@ -67,7 +67,7 @@ Afterwards run it with:
 
 ## Database
 
-The database is stored in JSON, in the `map` section. For an example database see `tests/e2e_tests/e2e_test_data.json`. The first subsection `data` consists of the actual datapoints, representing points on a map.
+The database is stored in JSON, in the `map` section. For an example database see `examples/e2e_test_data.json`. The first subsection `data` consists of the actual datapoints, representing points on a map.
 
 Datapoints have fields. The next subsections define special types of fields:
 - `obligatory_fields` - here are explicitely stated all the fields that the application assumes are presnt in all datapoints. E.g.
@@ -95,8 +95,10 @@ You can define the fields in all these subsections. Besides these types of field
 
 ## Examples
 
-You can find examples of working configuration and database in `tests/e2e_tests` named:
-- `e2e_test_config.yml`
-- `e2e_test_data.json`
+You can find examples of working configuration and database in `examples/` directory:
+- `e2e_test_config.yml` - Basic configuration example
+- `e2e_test_data.json` - Example database with sample location data
+- `mongo_e2e_test_config.yml` - MongoDB configuration example
 
 
+# final test

goodmap-1.3.0/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-1.3.0/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-1.3.0/goodmap/clustering.py

@@ -0,0 +1,75 @@
+import logging
+import uuid
+
+from scipy.spatial import KDTree
+
+# Maximum distance to consider a point-cluster match (accounts for floating point errors)
+DISTANCE_THRESHOLD = 1e-8
+
+logger = logging.getLogger(__name__)
+
+
+def map_clustering_data_to_proper_lazy_loading_object(input_array):
+    response_array = []
+    for item in input_array:
+        if item["count"] == 1:
+            response_object = {
+                "position": [item["longitude"], item["latitude"]],
+                "uuid": item["uuid"],
+                "cluster_uuid": None,
+                "cluster_count": None,
+                "type": "point",
+            }
+            response_array.append(response_object)
+            continue
+        response_object = {
+            "position": [item["longitude"], item["latitude"]],
+            "uuid": None,
+            "cluster_uuid": str(uuid.uuid4()),
+            "cluster_count": item["count"],
+            "type": "cluster",
+        }
+        response_array.append(response_object)
+    return response_array
+
+
+# Since there can be some floating point errors
+# we need to check if the distance is close enough to 0
+def match_clusters_uuids(points, clusters):
+    """
+    Match single-point clusters to their original point UUIDs.
+
+    For clusters containing exactly one point, this function attempts to match the cluster
+    coordinates back to the original point to retrieve its UUID. The 'uuid' key is optional
+    and will only be present in single-point clusters where a matching point is found.
+
+    Args:
+        points: List of point dicts with 'position' and 'uuid' keys
+        clusters: List of cluster dicts with 'longitude', 'latitude', and 'count' keys.
+                 For single-point clusters (count=1), a 'uuid' key will be added if a
+                 matching point is found (modified in place)
+
+    Returns:
+        The modified clusters list with 'uuid' keys added to matched single-point clusters
+    """
+    points_coords = [(point["position"][0], point["position"][1]) for point in points]
+    tree = KDTree(points_coords)
+    for cluster in clusters:
+        if cluster["count"] == 1:
+            cluster_coords = (cluster["longitude"], cluster["latitude"])
+            dist, idx = tree.query(cluster_coords)
+            if dist < DISTANCE_THRESHOLD:
+                closest_point = points[idx]
+                cluster["uuid"] = closest_point["uuid"]
+            else:
+                # Log warning when no match is found - indicates data inconsistency
+                logger.warning(
+                    "No matching UUID found for cluster at coordinates (%f, %f). "
+                    "Distance to nearest point: %f (threshold: %f)",
+                    cluster["longitude"],
+                    cluster["latitude"],
+                    dist,
+                    DISTANCE_THRESHOLD,
+                )
+                cluster["uuid"] = None
+    return clusters

goodmap-1.3.0/goodmap/config.py

@@ -0,0 +1,42 @@
+import sys
+import typing as t
+
+import yaml
+from platzky.config import Config as PlatzkyConfig
+from pydantic import Field
+
+
+class GoodmapConfig(PlatzkyConfig):
+    """Extended configuration for Goodmap with additional frontend library URL."""
+
+    goodmap_frontend_lib_url: str = Field(
+        default="https://cdn.jsdelivr.net/npm/@problematy/goodmap@1.0.4",
+        alias="GOODMAP_FRONTEND_LIB_URL",
+    )
+
+    @classmethod
+    def model_validate(
+        cls,
+        obj: t.Any,
+        *,
+        strict: bool | None = None,
+        from_attributes: bool | None = None,
+        context: dict[str, t.Any] | None = None,
+    ) -> "GoodmapConfig":
+        """Override to return correct type for GoodmapConfig."""
+        return t.cast(
+            "GoodmapConfig",
+            super().model_validate(
+                obj, strict=strict, from_attributes=from_attributes, context=context
+            ),
+        )
+
+    @classmethod
+    def parse_yaml(cls, path: str) -> "GoodmapConfig":
+        """Parse YAML configuration file and return GoodmapConfig instance."""
+        try:
+            with open(path, "r") as f:
+                return cls.model_validate(yaml.safe_load(f))
+        except FileNotFoundError:
+            print(f"Config file not found: {path}", file=sys.stderr)
+            raise SystemExit(1)

{goodmap-0.5.2 → goodmap-1.3.0}/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)))