bookalimo 0.1.4__py3-none-any.whl → 1.0.0__py3-none-any.whl

bookalimo/integrations/google_places/common.py

@@ -0,0 +1,245 @@
+"""
+Common utilities and shared functionality for Google Places clients.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Sequence, Union
+
+from ...logging import get_logger
+
+logger = get_logger("places")
+
+
+Fields = Union[
+    str,
+    Sequence[
+        Literal[
+            "*",
+            # Identity
+            "name",
+            # Labels & typing
+            "display_name",
+            "types",
+            "primary_type",
+            "primary_type_display_name",
+            # Phones & addresses
+            "national_phone_number",
+            "international_phone_number",
+            "formatted_address",
+            "short_formatted_address",
+            "postal_address",
+            "address_components",
+            "plus_code",
+            # Location & map
+            "location",
+            "viewport",
+            # Scores, links, media
+            "rating",
+            "google_maps_uri",
+            "website_uri",
+            "reviews",
+            "photos",
+            # Hours
+            "regular_opening_hours",
+            "current_opening_hours",
+            "current_secondary_opening_hours",
+            "regular_secondary_opening_hours",
+            "utc_offset_minutes",
+            "time_zone",
+            # Misc attributes
+            "adr_format_address",
+            "business_status",
+            "price_level",
+            "attributions",
+            "user_rating_count",
+            "icon_mask_base_uri",
+            "icon_background_color",
+            # Food/venue features
+            "takeout",
+            "delivery",
+            "dine_in",
+            "curbside_pickup",
+            "reservable",
+            "serves_breakfast",
+            "serves_lunch",
+            "serves_dinner",
+            "serves_beer",
+            "serves_wine",
+            "serves_brunch",
+            "serves_vegetarian_food",
+            "outdoor_seating",
+            "live_music",
+            "menu_for_children",
+            "serves_cocktails",
+            "serves_dessert",
+            "serves_coffee",
+            "good_for_children",
+            "allows_dogs",
+            "restroom",
+            "good_for_groups",
+            "good_for_watching_sports",
+            # Options & related places
+            "payment_options",
+            "parking_options",
+            "sub_destinations",
+            "accessibility_options",
+            # Fuel/EV & AI summaries
+            "fuel_options",
+            "ev_charge_options",
+            "generative_summary",
+            "review_summary",
+            "ev_charge_amenity_summary",
+            "neighborhood_summary",
+            # Context
+            "containing_places",
+            "pure_service_area_business",
+            "address_descriptor",
+            "price_range",
+            # Missing in your model but present in proto
+            "editorial_summary",
+        ]
+    ],
+]
+
+PlaceListFields = Union[
+    str,
+    Sequence[
+        Literal[
+            "*",
+            # Identity
+            "places.name",
+            # Labels & typing
+            "places.display_name",
+            "places.types",
+            "places.primary_type",
+            "places.primary_type_display_name",
+            # Phones & addresses
+            "places.national_phone_number",
+            "places.international_phone_number",
+            "places.formatted_address",
+            "places.short_formatted_address",
+            "places.postal_address",
+            "places.address_components",
+            "places.plus_code",
+            # Location & map
+            "places.location",
+            "places.viewport",
+            # Scores, links, media
+            "places.rating",
+            "places.google_maps_uri",
+            "places.website_uri",
+            "places.reviews",
+            "places.photos",
+            # Hours
+            "places.regular_opening_hours",
+            "places.current_opening_hours",
+            "places.current_secondary_opening_hours",
+            "places.regular_secondary_opening_hours",
+            "places.utc_offset_minutes",
+            "places.time_zone",
+            # Misc attributes
+            "places.adr_format_address",
+            "places.business_status",
+            "places.price_level",
+            "places.attributions",
+            "places.user_rating_count",
+            "places.icon_mask_base_uri",
+            "places.icon_background_color",
+            # Food/venue features
+            "places.takeout",
+            "places.delivery",
+            "places.dine_in",
+            "places.curbside_pickup",
+            "places.reservable",
+            "places.serves_breakfast",
+            "places.serves_lunch",
+            "places.serves_dinner",
+            "places.serves_beer",
+            "places.serves_wine",
+            "places.serves_brunch",
+            "places.serves_vegetarian_food",
+            "places.outdoor_seating",
+            "places.live_music",
+            "places.menu_for_children",
+            "places.serves_cocktails",
+            "places.serves_dessert",
+            "places.serves_coffee",
+            "places.good_for_children",
+            "places.allows_dogs",
+            "places.restroom",
+            "places.good_for_groups",
+            "places.good_for_watching_sports",
+            # Options & related places
+            "places.payment_options",
+            "places.parking_options",
+            "places.sub_destinations",
+            "places.accessibility_options",
+            # Fuel/EV & AI summaries
+            "places.fuel_options",
+            "places.ev_charge_options",
+            "places.generative_summary",
+            "places.review_summary",
+            "places.ev_charge_amenity_summary",
+            "places.neighborhood_summary",
+            # Context
+            "places.containing_places",
+            "places.pure_service_area_business",
+            "places.address_descriptor",
+            "places.price_range",
+            # Missing in your model but present in proto
+            "places.editorial_summary",
+        ]
+    ],
+]
+
+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: Sequence[str] | str | None) -> 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 ()
+    if isinstance(fields, str):
+        value = fields
+    else:
+        value = ",".join(fields)
+    return (("x-goog-fieldmask", value),)
+
+
+# Default field mask for places queries
+DEFAULT_PLACE_FIELDS: Fields = (
+    "display_name",
+    "formatted_address",
+    "location",
+)
+
+DEFAULT_PLACE_LIST_FIELDS: PlaceListFields = (
+    "places.display_name",
+    "places.formatted_address",
+    "places.location",
+)

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

bookalimo/{_logging.py → logging.py}

@@ -1,6 +1,15 @@
 """
