stac-fastapi-core 4.0.0a1__py3-none-any.whl

stac_fastapi/core/route_dependencies.py

@@ -0,0 +1,176 @@
+"""Route Dependencies Module."""
+
+import importlib
+import inspect
+import json
+import logging
+import os
+from typing import List
+
+from fastapi import Depends
+from jsonschema import validate
+
+_LOGGER = logging.getLogger("uvicorn.default")
+
+
+route_dependencies_schema = {
+    "type": "array",
+    "items": {
+        "type": "object",
+        "properties": {
+            "routes": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "method": {
+                            "anyOf": [
+                                {"$ref": "#/$defs/method"},
+                                {
+                                    "type": "array",
+                                    "items": {"$ref": "#/$defs/method"},
+                                    "uniqueItems": True,
+                                },
+                            ]
+                        },
+                        "path": {
+                            "anyOf": [
+                                {"$ref": "#/$defs/path"},
+                                {
+                                    "type": "array",
+                                    "items": {"$ref": "#/$defs/path"},
+                                    "uniqueItems": True,
+                                },
+                            ]
+                        },
+                        "type": {"type": "string"},
+                    },
+                    "required": ["method", "path"],
+                    "additionalProperties": False,
+                },
+            },
+            "dependencies": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "method": {"type": "string"},
+                        "args": {"type": "string"},
+                        "kwargs": {"type": "object"},
+                    },
+                    "required": ["method"],
+                    "additionalProperties": False,
+                },
+            },
+        },
+        "dependencies": {
+            "routes": ["dependencies"],
+            "dependencies": ["routes"],
+        },
+        "additionalProperties": False,
+    },
+    "$defs": {
+        "method": {
+            "type": "string",
+            "enum": ["*", "GET", "POST", "PUT", "PATCH", "DELETE"],
+        },
+        "path": {
+            "type": "string",
+            "pattern": r"^\*$|\/.*",
+        },
+    },
+}
+
+
+def get_route_dependencies_conf(route_dependencies_env: str) -> list:
+    """Get Route dependencies configuration from file or environment variable."""
+    if os.path.exists(route_dependencies_env):
+        with open(route_dependencies_env, encoding="utf-8") as route_dependencies_file:
+            route_dependencies_conf = json.load(route_dependencies_file)
+
+    else:
+        try:
+            route_dependencies_conf = json.loads(route_dependencies_env)
+        except json.JSONDecodeError as exception:
+            _LOGGER.error("Invalid JSON format for route dependencies. %s", exception)
+            raise
+
+    validate(instance=route_dependencies_conf, schema=route_dependencies_schema)
+
+    return route_dependencies_conf
+
+
+def get_routes(route_dependency_conf: dict) -> list:
+    """Get routes from route dependency configuration."""
+    # seperate out any path lists
+    intermediate_routes = []
+    for route in route_dependency_conf["routes"]:
+
+        if isinstance(route["path"], list):
+            for path in route["path"]:
+                intermediate_routes.append({**route, "path": path})
+
+        else:
+            intermediate_routes.append(route)
+
+    # seperate out any method lists
+    routes = []
+    for route in intermediate_routes:
+
+        if isinstance(route["method"], list):
+            for method in route["method"]:
+                routes.append({**route, "method": method})
+
+        else:
+            routes.append(route)
+
+    return routes
+
+
+def get_dependencies(route_dependency_conf: dict) -> list:
+    """Get dependencies from route dependency configuration."""
+    dependencies = []
+    for dependency_conf in route_dependency_conf["dependencies"]:
+
+        module_name, method_name = dependency_conf["method"].rsplit(".", 1)
+        module = importlib.import_module(module_name)
+        dependency = getattr(module, method_name)
+
+        if inspect.isclass(dependency):
+
+            dependency = dependency(
+                *dependency_conf.get("args", []), **dependency_conf.get("kwargs", {})
+            )
+
+        dependencies.append(Depends(dependency))
+
+    return dependencies
+
+
+def get_route_dependencies(route_dependencies_env: str = "") -> list:
+    """
+    Route dependencies generator.
+
+    Generate a set of route dependencies for authentication to the
+    provided FastAPI application.
+    """
+    route_dependencies_env = os.environ.get(
+        "STAC_FASTAPI_ROUTE_DEPENDENCIES", route_dependencies_env
+    )
+    route_dependencies: List[tuple] = []
+
+    if not route_dependencies_env:
+        _LOGGER.info("Authentication skipped.")
+        return route_dependencies
+
+    _LOGGER.info("Authentication enabled.")
+
+    route_dependencies_conf = get_route_dependencies_conf(route_dependencies_env)
+
+    for route_dependency_conf in route_dependencies_conf:
+
+        routes = get_routes(route_dependency_conf)
+        dependencies = get_dependencies(route_dependency_conf)
+        route_dependencies.append((routes, dependencies))
+
+    return route_dependencies

