bookalimo 0.1.5__py3-none-any.whl → 1.0.1__py3-none-any.whl

bookalimo/integrations/google_places/common.py

@@ -0,0 +1,231 @@
+"""
+Common utilities and shared functionality for Google Places clients.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Optional
+
+from ...logging import get_logger
+from ...schemas.places import (
+    AddressComponent,
+    AddressDescriptor,
+    FieldMaskInput,
+    GooglePlace,
+    Place,
+    PlaceType,
+    compile_field_mask,
+)
+from ...schemas.places import (
+    google as models,
+)
+
+logger = get_logger("places")
+
+# Default field mask for places queries
+DEFAULT_PLACE_FIELDS = (
+    "display_name",
+    "formatted_address",
+    "location",
+)
+
+ADDRESS_TYPES = {
+    "street_address",
+    "route",
+    "intersection",
+    "premise",
+    "subpremise",
+    "plus_code",
+    "postal_code",
+    "locality",
+    "sublocality",
+    "neighborhood",
+    "administrative_area_level_1",
+    "administrative_area_level_2",
+    "country",
+    "floor",
+    "room",
+}
+
+
+def fmt_exc(e: BaseException) -> str:
+    """Format exception for logging without touching non-existent attributes."""
+    return f"{type(e).__name__}: {e}"
+
+
+def mask_header(
+    fields: FieldMaskInput, prefix: str = ""
+) -> tuple[tuple[str, str], ...]:
+    """
+    Build the X-Goog-FieldMask header. Pass a comma-separated string or a sequence.
+    If None, no header is added (e.g., autocomplete, get_photo_media).
+    """
+    if fields is None:
+        return ()  # type: ignore[unreachable]
+    value = compile_field_mask(fields, prefix=prefix)
+    return (("x-goog-fieldmask", ",".join(value)),)
+
+
+def strip_html(s: str) -> str:
+    # Simple fallback for adr_format_address (which is HTML)
+    return re.sub(r"<[^>]+>", "", s) if s else s
+
+
+def infer_place_type(m: GooglePlace) -> PlaceType:
+    # 1) Airport wins outright
+    tset = set(m.types or [])
+    ptype = (m.primary_type or "").lower() if getattr(m, "primary_type", None) else ""
+    if "airport" in tset or ptype == "airport":
+        return PlaceType.AIRPORT
+    # 2) Anything that looks like a geocoded address
+    if tset & ADDRESS_TYPES:
+        return PlaceType.ADDRESS
+    # 3) Otherwise treat as a point of interest
+    return PlaceType.POI
+
+
+def get_lat_lng(model: GooglePlace) -> tuple[float, float]:
+    if model.location:
+        lat = model.location.latitude
+        lng = model.location.longitude
+    elif model.viewport:
+        lat = model.viewport.low.latitude
+        lng = model.viewport.low.longitude
+    else:
+        lat = 0
+        lng = 0
+    return lat, lng
+
+
+def name_from_place(p: Place) -> Optional[str]:
+    # Try common fields; support Google Places v1 structure where display_name may have `.text`
+    gp = getattr(p, "google_place", None)
+    candidates = [
+        getattr(gp, "display_name", None),
+        getattr(gp, "name", None),
+        getattr(p, "name", None),
+        getattr(p, "address_descriptor", None),
+        getattr(p, "address_components", None),
+        getattr(p, "formatted_address", None),
+    ]
+    for c in candidates:
+        if not c:
+            continue
+
+        maybe_text = getattr(c, "text", c)
+        if isinstance(maybe_text, str) and maybe_text.strip():
+            return maybe_text.strip()
+        elif isinstance(maybe_text, AddressDescriptor):
+            return maybe_text.landmarks[0].display_name.text
+        elif isinstance(maybe_text, list):
+            for item in maybe_text:
+                if isinstance(item, AddressComponent):
+                    return item.long_text
+                else:
+                    break
+    return None
+
+
+def build_search_request_params(
+    query: Optional[str],
+    request: Optional[models.SearchTextRequest],
+    **kwargs: Any,
+) -> dict[str, Any]:
+    """Build request parameters for search_text API call."""
+    if query is None and request is None:
+        raise ValueError("Either 'query' or 'request' must be provided")
+    if query is not None and request is not None:
+        raise ValueError(
+            "Only one of 'query' or 'request' should be provided, not both"
+        )
+
+    if request is not None:
+        request_params = request.model_dump(exclude_none=True)
+        request_params.update(kwargs)
+        return request_params
+    else:
+        return {"text_query": query, **kwargs}
+
+
+def normalize_place_from_proto(proto: Any) -> models.Place:
+    """Convert a proto Place to our normalized Place model."""
+    from .proto_adapter import validate_proto_to_model
+
+    model = validate_proto_to_model(proto, GooglePlace)
+    adr_format = getattr(model, "adr_format_address", None)
+    addr = (
+        getattr(model, "formatted_address", None)
+        or getattr(model, "short_formatted_address", None)
+        or strip_html(adr_format or "")
+        or ""
+    )
+    lat, lng = get_lat_lng(model)
+    return models.Place(
+        formatted_address=addr,
+        lat=lat,
+        lng=lng,
+        place_type=infer_place_type(model),
+        google_place=model,
+    )
+
+
+def normalize_search_results(proto_response: Any) -> list[models.Place]:
+    """Convert search_text response to list of normalized Place models."""
+    return [normalize_place_from_proto(proto) for proto in proto_response.places]
+
+
+def build_get_place_request(
+    place_id: Optional[str], request: Optional[models.GetPlaceRequest]
+) -> dict[str, Any]:
+    """Build request parameters for get_place API call."""
+    if place_id is None and request is None:
+        raise ValueError("Either 'place_id' or 'request' must be provided")
+
+    if request:
+        return request.model_dump(exclude_none=True)
+    else:
+        return {"name": f"places/{place_id}"}
+
+
+def derive_effective_query(query: Optional[str], places: list[models.Place]) -> str:
+    """Derive an effective query string from query and/or places."""
+    effective_query = (query or "").strip()
+
+    if not effective_query:
+        if len(places) == 1:
+            derived = name_from_place(places[0])
+            if not derived:
+                raise ValueError("Could not derive a query from the provided place.")
+            effective_query = derived
+        else:
+            raise ValueError(
+                "Multiple places provided but no 'query' to disambiguate them."
+            )
+
+    return effective_query
+
+
+def validate_resolve_airport_inputs(
+    place_id: Optional[str],
+    places: Optional[list[models.Place]],
+    max_distance_km: Optional[float],
+) -> None:
+    """Validate inputs for resolve_airport method."""
+    if place_id is not None and places is not None:
+        raise ValueError("Provide only one of place_id or places, not both.")
+    if max_distance_km is not None and max_distance_km <= 0:
+        raise ValueError("max_distance_km, if provided, must be > 0.")
+
+
+def validate_autocomplete_inputs(
+    input: Optional[str],
+    request: Optional[models.AutocompletePlacesRequest],
+) -> models.AutocompletePlacesRequest:
+    """Validate inputs for autocomplete method."""
+    if request is None:
+        if input is None:
+            raise ValueError("Either input or request must be provided.")
+        else:
+            request = models.AutocompletePlacesRequest(input=input)
+    return request

bookalimo/integrations/google_places/proto_adapter.py

@@ -0,0 +1,224 @@
+from __future__ import annotations
+
+import inspect
+from functools import lru_cache
+from typing import (
+    Any,
+    Dict,
+    List,
+    Optional,
+    Tuple,
+    Type,
+    TypeVar,
+    cast,
+    get_args,
+    get_origin,
+)
+
+from google.protobuf import json_format as jf
+
+# Protobuf imports
+from google.protobuf.message import Message as GPBMessage
+from pydantic import BaseModel, TypeAdapter
+from pydantic_core import ValidationError
+
+# Logging
+from ...logging import get_logger
+
+TModel = TypeVar("TModel", bound=BaseModel)
+
+log = get_logger("proto_adapter")
+
+# ---------------- Proto extraction (proto-plus or vanilla GPB) ----------------
+
+
+def _extract_gpb_message(msg: Any) -> GPBMessage:
+    if isinstance(msg, GPBMessage):
+        return msg
+    for attr in ("_pb", "pb"):
+        if hasattr(msg, attr):
+            cand = getattr(msg, attr)
+            if isinstance(cand, GPBMessage):
+                return cand
+    for meth in ("to_protobuf", "to_pb"):
+        if hasattr(msg, meth):
+            cand = getattr(msg, meth)()
+            if isinstance(cand, GPBMessage):
+                return cand
+    raise TypeError(
+        "Unsupported protobuf message type. Provide a google.protobuf Message "
+        "or a proto-plus message exposing ._pb/.pb or .to_protobuf()."
+    )
+
+
+# ---------------- Version-proof MessageToDict wrapper ----------------
+
+
+@lru_cache(maxsize=1)
+def _mtodict_signature() -> inspect.Signature:
+    return inspect.signature(jf.MessageToDict)
+
+
+def _message_to_dict(
+    msg: Any,
+    *,
+    use_integers_for_enums: bool = True,
+    including_default_value_fields: bool = False,
+    preserving_proto_field_name: bool = True,
+) -> dict[str, Any]:
+    """
+    Wraps google.protobuf.json_format.MessageToDict with runtime arg mapping
+    so it works across protobuf versions.
+    """
+    gpb = _extract_gpb_message(msg)
+    sig = _mtodict_signature()
+    params = sig.parameters
+
+    kwargs: dict[str, Any] = {
+        "preserving_proto_field_name": preserving_proto_field_name,
+        "use_integers_for_enums": use_integers_for_enums,
+    }
+
+    # protobuf>=5 uses "always_print_fields_with_no_presence"
+    if "including_default_value_fields" in params:
+        kwargs["including_default_value_fields"] = including_default_value_fields
+    elif "always_print_fields_with_no_presence" in params:
+        # Map our public arg to the new name
+        kwargs["always_print_fields_with_no_presence"] = including_default_value_fields
+    # else: neither supported (very old?) -> omit, default behavior
+
+    try:
+        return jf.MessageToDict(gpb, **kwargs)
+    except Exception as e:
+        log.error(f"MessageToDict conversion failed: {e}")
+        raise
+
+
+# ---------------- Optional base64 -> bytes coercion guided by model schema ----------------
+
+
+def _unwrap_optional(tp: Any) -> Any:
+    if get_origin(tp) is Optional:
+        return get_args(tp)[0]
+    return tp
+
+
+def _coerce_by_annotation(data: Any, annotation: Any) -> Any:
+    from base64 import urlsafe_b64decode
+
+    from pydantic import BaseModel as PydBaseModel
+
+    if annotation is None:
+        return data
+
+    if get_origin(annotation) is Optional:
+        annotation = _unwrap_optional(annotation)
+
+    if annotation is bytes and isinstance(data, str):
+        # tolerate missing padding
+        try:
+            return urlsafe_b64decode(data + "===")
+        except Exception:
+            return data
+
+    if get_origin(annotation) in (list, tuple, List, Tuple):
+        (item_type,) = get_args(annotation) or (Any,)
+        if isinstance(data, list):
+            return [_coerce_by_annotation(x, item_type) for x in data]
+        return data
+
+    if get_origin(annotation) in (dict, Dict):
+        args = get_args(annotation)
+        if len(args) == 2 and isinstance(data, dict):
+            _, v_type = args
+            return {k: _coerce_by_annotation(v, v_type) for k, v in data.items()}
+        return data
+
+    if (
+        isinstance(annotation, type)
+        and issubclass(annotation, PydBaseModel)
+        and isinstance(data, dict)
+    ):
+        out = dict(data)
+        for fname, f in annotation.model_fields.items():
+            keys = [fname]
+            if f.alias and f.alias != fname:
+                keys.insert(0, f.alias)
+            present = next((k for k in keys if k in out), None)
+            if present is not None:
+                out[present] = _coerce_by_annotation(out[present], f.annotation)
+        return out
+
+    return data
+
+
+# ---------------- TypeAdapter cache (generic-erased to appease Pyright) ----------------
+
+
+@lru_cache(maxsize=256)
+def _adapter_for_cached(model_cls: type) -> TypeAdapter[BaseModel]:
+    # erase generic in the cache to avoid TypeVar identity issues in type checkers
+    return TypeAdapter(model_cls)
+
+
+# ---------------- Public API ----------------
+
+
+def validate_proto_to_model(
+    msg: Any,
+    model_type: Type[TModel],
+    *,
+    decode_bytes_by_schema: bool = True,
+    use_integers_for_enums: bool = True,
+    including_default_value_fields: bool = False,
+    preserving_proto_field_name: bool = True,
+) -> TModel:
+    """
+    Validate a protobuf message (proto-plus or GPB) into a Pydantic v2 model instance.
+
+    - Works across protobuf versions (handles arg rename to always_print_fields_with_no_presence).
+    - Fully runtime: you pass the concrete Pydantic model class.
+    """
+    # Convert protobuf to dictionary
+    try:
+        raw = _message_to_dict(
+            msg,
+            use_integers_for_enums=use_integers_for_enums,
+            including_default_value_fields=including_default_value_fields,
+            preserving_proto_field_name=preserving_proto_field_name,
+        )
+    except Exception as e:
+        log.error(f"Failed to convert protobuf to dict: {e}")
+        raise
+
+    # Apply type coercion if enabled
+    try:
+        data = _coerce_by_annotation(raw, model_type) if decode_bytes_by_schema else raw
+    except Exception as e:
+        log.error(f"Failed during type coercion: {e}")
+        raise
+
+    # Validate with Pydantic
+    try:
+        adapter = _adapter_for_cached(model_type)
+        result = cast(TModel, adapter.validate_python(data))
+        return result
+
+    except ValidationError as e:
+        log.error(
+            f"Pydantic validation failed for {model_type.__name__} ({e.error_count()} errors)"
+        )
+
+        # Log key validation errors with context
+        for error in e.errors():
+            if "loc" in error and error["loc"]:
+                location = ".".join(str(loc) for loc in error["loc"])
+                log.error(f"Validation error at {location}: {error['msg']}")
+            else:
+                log.error(f"Validation error: {error['msg']}")
+
+        raise
+
+    except Exception as e:
+        log.error(f"Unexpected error during validation: {e}")
+        raise