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

bookalimo/schemas/places/google.py

@@ -1,4 +1,15 @@
 import re
+import sys
+
+if sys.version_info >= (3, 11):
+    from enum import StrEnum
+else:
+    from enum import Enum
+
+    class StrEnum(str, Enum):
+        pass
+
+
 from typing import Any, Optional, cast
 
 import pycountry
@@ -24,7 +35,7 @@ from .common import (
     LatLng,
     Viewport,
 )
-from .place import Place as GooglePlace
+from .place import GooglePlace, PriceLevel
 
 # ---------- Constants & Enums ----------
 
@@ -33,7 +44,7 @@ COUNTRY_CODES = {
 }
 
 
-class PlaceType:
+class PlaceType(StrEnum):
     """Place type constants."""
 
     ADDRESS = "address"
@@ -41,6 +52,31 @@ class PlaceType:
     POI = "poi"  # Point of Interest
 
 
+class RankPreference(StrEnum):
+    """Ranking preference constants for SearchTextRequest."""
+
+    RANK_PREFERENCE_UNSPECIFIED = "RANK_PREFERENCE_UNSPECIFIED"
+    DISTANCE = "DISTANCE"
+    RELEVANCE = "RELEVANCE"
+
+
+class EVConnectorType(StrEnum):
+    """EV connector type constants."""
+
+    EV_CONNECTOR_TYPE_UNSPECIFIED = "EV_CONNECTOR_TYPE_UNSPECIFIED"
+    EV_CONNECTOR_TYPE_OTHER = "EV_CONNECTOR_TYPE_OTHER"
+    EV_CONNECTOR_TYPE_J1772 = "EV_CONNECTOR_TYPE_J1772"
+    EV_CONNECTOR_TYPE_TYPE_2 = "EV_CONNECTOR_TYPE_TYPE_2"
+    EV_CONNECTOR_TYPE_CHADEMO = "EV_CONNECTOR_TYPE_CHADEMO"
+    EV_CONNECTOR_TYPE_CCS_COMBO_1 = "EV_CONNECTOR_TYPE_CCS_COMBO_1"
+    EV_CONNECTOR_TYPE_CCS_COMBO_2 = "EV_CONNECTOR_TYPE_CCS_COMBO_2"
+    EV_CONNECTOR_TYPE_TESLA = "EV_CONNECTOR_TYPE_TESLA"
+    EV_CONNECTOR_TYPE_UNSPECIFIED_GB_T = "EV_CONNECTOR_TYPE_UNSPECIFIED_GB_T"
+    EV_CONNECTOR_TYPE_UNSPECIFIED_WALL_OUTLET = (
+        "EV_CONNECTOR_TYPE_UNSPECIFIED_WALL_OUTLET"
+    )
+
+
 # ---------- Text Primitives ----------
 class StringRange(BaseModel):
     """Identifies a substring within a given text."""
@@ -90,8 +126,8 @@ class StructuredFormat(BaseModel):
 
     model_config = ConfigDict(extra="forbid")
 
-    main_text: FormattableText
-    secondary_text: FormattableText
+    main_text: Optional[FormattableText] = None
+    secondary_text: Optional[FormattableText] = None
 
 
 # ---------- Geometry Primitives ----------
@@ -148,6 +184,82 @@ class LocationRestriction(BaseModel):
         return self
 
 