stac_fastapi/core/serializers.py

@@ -0,0 +1,177 @@
+"""Serializers."""
+import abc
+from copy import deepcopy
+from typing import Any, List, Optional
+
+import attr
+from starlette.requests import Request
+
+from stac_fastapi.core.datetime_utils import now_to_rfc3339_str
+from stac_fastapi.core.models.links import CollectionLinks
+from stac_fastapi.types import stac as stac_types
+from stac_fastapi.types.links import ItemLinks, resolve_links
+
+
+@attr.s
+class Serializer(abc.ABC):
+    """Defines serialization methods between the API and the data model.
+
+    This class is meant to be subclassed and implemented by specific serializers for different STAC objects (e.g. Item, Collection).
+    """
+
+    @classmethod
+    @abc.abstractmethod
+    def db_to_stac(cls, item: dict, base_url: str) -> Any:
+        """Transform database model to STAC object.
+
+        Arguments:
+            item (dict): A dictionary representing the database model.
+            base_url (str): The base URL of the STAC API.
+
+        Returns:
+            Any: A STAC object, e.g. an `Item` or `Collection`, representing the input `item`.
+        """
+        ...
+
+    @classmethod
+    @abc.abstractmethod
+    def stac_to_db(cls, stac_object: Any, base_url: str) -> dict:
+        """Transform STAC object to database model.
+
+        Arguments:
+            stac_object (Any): A STAC object, e.g. an `Item` or `Collection`.
+            base_url (str): The base URL of the STAC API.
+
+        Returns:
+            dict: A dictionary representing the database model.
+        """
+        ...
+
+
+class ItemSerializer(Serializer):
+    """Serialization methods for STAC items."""
+
+    @classmethod
+    def stac_to_db(cls, stac_data: stac_types.Item, base_url: str) -> stac_types.Item:
+        """Transform STAC item to database-ready STAC item.
+
+        Args:
+            stac_data (stac_types.Item): The STAC item object to be transformed.
+            base_url (str): The base URL for the STAC API.
+
+        Returns:
+            stac_types.Item: The database-ready STAC item object.
+        """
+        item_links = resolve_links(stac_data.get("links", []), base_url)
+        stac_data["links"] = item_links
+
+        now = now_to_rfc3339_str()
+        if "created" not in stac_data["properties"]:
+            stac_data["properties"]["created"] = now
+        stac_data["properties"]["updated"] = now
+        return stac_data
+
+    @classmethod
+    def db_to_stac(cls, item: dict, base_url: str) -> stac_types.Item:
+        """Transform database-ready STAC item to STAC item.
+
+        Args:
+            item (dict): The database-ready STAC item to be transformed.
+            base_url (str): The base URL for the STAC API.
+
+        Returns:
+            stac_types.Item: The STAC item object.
+        """
+        item_id = item["id"]
+        collection_id = item["collection"]
+        item_links = ItemLinks(
+            collection_id=collection_id, item_id=item_id, base_url=base_url
+        ).create_links()
+
+        original_links = item.get("links", [])
+        if original_links:
+            item_links += resolve_links(original_links, base_url)
+
+        return stac_types.Item(
+            type="Feature",
+            stac_version=item.get("stac_version", ""),
+            stac_extensions=item.get("stac_extensions", []),
+            id=item_id,
+            collection=item.get("collection", ""),
+            geometry=item.get("geometry", {}),
+            bbox=item.get("bbox", []),
+            properties=item.get("properties", {}),
+            links=item_links,
+            assets=item.get("assets", {}),
+        )
+
+
+class CollectionSerializer(Serializer):
+    """Serialization methods for STAC collections."""
+
+    @classmethod
+    def stac_to_db(
+        cls, collection: stac_types.Collection, request: Request
+    ) -> stac_types.Collection:
+        """
+        Transform STAC Collection to database-ready STAC collection.
+
+        Args:
+            stac_data: the STAC Collection object to be transformed
+            starlette.requests.Request: the API request
+
+        Returns:
+            stac_types.Collection: The database-ready STAC Collection object.
+        """
+        collection = deepcopy(collection)
+        collection["links"] = resolve_links(
+            collection.get("links", []), str(request.base_url)
+        )
+        return collection
+
+    @classmethod
+    def db_to_stac(
+        cls, collection: dict, request: Request, extensions: Optional[List[str]] = []
+    ) -> stac_types.Collection:
+        """Transform database model to STAC collection.
+
+        Args:
+            collection (dict): The collection data in dictionary form, extracted from the database.
+            starlette.requests.Request: the API request
+            extensions: A list of the extension class names (`ext.__name__`) or all enabled STAC API extensions.
+
+        Returns:
+            stac_types.Collection: The STAC collection object.
+        """
+        # Avoid modifying the input dict in-place ... doing so breaks some tests
+        collection = deepcopy(collection)
+
+        # Set defaults
+        collection_id = collection.get("id")
+        collection.setdefault("type", "Collection")
+        collection.setdefault("stac_extensions", [])
+        collection.setdefault("stac_version", "")
+        collection.setdefault("title", "")
+        collection.setdefault("description", "")
+        collection.setdefault("keywords", [])
+        collection.setdefault("license", "")
+        collection.setdefault("providers", [])
+        collection.setdefault("summaries", {})
+        collection.setdefault(
+            "extent", {"spatial": {"bbox": []}, "temporal": {"interval": []}}
+        )
+        collection.setdefault("assets", {})
+
+        # Create the collection links using CollectionLinks
+        collection_links = CollectionLinks(
+            collection_id=collection_id, request=request, extensions=extensions
+        ).create_links()
+
+        # Add any additional links from the collection dictionary
+        original_links = collection.get("links")
+        if original_links:
+            collection_links += resolve_links(original_links, str(request.base_url))
+        collection["links"] = collection_links
+
+        # Return the stac_types.Collection object
+        return stac_types.Collection(**collection)

