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

bookalimo/schemas/__init__.py

@@ -1,84 +1,170 @@
 """Pydantic schemas for the Bookalimo SDK."""
 
 from ..transport.auth import Credentials
-from .booking import (
+from .places import (
+    AutocompletePlacesRequest,
+    AutocompletePlacesResponse,
+    BusinessStatus,
+    Circle,
+    EVConnectorType,
+    FieldMaskInput,
+    FormattableText,
+    GeocodingRequest,
+    GetPlaceRequest,
+    GooglePlace,
+    LocationBias,
+    LocationRestriction,
+    Place,
+    PlacePrediction,
+    PlaceType,
+    PriceLevel,
+    QueryPrediction,
+    RankPreference,
+    SearchTextRequest,
+    StringRange,
+    StructuredFormat,
+    Suggestion,
+)
+
+# Import request models (for API calls - serialize to camelCase)
+from .requests import (
+    Account,
     Address,
     Airport,
     BookRequest,
-    BookResponse,
-    CardHolderType,
     City,
     CreditCard,
     DetailsRequest,
-    DetailsResponse,
-    EditableReservationRequest,
-    EditReservationResponse,
+    EditReservationRequest,
     GetReservationRequest,
     ListReservationsRequest,
-    ListReservationsResponse,
     Location,
-    LocationType,
     MeetGreetAdditional,
-    MeetGreetType,
     Passenger,
     Price,
     PriceRequest,
-    PriceResponse,
-    RateType,
     Reservation,
-    ReservationStatus,
     Reward,
-    RewardType,
     Stop,
 )
-from .places import (
-    AutocompletePlacesRequest,
-    AutocompletePlacesResponse,
-    Circle,
-    FormattableText,
-    GeocodingRequest,
-    GetPlaceRequest,
-    LocationBias,
-    LocationRestriction,
-    Place,
-    PlacePrediction,
-    PlaceType,
-    QueryPrediction,
-    StringRange,
-    StructuredFormat,
-    Suggestion,
+
+# Import response versions with explicit naming for clarity
+from .responses import (
+    Account as AccountResponse,
+)
+from .responses import (
+    Address as AddressResponse,
+)
+from .responses import (
+    Airport as AirportResponse,
+)
+
+# Import response models (from API responses - serialize to snake_case)
+from .responses import (
+    BookResponse,
+    CarClassPrice,
+    DetailsResponse,
+    EditReservationResponse,
+    GetReservationResponse,
+    ListReservationsResponse,
+    PriceResponse,
+    ReservationData,
+)
+from .responses import (
+    BreakdownItem as BreakdownItemResponse,
+)
+from .responses import (
+    City as CityResponse,
+)
+from .responses import (
+    CreditCard as CreditCardResponse,
+)
+from .responses import (
+    Location as LocationResponse,
+)
+from .responses import (
+    MeetGreet as MeetGreetResponse,
+)
+from .responses import (
+    MeetGreetAdditional as MeetGreetAdditionalResponse,
+)
+from .responses import (
+    Passenger as PassengerResponse,
+)
+from .responses import (
+    Reservation as ReservationResponse,
+)
+from .responses import (
+    Reward as RewardResponse,
+)
+from .responses import (
+    Stop as StopResponse,
+)
+
+# Import enums and shared types from shared module
+from .shared import (
+    CardHolderType,
+    LocationType,
+    MeetGreetType,
+    RateType,
+    ReservationStatus,
+    RewardType,
 )
 
 __all__ = [
+    # Enums and shared types
     "RateType",
     "LocationType",
     "MeetGreetType",
     "RewardType",
     "ReservationStatus",
     "CardHolderType",
+    # Request models (default exports - serialize to camelCase for API)
     "City",
     "Address",
     "Airport",
     "Location",
     "Stop",
+    "Account",
     "Passenger",
     "Reward",
     "CreditCard",
     "MeetGreetAdditional",
     "Price",
     "Reservation",
-    "EditableReservationRequest",
+    "EditReservationRequest",
     "PriceRequest",
-    "PriceResponse",
     "DetailsRequest",
-    "DetailsResponse",
     "BookRequest",
-    "BookResponse",
     "ListReservationsRequest",
-    "ListReservationsResponse",
     "GetReservationRequest",
+    # Response models (serialize to snake_case for Python DX)
+    "BookResponse",
+    "CarClassPrice",
+    "DetailsResponse",
     "EditReservationResponse",
+    "GetReservationResponse",
+    "ListReservationsResponse",
+    "PriceResponse",
+    # Explicit response model variants (for handling API responses)
+    "AccountResponse",
+    "AddressResponse",
+    "AirportResponse",
+    "BreakdownItemResponse",
+    "CityResponse",
+    "CreditCardResponse",
+    "ReservationData",
+    "LocationResponse",
+    "MeetGreetResponse",
+    "MeetGreetAdditionalResponse",
+    "PassengerResponse",
+    "ReservationResponse",
+    "RewardResponse",
+    "StopResponse",
+    # Places API schemas
     "PlaceType",
+    "RankPreference",
+    "EVConnectorType",
     "StringRange",
     "FormattableText",
     "StructuredFormat",
@@ -93,5 +179,11 @@ __all__ = [
     "GetPlaceRequest",
     "AutocompletePlacesRequest",
     "GeocodingRequest",
+    "SearchTextRequest",
+    "GooglePlace",
+    "PriceLevel",
+    "FieldMaskInput",
+    "BusinessStatus",
+    # Auth
     "Credentials",
 ]

bookalimo/schemas/base.py

@@ -7,32 +7,78 @@ from enum import Enum
 from typing import Any, cast
 
 from pydantic import BaseModel, ConfigDict, model_serializer
-from pydantic.alias_generators import to_camel
+from pydantic.alias_generators import to_camel, to_snake
 from pydantic_core.core_schema import SerializationInfo, SerializerFunctionWrapHandler
 
 
-class ApiModel(BaseModel):
+def _deep_to_snake(obj: Any) -> Any:
+    if isinstance(obj, dict):
+        return {
+            (to_snake(k) if isinstance(k, str) else k): _deep_to_snake(v)
+            for k, v in obj.items()
+        }
+    if isinstance(obj, list):
+        return [_deep_to_snake(v) for v in obj]
+    if isinstance(obj, tuple):
+        return type(obj)(_deep_to_snake(v) for v in obj)
+    return obj
+
+
+class SharedModel(BaseModel):
     """
-    Base model for all Book-A-Limo API models.
+    Base model for shared data structures used in both API requests and responses.
 
-    Provides automatic field name conversion between Python snake_case
-    and API camelCase, plus proper enum handling.
+    Provides field name conversion but no serialization opinions - subclasses decide
+    whether to serialize to camelCase (for requests) or snake_case (for responses).
     """
 
     model_config = ConfigDict(
         # Auto-generate camelCase aliases from snake_case field names
         alias_generator=to_camel,
-        # Accept both alias (camel) and name (snake) on input (v2.11+)
+        # Accept both alias (camel) and name (snake) on input
         validate_by_alias=True,
-        validate_by_name=True,  # replaces populate_by_name
-        # Default to using aliases when dumping (wire format)
-        serialize_by_alias=True,
+        validate_by_name=True,
+        # Don't set serialize_by_alias - let subclasses decide
         # Enums dumping handled in model_serializer
         use_enum_values=False,
         # Ignore unknown keys from the API
         extra="ignore",
     )
 
+
+class RequestModel(SharedModel):
+    """
+    Base model for API request models.
+
+    Serializes to camelCase by default (what the Book-A-Limo API expects).
+    """
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        validate_by_alias=True,
+        validate_by_name=True,
+        serialize_by_alias=True,  # Serialize to camelCase for API requests
+        use_enum_values=False,
+        extra="ignore",
+    )
+
+
+class ResponseModel(SharedModel):
+    """
+    Base model for API response models.
+
+    Serializes to snake_case by default (better DX for Python developers).
+    """
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        validate_by_alias=True,
+        validate_by_name=True,
+        serialize_by_alias=False,  # Serialize to snake_case for Python developers
+        use_enum_values=False,
+        extra="ignore",
+    )
+
     @model_serializer(mode="wrap")
     def _serialize(
         self, handler: SerializerFunctionWrapHandler, info: SerializationInfo
@@ -41,16 +87,30 @@ class ApiModel(BaseModel):
         data = handler(self)
 
         # Decide how to emit enums based on context (default to 'value')
-        enum_out = (info.context or {}).get("enum_out", "value")
+        ctx = info.context or {}
+        enum_out = ctx.get("enum_out", "value")
 
-        def convert(obj: Any) -> Any:
+        def convert_values(obj: Any) -> Any:
             if isinstance(obj, Enum):
                 return obj.name if enum_out == "name" else obj.value
             if isinstance(obj, dict):
-                return {k: convert(v) for k, v in obj.items()}
+                return {k: convert_values(v) for k, v in obj.items()}
             if isinstance(obj, (list, tuple)):
                 t = type(obj)
-                return t(convert(v) for v in obj)
+                return t(convert_values(v) for v in obj)
             return obj
 
-        return cast(dict[str, Any], convert(data))
+        out = cast(dict[str, Any], convert_values(data))
+
+        # Key case control: default "camel" (uses aliases); allow "snake" via context.
+        case = ctx.get("case")
+        # Support boolean alias for convenience: snake_case=True -> case="snake"
+        if ctx.get("snake_case") is True:
+            case = "snake"
+        elif ctx.get("snake_case") is False:
+            case = "camel"
+
+        if case == "snake":
+            out = cast(dict[str, Any], _deep_to_snake(out))
+
+        return out

bookalimo/schemas/places/__init__.py

@@ -1,9 +1,13 @@
 """Google Places API schemas."""
 
+from .common import AddressDescriptor
+from .field_mask import FieldMaskInput, FieldPath, compile_field_mask
 from .google import (
     AutocompletePlacesRequest,
     AutocompletePlacesResponse,
     Circle,
+    EVConnectorType,
+    EVOptions,
     FormattableText,
     GeocodingRequest,
     GetPlaceRequest,
@@ -13,20 +17,31 @@ from .google import (
     PlacePrediction,
     PlaceType,
     QueryPrediction,
+    RankPreference,
+    ResolvedAirport,
+    RoutingParameters,
+    SearchTextLocationRestriction,
+    SearchTextRequest,
+    SearchTextResponse,
     StringRange,
     StructuredFormat,
     Suggestion,
 )
+from .place import AddressComponent, BusinessStatus, GooglePlace, PriceLevel
 
 __all__ = [
     "PlaceType",
+    "RankPreference",
+    "EVConnectorType",
     "StringRange",
     "FormattableText",
     "StructuredFormat",
     "Circle",
     "LocationBias",
     "LocationRestriction",
+    "SearchTextLocationRestriction",
     "Place",
+    "GooglePlace",
     "AutocompletePlacesResponse",
     "PlacePrediction",
     "QueryPrediction",
@@ -34,4 +49,16 @@ __all__ = [
     "GetPlaceRequest",
     "AutocompletePlacesRequest",
     "GeocodingRequest",
+    "SearchTextRequest",
+    "ResolvedAirport",
+    "AddressDescriptor",
+    "AddressComponent",
+    "FieldMaskInput",
+    "FieldPath",
+    "compile_field_mask",
+    "EVOptions",
+    "RoutingParameters",
+    "SearchTextResponse",
+    "PriceLevel",
+    "BusinessStatus",
 ]

bookalimo/schemas/places/common.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import re
+from enum import IntEnum
 from typing import Optional
 
 from pydantic import (
@@ -40,7 +41,24 @@ BASE64URL_36 = re.compile(
 )  # up to 36 chars, URL-safe base64-ish
 
 
-# ---------- “External” Google message wrappers ----------
+# ---------- Fundamental types ----------
+class LocalizedText(BaseModel):
+    """Localized text with language code."""
+
+    model_config = ConfigDict(extra="allow")
+
+    text: str
+    language_code: Optional[str] = None
+
+    @field_validator("language_code")
+    @classmethod
+    def _language_code(cls, v: str) -> str:
+        if not BCP47.match(v):
+            raise ValueError("language_code must be a valid BCP-47 language tag")
+        return v
+
+
+# ---------- "External" Google message wrappers ----------
 class ExternalModel(BaseModel):
     """Permissive wrapper for Google messages we don't model in detail."""
 
@@ -77,7 +95,142 @@ class FuelOptions(ExternalModel): ...
 class EVChargeOptions(ExternalModel): ...
 
 
-class AddressDescriptor(ExternalModel): ...
+class AddressDescriptor(BaseModel):
+    """A relational description of a location with nearby landmarks and containing areas."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    class Landmark(BaseModel):
+        """Basic landmark information and relationship with target location."""
+
+        model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+        class SpatialRelationship(IntEnum):
+            """Spatial relationship between target location and landmark."""
+
+            NEAR = 0
+            WITHIN = 1
+            BESIDE = 2
+            ACROSS_THE_ROAD = 3
+            DOWN_THE_ROAD = 4
+            AROUND_THE_CORNER = 5
+            BEHIND = 6
+
+        name: str = Field(..., description="Landmark's resource name")
+        place_id: str = Field(..., description="Landmark's place ID")
+        display_name: LocalizedText = Field(..., description="Landmark's display name")
+        types: list[str] = Field(
+            default_factory=list, description="Type tags for landmark"
+        )
+        spatial_relationship: SpatialRelationship = Field(
+            default=SpatialRelationship.NEAR,
+            description="Spatial relationship to target",
+        )
+        straight_line_distance_meters: float = Field(
+            ..., ge=0.0, description="Straight line distance in meters"
+        )
+        travel_distance_meters: Optional[float] = Field(
+            default=None,
+            ge=0.0,
+            description="Travel distance in meters along road network",
+        )
+
+        @field_validator("name")
+        @classmethod
+        def _name(cls, v: str) -> str:
+            if not PLACE_RESOURCE.fullmatch(v):
+                raise ValueError("name must be in the form 'places/{place_id}'")
+            return v
+
+        @field_validator("place_id")
+        @classmethod
+        def _place_id(cls, v: str) -> str:
+            if not PLACE_ID.fullmatch(v):
+                raise ValueError("place_id must be a valid Place ID")
+            return v
+
+        @field_validator("types")
+        @classmethod
+        def _types(cls, v: list[str]) -> list[str]:
+            out, seen = [], set()
+            for raw in v:
+                t = raw.strip()
+                if not t:
+                    raise ValueError("types cannot contain empty strings")
+                if not PLACE_TYPE.fullmatch(t):
+                    raise ValueError(f"invalid place type '{t}'")
+                if t not in seen:
+                    out.append(t)
+                    seen.add(t)
+            return out
+
+        @model_validator(mode="after")
+        def _name_id_consistency(self) -> Self:
+            if self.name.split("/", 1)[1] != self.place_id:
+                raise ValueError("place_id must match the trailing component of name")
+            return self
+
+    class Area(BaseModel):
+        """Area information and relationship with target location."""
+
+        model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+        class Containment(IntEnum):
+            """Spatial relationship between target location and area."""
+
+            CONTAINMENT_UNSPECIFIED = 0
+            WITHIN = 1
+            OUTSKIRTS = 2
+            NEAR = 3
+
+        name: str = Field(..., description="Area's resource name")
+        place_id: str = Field(..., description="Area's place ID")
+        display_name: LocalizedText = Field(..., description="Area's display name")
+        containment: Containment = Field(
+            default=Containment.CONTAINMENT_UNSPECIFIED,
+            description="Spatial relationship to target",
+        )
+
+        @field_validator("name")
+        @classmethod
+        def _name(cls, v: str) -> str:
+            if not PLACE_RESOURCE.fullmatch(v):
+                raise ValueError("name must be in the form 'places/{place_id}'")
+            return v
+
+        @field_validator("place_id")
+        @classmethod
+        def _place_id(cls, v: str) -> str:
+            if not PLACE_ID.fullmatch(v):
+                raise ValueError("place_id must be a valid Place ID")
+            return v
+
+        @model_validator(mode="after")
+        def _name_id_consistency(self) -> Self:
+            if self.name.split("/", 1)[1] != self.place_id:
+                raise ValueError("place_id must match the trailing component of name")
+            return self
+
+    landmarks: list[Landmark] = Field(
+        default_factory=list, description="Ranked list of nearby landmarks"
+    )
+    areas: list[Area] = Field(
+        default_factory=list, description="Ranked list of containing or adjacent areas"
+    )
+
+    @field_validator("landmarks")
+    @classmethod
+    def _max_landmarks(cls, v: list[Landmark]) -> list[Landmark]:
+        if len(v) > 10:  # Reasonable limit for API responses
+            raise ValueError("landmarks can contain at most 10 items")
+        return v
+
+    @field_validator("areas")
+    @classmethod
+    def _max_areas(cls, v: list[Area]) -> list[Area]:
+        if len(v) > 10:  # Reasonable limit for API responses
+            raise ValueError("areas can contain at most 10 items")
+        return v
 
 
 class PriceRange(ExternalModel): ...