+# ---------- Search Text Supporting Models ----------
+
+
+class Polyline(BaseModel):
+    """Route polyline representation."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    encoded_polyline: Optional[str] = Field(None, description="Encoded polyline string")
+
+
+class RoutingParameters(BaseModel):
+    """Parameters to configure routing calculations."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    origin: Optional[LatLng] = Field(None, description="Explicit routing origin")
+    travel_mode: Optional[str] = Field(
+        None, description="Travel mode (DRIVE, WALK, BICYCLE, TRANSIT)"
+    )
+    routing_preference: Optional[str] = Field(
+        None, description="Routing preference (TRAFFIC_AWARE, etc.)"
+    )
+
+
+class EVOptions(BaseModel):
+    """Searchable EV options for place search."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    minimum_charging_rate_kw: Optional[float] = Field(
+        None, gt=0, description="Minimum required charging rate in kilowatts"
+    )
+    connector_types: list[EVConnectorType] = Field(
+        default_factory=list, description="Preferred EV connector types"
+    )
+
+    @field_validator("connector_types")
+    @classmethod
+    def _validate_connector_types(
+        cls, v: list[EVConnectorType]
+    ) -> list[EVConnectorType]:
+        # Remove duplicates while preserving order
+        seen = set()
+        cleaned = []
+        for connector_type in v:
+            if connector_type not in seen:
+                cleaned.append(connector_type)
+                seen.add(connector_type)
+        return cleaned
+
+
+class SearchAlongRouteParameters(BaseModel):
+    """Parameters for searching along a route."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    polyline: Polyline = Field(..., description="Route polyline")
+
+
+class SearchTextLocationRestriction(BaseModel):
+    """
+    Location restriction for SearchTextRequest - allows only rectangle.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    rectangle: Optional[Viewport] = None
+
+    @model_validator(mode="after")
+    def _validate_rectangle_required(self) -> Self:
+        if self.rectangle is None:
+            raise ValueError("rectangle is required for LocationRestriction")
+        return self
+
+
 # ---------- Responses ----------
 
 
@@ -157,10 +269,7 @@ class Place(BaseModel):
     formatted_address: str = Field(..., description="Full formatted address")
     lat: float = Field(..., description="Latitude")
     lng: float = Field(..., description="Longitude")
-    place_type: str = Field(..., description="Type: address, airport, or poi")
-    iata_code: Optional[str] = Field(
-        None, description="IATA airport code if applicable"
-    )
+    place_type: PlaceType = Field(..., description="Type: address, airport, or poi")
     google_place: Optional[GooglePlace] = Field(
         None, description="Raw Google Places API response"
     )
@@ -542,37 +651,173 @@ class AutocompletePlacesRequest(BaseModel):
         return self
 
 
+class ExtraComputations(StrEnum):
+    """Extra computations for Geocoding API requests."""
+
+    ADDRESS_DESCRIPTORS = "ADDRESS_DESCRIPTORS"
+    BUILDING_AND_ENTRANCES = "BUILDING_AND_ENTRANCES"
+
+
 class GeocodingRequest(BaseModel):
     """
     Pydantic model for validating and building Geocoding API query parameters.