stac_fastapi/core/session.py

@@ -0,0 +1,25 @@
+"""database session management."""
+import logging
+
+import attr
+
+logger = logging.getLogger(__name__)
+
+
+@attr.s
+class Session:
+    """Database session management."""
+
+    @classmethod
+    def create_from_env(cls):
+        """Create from environment."""
+        ...
+
+    @classmethod
+    def create_from_settings(cls, settings):
+        """Create a Session object from settings."""
+        ...
+
+    def __attrs_post_init__(self):
+        """Post init handler."""
+        ...

stac_fastapi/core/utilities.py

@@ -0,0 +1,135 @@
+"""Module for geospatial processing functions.
+
+This module contains functions for transforming geospatial coordinates,
+such as converting bounding boxes to polygon representations.
+"""
+from typing import Any, Dict, List, Optional, Set, Union
+
+from stac_fastapi.types.stac import Item
+
+MAX_LIMIT = 10000
+
+
+def bbox2polygon(b0: float, b1: float, b2: float, b3: float) -> List[List[List[float]]]:
+    """Transform a bounding box represented by its four coordinates `b0`, `b1`, `b2`, and `b3` into a polygon.
+
+    Args:
+        b0 (float): The x-coordinate of the lower-left corner of the bounding box.
+        b1 (float): The y-coordinate of the lower-left corner of the bounding box.
+        b2 (float): The x-coordinate of the upper-right corner of the bounding box.
+        b3 (float): The y-coordinate of the upper-right corner of the bounding box.
+
+    Returns:
+        List[List[List[float]]]: A polygon represented as a list of lists of coordinates.
+    """
+    return [[[b0, b1], [b2, b1], [b2, b3], [b0, b3], [b0, b1]]]
+
+
+# copied from stac-fastapi-pgstac
+# https://github.com/stac-utils/stac-fastapi-pgstac/blob/26f6d918eb933a90833f30e69e21ba3b4e8a7151/stac_fastapi/pgstac/utils.py#L10-L116
+def filter_fields(  # noqa: C901
+    item: Union[Item, Dict[str, Any]],
+    include: Optional[Set[str]] = None,
+    exclude: Optional[Set[str]] = None,
+) -> Item:
+    """Preserve and remove fields as indicated by the fields extension include/exclude sets.
+
+    Returns a shallow copy of the Item with the fields filtered.
+
+    This will not perform a deep copy; values of the original item will be referenced
+    in the return item.
+    """
+    if not include and not exclude:
+        return item
+
+    # Build a shallow copy of included fields on an item, or a sub-tree of an item
+    def include_fields(
+        source: Dict[str, Any], fields: Optional[Set[str]]
+    ) -> Dict[str, Any]:
+        if not fields:
+            return source
+
+        clean_item: Dict[str, Any] = {}
+        for key_path in fields or []:
+            key_path_parts = key_path.split(".")
+            key_root = key_path_parts[0]
+            if key_root in source:
+                if isinstance(source[key_root], dict) and len(key_path_parts) > 1:
+                    # The root of this key path on the item is a dict, and the
+                    # key path indicates a sub-key to be included. Walk the dict
+                    # from the root key and get the full nested value to include.
+                    value = include_fields(
+                        source[key_root], fields={".".join(key_path_parts[1:])}
+                    )
+
+                    if isinstance(clean_item.get(key_root), dict):
+                        # A previously specified key and sub-keys may have been included
+                        # already, so do a deep merge update if the root key already exists.
+                        dict_deep_update(clean_item[key_root], value)
+                    else:
+                        # The root key does not exist, so add it. Fields
+                        # extension only allows nested referencing on dicts, so
+                        # this won't overwrite anything.
+                        clean_item[key_root] = value
+                else:
+                    # The item value to include is not a dict, or, it is a dict but the
+                    # key path is for the whole value, not a sub-key. Include the entire
+                    # value in the cleaned item.
+                    clean_item[key_root] = source[key_root]
+            else:
+                # The key, or root key of a multi-part key, is not present in the item,
+                # so it is ignored
+                pass
+        return clean_item
+
+    # For an item built up for included fields, remove excluded fields. This
+    # modifies `source` in place.
+    def exclude_fields(source: Dict[str, Any], fields: Optional[Set[str]]) -> None:
+        for key_path in fields or []:
+            key_path_part = key_path.split(".")
+            key_root = key_path_part[0]
+            if key_root in source:
+                if isinstance(source[key_root], dict) and len(key_path_part) > 1:
+                    # Walk the nested path of this key to remove the leaf-key
+                    exclude_fields(
+                        source[key_root], fields={".".join(key_path_part[1:])}
+                    )
+                    # If, after removing the leaf-key, the root is now an empty
+                    # dict, remove it entirely
+                    if not source[key_root]:
+                        del source[key_root]
+                else:
+                    # The key's value is not a dict, or there is no sub-key to remove. The
+                    # entire key can be removed from the source.
+                    source.pop(key_root, None)
+
+    # Coalesce incoming type to a dict
+    item = dict(item)
+
+    clean_item = include_fields(item, include)
+
+    # If, after including all the specified fields, there are no included properties,
+    # return just id and collection.
+    if not clean_item:
+        return Item({"id": item["id"], "collection": item["collection"]})
+
+    exclude_fields(clean_item, exclude)
+
+    return Item(**clean_item)
+
+
+def dict_deep_update(merge_to: Dict[str, Any], merge_from: Dict[str, Any]) -> None:
+    """Perform a deep update of two dicts.
+
+    merge_to is updated in-place with the values from merge_from.
+    merge_from values take precedence over existing values in merge_to.
+    """
+    for k, v in merge_from.items():
+        if (
+            k in merge_to
+            and isinstance(merge_to[k], dict)
+            and isinstance(merge_from[k], dict)
+        ):
+            dict_deep_update(merge_to[k], merge_from[k])
+        else:
+            merge_to[k] = v

stac_fastapi/core/version.py

@@ -0,0 +1,2 @@
+"""library version."""
+__version__ = "4.0.0a1"