-Logging configuration for bookalimo package.
-Public SDK-style logging with built-in redaction helpers.
+Logging utilities for the Bookalimo SDK.
+
+The SDK uses Python's standard logging module. To enable debug logging,
+configure the 'bookalimo' logger or set the BOOKALIMO_LOG_LEVEL environment variable.
+
+Example:
+    import logging
+    logging.getLogger('bookalimo').setLevel(logging.DEBUG)
+
+    # Or via environment variable
+    export BOOKALIMO_LOG_LEVEL=DEBUG
 """
 
 from __future__ import annotations
@@ -8,13 +17,51 @@ from __future__ import annotations
 import logging
 import os
 import re
-from collections.abc import Iterable, Mapping
+from collections.abc import Awaitable, Iterable, Mapping
+from functools import wraps
 from time import perf_counter
-from typing import Any, Callable
+from typing import Any, Callable, TypeVar
+
+from typing_extensions import ParamSpec
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def _level_from_env() -> int | None:
+    """Get log level from BOOKALIMO_LOG_LEVEL environment variable."""
+    lvl = os.getenv("BOOKALIMO_LOG_LEVEL")
+    if not lvl:
+        return None
+    try:
+        return int(lvl)
+    except ValueError:
+        try:
+            return logging._nameToLevel.get(lvl.upper(), None)
+        except Exception:
+            return None
+
 
 logger = logging.getLogger("bookalimo")
-logger.addHandler(logging.NullHandler())
-logger.setLevel(logging.WARNING)
+
+# Apply environment variable level if set, otherwise use WARNING as default
+env_level = _level_from_env()
+logger.setLevel(env_level if env_level is not None else logging.WARNING)
+
+# If user set BOOKALIMO_LOG_LEVEL, they expect to see logs - add console handler
+if env_level is not None:
+    # Only add console handler if one doesn't already exist
+    if not any(isinstance(h, logging.StreamHandler) for h in logger.handlers):
+        console_handler = logging.StreamHandler()
+        console_handler.setLevel(env_level)
+        formatter = logging.Formatter(
+            "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+        )
+        console_handler.setFormatter(formatter)
+        logger.addHandler(console_handler)
+else:
+    # If no env var is set, use NullHandler (library default behavior)
+    logger.addHandler(logging.NullHandler())
 
 REDACTED = "******"
 
@@ -132,44 +179,6 @@ def get_logger(name: str | None = None) -> logging.Logger:
     return logger
 
 
-def enable_debug_logging(level: int | None = None) -> None:
-    level = level or _level_from_env() or logging.DEBUG
-    logger.setLevel(level)
-
-    has_real_handler = any(
-        not isinstance(h, logging.NullHandler) for h in logger.handlers
-    )
-    if not has_real_handler:
-        handler = logging.StreamHandler()
-        formatter = logging.Formatter(
-            "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
-        )
-        handler.setFormatter(formatter)
-        logger.addHandler(handler)
-
-    logger.info("bookalimo logging enabled at %s", logging.getLevelName(logger.level))
-
-
-def disable_debug_logging() -> None:
-    logger.setLevel(logging.WARNING)
-    for handler in logger.handlers[:]:
-        if not isinstance(handler, logging.NullHandler):
-            logger.removeHandler(handler)
-
-
-def _level_from_env() -> int | None:
-    lvl = os.getenv("BOOKALIMO_LOG_LEVEL")
-    if not lvl:
-        return None
-    try:
-        return int(lvl)
-    except ValueError:
-        try:
-            return logging._nameToLevel.get(lvl.upper(), None)
-        except Exception:
-            return None
-
-
 # ---- decorator for async methods --------------------------------------------
 
 
@@ -178,27 +187,19 @@ def log_call(
     include_params: Iterable[str] | None = None,
     transforms: Mapping[str, Callable[[Any], Any]] | None = None,
     operation: str | None = None,
-) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
-    """
-    Decorator for async SDK methods.
-    - DEBUG: logs start/end with sanitized params + duration
-    - WARNING: logs errors (sanitized). No overhead when DEBUG is off.
-    """
+) -> Callable[[Callable[P, Awaitable[R]]], Callable[P, Awaitable[R]]]:
     include = set(include_params or [])
     transforms = transforms or {}
 
-    def _decorate(fn: Callable[..., Any]) -> Callable[..., Any]:
-        async def _async_wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+    def _decorate(fn: Callable[P, Awaitable[R]]) -> Callable[P, Awaitable[R]]:
+        @wraps(fn)
+        async def _async_wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
             log = get_logger("wrapper")
             op = operation or fn.__name__
 
-            # Fast path: if debug disabled, skip param binding/redaction entirely
             debug_on = log.isEnabledFor(logging.DEBUG)
             if debug_on:
-                # Build a minimal, sanitized args snapshot
                 snapshot: dict[str, Any] = {}
-                # Map positional args to param names without inspect overhead by relying on kwargs only:
-                # we assume call sites are using kwargs in the wrapper (they do).
                 for k in include:
                     val = kwargs.get(k, None)
                     if k in transforms:
@@ -209,7 +210,6 @@ def log_call(
                     else:
                         val = redact_param(k, val)
                     snapshot[k] = val
-
                 start = perf_counter()
                 log.debug(
                     "→ %s(%s)",
@@ -219,21 +219,18 @@ def log_call(
                 )
 
             try:
-                result = await fn(self, *args, **kwargs)
+                result = await fn(*args, **kwargs)
                 if debug_on:
                     dur_ms = (perf_counter() - start) * 1000.0
-                    # Keep result logging ultra-light
-                    result_type = type(result).__name__
                     log.debug(
                         "← %s ok in %.1f ms (%s)",
                         op,
                         dur_ms,
-                        result_type,
+                        type(result).__name__,
                         extra={"operation": op},
                     )
                 return result
             except Exception as e:
-                # WARNING with sanitized error; no param dump on failures
                 log.warning(
                     "%s failed: %s", op, e.__class__.__name__, extra={"operation": op}
                 )