+    Supports both forward geocoding (address -> coordinates) and reverse geocoding (coordinates -> address).
     This model is not for a JSON request body, but for constructing a URL.
     """
 
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+    # Forward geocoding parameters
     address: Optional[str] = Field(
         default=None,
         description="The street address or plus code that you want to geocode.",
     )
+    components: Optional[str] = Field(
+        default=None,
+        description="Components filter with pipe-separated component:value pairs (e.g., 'country:US|locality:Mountain View').",
+    )
+
+    # Reverse geocoding parameters
+    latlng: Optional[str] = Field(
+        default=None,
+        description="Latitude and longitude coordinates for reverse geocoding (e.g., '40.714224,-73.961452').",
+    )
     place_id: Optional[str] = Field(
         default=None,
         description="The place ID of the place for which you wish to obtain the human-readable address.",
     )
+
+    # Optional parameters for both forward and reverse geocoding
     language: Optional[str] = Field(
-        default=None, description="The language in which to return results."
+        default=None, description="The language in which to return results (BCP-47)."
     )
     region: Optional[str] = Field(
         default=None, description="The region code (ccTLD) to bias results."
     )
+    extra_computations: list[ExtraComputations] = Field(
+        default_factory=list,
+        description="Additional features to include in the response.",
+    )
+
+    # Forward geocoding specific optional parameters
+    bounds: Optional[str] = Field(
+        default=None,
+        description="Bounding box for viewport biasing (format: 'southwest_lat,southwest_lng|northeast_lat,northeast_lng').",
+    )
+
+    # Reverse geocoding specific optional parameters
+    result_type: Optional[str] = Field(
+        default=None,
+        description="Filter for address types, pipe-separated (e.g., 'street_address|route').",
+    )
+    location_type: Optional[str] = Field(
+        default=None,
+        description="Filter for location types, pipe-separated (e.g., 'ROOFTOP|RANGE_INTERPOLATED').",
+    )
+
+    @field_validator("latlng")
+    @classmethod
+    def _validate_latlng(cls, v: Optional[str]) -> Optional[str]:
+        if v is None:
+            return v
+        try:
+            parts = v.split(",")
+            if len(parts) != 2:
+                raise ValueError("latlng must be in format 'latitude,longitude'")
+            lat, lng = float(parts[0]), float(parts[1])
+            if not (-90 <= lat <= 90):
+                raise ValueError("Latitude must be between -90 and 90")
+            if not (-180 <= lng <= 180):
+                raise ValueError("Longitude must be between -180 and 180")
+        except (ValueError, IndexError) as e:
+            if "could not convert" in str(e):
+                raise ValueError("latlng coordinates must be valid numbers") from None
+            raise
+        return v
+
+    @field_validator("bounds")
+    @classmethod
+    def _validate_bounds(cls, v: Optional[str]) -> Optional[str]:
+        if v is None:
+            return v
+        try:
+            parts = v.split("|")
+            if len(parts) != 2:
+                raise ValueError(
+                    "bounds must be in format 'sw_lat,sw_lng|ne_lat,ne_lng'"
+                )
+            for part in parts:
+                coords = part.split(",")
+                if len(coords) != 2:
+                    raise ValueError("Each bounds coordinate pair must be 'lat,lng'")
+                lat, lng = float(coords[0]), float(coords[1])
+                if not (-90 <= lat <= 90):
+                    raise ValueError("Latitude must be between -90 and 90")
+                if not (-180 <= lng <= 180):
+                    raise ValueError("Longitude must be between -180 and 180")
+        except (ValueError, IndexError) as e:
+            if "could not convert" in str(e):
+                raise ValueError("bounds coordinates must be valid numbers") from None
+            raise
+        return v
+
+    @field_validator("language")
+    @classmethod
+    def _validate_language_code(cls, v: Optional[str]) -> Optional[str]:
+        if v is None:
+            return v
+        if not BCP47.match(v):
+            raise ValueError(
+                "language must be a valid BCP-47 tag (e.g., 'en', 'en-US', 'zh-Hant')."
+            )
+        return v
+
+    @field_validator("region")
+    @classmethod
+    def _validate_region_code(cls, v: Optional[str]) -> Optional[str]:
+        if v is None:
+            return v
+        v2 = v.upper()
+        if not CLDR_REGION_2.fullmatch(v2):
+            raise ValueError(
+                "region must be a two-letter ccTLD region code (e.g., 'US', 'GB')."
+            )
+        return v2
+
+    @field_validator("extra_computations")
+    @classmethod
+    def _validate_extra_computations(
+        cls, v: list[ExtraComputations]
+    ) -> list[ExtraComputations]:
+        # Remove duplicates while preserving order
+        seen = set()
+        cleaned = []
+        for computation in v:
+            if computation not in seen:
+                cleaned.append(computation)
+                seen.add(computation)
+        return cleaned
 
     @model_validator(mode="before")
     @classmethod
     def check_required_params(cls, data: Any) -> Any:
-        """Ensures that either 'address', 'place_id', or 'components' is provided."""
+        """Validates that proper parameters are provided for forward or reverse geocoding."""
         if isinstance(data, dict):
-            if not any(
-                [data.get("address"), data.get("place_id"), data.get("components")]
-            ):
+            has_forward = any([data.get("address"), data.get("components")])
+            has_reverse = data.get("latlng") is not None
+            has_place_id = data.get("place_id") is not None
+
+            if not (has_forward or has_reverse or has_place_id):
                 raise ValueError(
-                    "You must specify either 'address', 'place_id', or 'components'."
+                    "For forward geocoding: specify 'address' and/or 'components'. "
+                    "For reverse geocoding: specify 'latlng'. "
+                    "For place ID lookup: specify 'place_id'."
+                )
+
+            # Can't mix forward and reverse geocoding parameters
+            if has_reverse and (has_forward or has_place_id):
+                raise ValueError(
+                    "Cannot mix reverse geocoding (latlng) with forward geocoding (address/components) or place_id lookup."
                 )
         return data
 
@@ -581,16 +826,213 @@ class GeocodingRequest(BaseModel):
         Serializes the model fields into a dictionary suitable for URL query parameters.
         """
         params = QueryParams()
+
+        # Forward geocoding parameters
         if self.address:
             params = params.add("address", self.address)
-
+        if self.components:
+            params = params.add("components", self.components)
+        if self.bounds:
+            params = params.add("bounds", self.bounds)
+
+        # Reverse geocoding parameters
+        if self.latlng:
+            params = params.add("latlng", self.latlng)
+        if self.result_type:
+            params = params.add("result_type", self.result_type)
+        if self.location_type:
+            params = params.add("location_type", self.location_type)
+
+        # Place ID lookup
         if self.place_id:
             params = params.add("place_id", self.place_id)
 
+        # Common optional parameters
         if self.language:
             params = params.add("language", self.language)
-
         if self.region:
             params = params.add("region", self.region)
 
+        # Extra computations (can appear multiple times)
+        for computation in self.extra_computations:
+            params = params.add("extra_computations", computation.value)
+
         return params
