bookalimo 1.0.0__py3-none-any.whl → 1.0.1__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."""
@@ -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"
     )
@@ -594,3 +703,181 @@ class GeocodingRequest(BaseModel):
             params = params.add("region", self.region)
 
         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")

bookalimo/schemas/places/place.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from typing import List, Optional
+from enum import IntEnum
+from typing import Optional
 
 from pydantic import (
     AnyUrl,
@@ -24,6 +25,7 @@ from .common import (
     EVChargeOptions,
     FuelOptions,
     LatLng,
+    LocalizedText,
     OpeningHours,
     ParkingOptions,
     PaymentOptions,
@@ -38,7 +40,7 @@ from .common import (
 )
 
 
-class PriceLevel(int):
+class PriceLevel(IntEnum):
     PRICE_LEVEL_UNSPECIFIED = 0
     PRICE_LEVEL_FREE = 1
     PRICE_LEVEL_INEXPENSIVE = 2
@@ -47,7 +49,7 @@ class PriceLevel(int):
     PRICE_LEVEL_VERY_EXPENSIVE = 5
 
 
-class BusinessStatus(int):
+class BusinessStatus(IntEnum):
     BUSINESS_STATUS_UNSPECIFIED = 0
     OPERATIONAL = 1
     CLOSED_TEMPORARILY = 2
@@ -59,12 +61,14 @@ class AddressComponent(BaseModel):
 
     long_text: str
     short_text: Optional[str] = None
-    types: List[str] = Field(default_factory=list)
+    types: list[str] = Field(
+        default_factory=list
+    )  # limited to https://developers.google.com/maps/documentation/places/web-service/place-types
     language_code: Optional[str] = None
 
     @field_validator("types")
     @classmethod
-    def _types(cls, v: List[str]) -> List[str]:
+    def _types(cls, v: list[str]) -> list[str]:
         out, seen = [], set()
         for raw in v:
             t = raw.strip()
@@ -114,13 +118,6 @@ class NeighborhoodSummary(BaseModel):
     disclosure_text: Optional[LocalizedText] = None
 
 
-class LocalizedText(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-    text: str
-    language_code: str
-
-
 class ContainingPlace(BaseModel):
     model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
 
@@ -148,7 +145,7 @@ class ContainingPlace(BaseModel):
         return self
 
 
-class Place(BaseModel):
+class GooglePlace(BaseModel):
     model_config = ConfigDict(extra="allow", str_strip_whitespace=True)
 
     # Identity
@@ -157,7 +154,7 @@ class Place(BaseModel):
 
     # Labels & typing
     display_name: Optional[LocalizedText] = None
-    types: List[str] = Field(default_factory=list)
+    types: list[str] = Field(default_factory=list)
     primary_type: Optional[str] = None
     primary_type_display_name: Optional[LocalizedText] = None
 
@@ -165,9 +162,10 @@ class Place(BaseModel):
     national_phone_number: Optional[str] = None
     international_phone_number: Optional[str] = None
     formatted_address: Optional[str] = None
+    address_descriptor: Optional[AddressDescriptor] = None
     short_formatted_address: Optional[str] = None
     postal_address: Optional[PostalAddress] = None
-    address_components: List[AddressComponent] = Field(default_factory=list)
+    address_components: list[AddressComponent] = Field(default_factory=list)
     plus_code: Optional[PlusCode] = None
 
     # Location & map
@@ -178,22 +176,22 @@ class Place(BaseModel):
     rating: Optional[float] = None
     google_maps_uri: Optional[AnyUrl] = None
     website_uri: Optional[AnyUrl] = None
-    reviews: List[Review] = Field(default_factory=list)
-    photos: List[Photo] = Field(default_factory=list)
+    reviews: list[Review] = Field(default_factory=list)
+    photos: list[Photo] = Field(default_factory=list)
 
     # Hours
     regular_opening_hours: Optional[OpeningHours] = None
     current_opening_hours: Optional[OpeningHours] = None
-    current_secondary_opening_hours: List[OpeningHours] = Field(default_factory=list)
-    regular_secondary_opening_hours: List[OpeningHours] = Field(default_factory=list)
+    current_secondary_opening_hours: list[OpeningHours] = Field(default_factory=list)
+    regular_secondary_opening_hours: list[OpeningHours] = Field(default_factory=list)
     utc_offset_minutes: Optional[int] = None
     time_zone: Optional[TimeZone] = None
 
     # Misc attributes
     adr_format_address: Optional[str] = None
-    business_status: Optional[int] = None
-    price_level: Optional[int] = None
-    attributions: List[Attribution] = Field(default_factory=list)
+    business_status: Optional[BusinessStatus] = None
+    price_level: Optional[PriceLevel] = None
+    attributions: list[Attribution] = Field(default_factory=list)
     user_rating_count: Optional[int] = None
     icon_mask_base_uri: Optional[AnyUrl] = None
     icon_background_color: Optional[str] = None
@@ -227,7 +225,7 @@ class Place(BaseModel):
     # Options & related places
     payment_options: Optional[PaymentOptions] = None
     parking_options: Optional[ParkingOptions] = None
-    sub_destinations: List[SubDestination] = Field(default_factory=list)
+    sub_destinations: list[SubDestination] = Field(default_factory=list)
     accessibility_options: Optional[AccessibilityOptions] = None
 
     # Fuel/EV & AI summaries
@@ -239,9 +237,8 @@ class Place(BaseModel):
     neighborhood_summary: Optional[NeighborhoodSummary] = None
 
     # Context
-    containing_places: List[ContainingPlace] = Field(default_factory=list)
+    containing_places: list[ContainingPlace] = Field(default_factory=list)
     pure_service_area_business: Optional[bool] = None
-    address_descriptor: Optional[AddressDescriptor] = None
     price_range: Optional[PriceRange] = None
 
     # ---------- Validators ----------
@@ -273,7 +270,7 @@ class Place(BaseModel):
 
     @field_validator("types")
     @classmethod
-    def _types(cls, v: List[str]) -> List[str]:
+    def _types(cls, v: list[str]) -> list[str]:
         out, seen = [], set()
         for raw in v:
             t = raw.strip()
@@ -324,14 +321,14 @@ class Place(BaseModel):
 
     @field_validator("reviews")
     @classmethod
-    def _max_reviews(cls, v: List[Review]) -> List[Review]:
+    def _max_reviews(cls, v: list[Review]) -> list[Review]:
         if len(v) > 5:
             raise ValueError("reviews can contain at most 5 items")
         return v
 
     @field_validator("photos")
     @classmethod
-    def _max_photos(cls, v: List[Photo]) -> List[Photo]:
+    def _max_photos(cls, v: list[Photo]) -> list[Photo]:
         if len(v) > 10:
             raise ValueError("photos can contain at most 10 items")
         return v