+
+
+class SearchTextRequest(BaseModel):
+    """
+    Pydantic model for SearchTextRequest with rich validations.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid", str_strip_whitespace=True, populate_by_name=True
+    )
+
+    # Required field
+    text_query: str = Field(
+        ..., min_length=1, description="Required. The text query for textual search."
+    )
+
+    # Localization
+    language_code: Optional[str] = Field(
+        default=None,
+        description="Place details will be displayed with the preferred language if available.",
+    )
+    region_code: Optional[str] = Field(
+        default=None,
+        description="The Unicode country/region code (CLDR) of the location.",
+    )
+
+    # Ranking and type filtering
+    rank_preference: Optional[RankPreference] = Field(
+        default=None, description="How results will be ranked in the response."
+    )
+    included_type: Optional[str] = Field(
+        default=None,
+        description="The requested place type. Only support one included type.",
+    )
+    strict_type_filtering: bool = Field(
+        default=False,
+        description="Used to set strict type filtering for included_type.",
+    )
+
+    # Filters
+    open_now: bool = Field(
+        default=False,
+        description="Used to restrict the search to places that are currently open.",
+    )
+    min_rating: Optional[float] = Field(
+        default=None,
+        ge=0,
+        le=5,
+        description="Filter out results whose average user rating is strictly less than this limit.",
+    )
+    max_result_count: Optional[int] = Field(
+        default=None,
+        ge=1,
+        le=20,
+        description="Maximum number of results to return. Must be between 1 and 20.",
+    )
+    price_levels: list[PriceLevel] = Field(
+        default_factory=list,
+        description="Used to restrict the search to places that are marked as certain price levels.",
+    )
+
+    # Location constraints (mutually exclusive)
+    location_bias: Optional[LocationBias] = Field(
+        default=None,
+        description="The region to search. This location serves as a bias.",
+    )
+    location_restriction: Optional[SearchTextLocationRestriction] = Field(
+        default=None,
+        description="The region to search. This location serves as a restriction.",
+    )
+
+    # Advanced options
+    ev_options: Optional[EVOptions] = Field(
+        default=None,
+        description="Set the searchable EV options of a place search request.",
+    )
+    routing_parameters: Optional[RoutingParameters] = Field(
+        default=None, description="Additional parameters for routing to results."
+    )
+    search_along_route_parameters: Optional[SearchAlongRouteParameters] = Field(
+        default=None, description="Additional parameters for searching along a route."
+    )
+    include_pure_service_area_businesses: bool = Field(
+        default=False,
+        description="Include pure service area businesses if the field is set to true.",
+    )
+
+    # Field validators
+    @field_validator("language_code")
+    @classmethod
+    def _validate_language_code(cls, v: Optional[str]) -> Optional[str]:
+        if v is None:
+            return v
+        if not BCP47.match(v):
+            raise ValueError(
+                "language_code must be a valid BCP-47 tag (e.g., 'en', 'en-US', 'zh-Hant')."
+            )
+        return v
+
+    @field_validator("region_code")
+    @classmethod
+    def _validate_region_code(cls, v: Optional[str]) -> Optional[str]:
+        if v is None:
+            return v
+        v2 = v.upper()
+        if not CLDR_REGION_2.fullmatch(v2):
+            raise ValueError(
+                "region_code must be a two-letter CLDR region code (e.g., 'US', 'GB')."
+            )
+        return v2
+
+    @field_validator("included_type")
+    @classmethod
+    def _validate_included_type(cls, v: Optional[str]) -> Optional[str]:
+        if v is None:
+            return v
+        if not PLACE_TYPE.match(v):
+            raise ValueError(
+                f"Invalid place type '{v}'. Use lowercase letters, digits, and underscores."
+            )
+        return v
+
+    @field_validator("min_rating")
+    @classmethod
+    def _validate_min_rating(cls, v: Optional[float]) -> Optional[float]:
+        if v is None:
+            return v
+        # Round up to nearest 0.5 as per Google's specification
+        import math
+
+        return math.ceil(v * 2) / 2
+
+    @field_validator("price_levels")
+    @classmethod
+    def _validate_price_levels(cls, v: list[PriceLevel]) -> list[PriceLevel]:
+        # Remove duplicates while preserving order
+        seen = set()
+        cleaned = []
+        for level in v:
+            if level not in seen:
+                cleaned.append(level)
+                seen.add(level)
+        return cleaned
+
+    # Cross-field validation
+    @model_validator(mode="after")
+    def _validate_cross_fields(self) -> Self:
+        # Mutually exclusive location constraints
+        if self.location_bias is not None and self.location_restriction is not None:
+            raise ValueError(
+                "Cannot set both location_bias and location_restriction. Choose one."
+            )
+        return self
+
+
+class SearchTextResponse(BaseModel):
+    """Response proto for SearchText."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    places: list[GooglePlace] = Field(
+        default_factory=list,
+        description="A list of places that meet the user's text search criteria.",
+    )
+
+
+class ResolvedAirport(BaseModel):
+    """Airport result from the resolve_airport() method."""
+
+    name: str = Field(..., description="Name of the airport")
+    city: str = Field(..., description="City of the airport")
+    iata_code: Optional[str] = Field(
+        None, description="IATA airport code if applicable"
+    )
+    icao_code: Optional[str] = Field(
+        None, description="ICAO airport code if applicable"
+    )
+    confidence: float = Field(..., description="Search result confidence score")