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

bookalimo/schemas/__init__.py

@@ -1,49 +1,23 @@
 """Pydantic schemas for the Bookalimo SDK."""
 
 from ..transport.auth import Credentials
-from .booking import (
-    Address,
-    Airport,
-    BookRequest,
-    BookResponse,
-    CardHolderType,
-    City,
-    CreditCard,
-    DetailsRequest,
-    DetailsResponse,
-    EditableReservationRequest,
-    EditReservationResponse,
-    GetReservationRequest,
-    ListReservationsRequest,
-    ListReservationsResponse,
-    Location,
-    LocationType,
-    MeetGreetAdditional,
-    MeetGreetType,
-    Passenger,
-    Price,
-    PriceRequest,
-    PriceResponse,
-    RateType,
-    Reservation,
-    ReservationStatus,
-    Reward,
-    RewardType,
-    Stop,
-)
 from .places import (
     AutocompletePlacesRequest,
     AutocompletePlacesResponse,
+    BusinessStatus,
     Circle,
     EVConnectorType,
+    FieldMaskInput,
     FormattableText,
     GeocodingRequest,
     GetPlaceRequest,
+    GooglePlace,
     LocationBias,
     LocationRestriction,
     Place,
     PlacePrediction,
     PlaceType,
+    PriceLevel,
     QueryPrediction,
     RankPreference,
     SearchTextRequest,
@@ -52,35 +26,142 @@ from .places import (
     Suggestion,
 )
 
+# Import request models (for API calls - serialize to camelCase)
+from .requests import (
+    Account,
+    Address,
+    Airport,
+    BookRequest,
+    City,
+    CreditCard,
+    DetailsRequest,
+    EditReservationRequest,
+    GetReservationRequest,
+    ListReservationsRequest,
+    Location,
+    MeetGreetAdditional,
+    Passenger,
+    Price,
+    PriceRequest,
+    Reservation,
+    Reward,
+    Stop,
+)
+
+# 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",
@@ -99,5 +180,10 @@ __all__ = [
     "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

@@ -27,7 +27,7 @@ from .google import (
     StructuredFormat,
     Suggestion,
 )
-from .place import AddressComponent, GooglePlace
+from .place import AddressComponent, BusinessStatus, GooglePlace, PriceLevel
 
 __all__ = [
     "PlaceType",
@@ -59,4 +59,6 @@ __all__ = [
     "EVOptions",
     "RoutingParameters",
     "SearchTextResponse",
+    "PriceLevel",
+    "BusinessStatus",
 ]

bookalimo/schemas/places/common.py

@@ -48,7 +48,7 @@ class LocalizedText(BaseModel):
     model_config = ConfigDict(extra="allow")
 
     text: str
-    language_code: str
+    language_code: Optional[str] = None
 
     @field_validator("language_code")
     @classmethod

bookalimo/schemas/places/field_mask.py

@@ -210,12 +210,3 @@ class _Root:
 
 
 F = _Root()  # Usage: F.display_name, F.reviews.text, F.photos.author_attributions
-
-
-if __name__ == "__main__":
-    print(
-        compile_field_mask(
-            "photos.author_attributions,photos.author_attributions.textt",
-            prefix="places",
-        )
-    )

bookalimo/schemas/places/google.py

@@ -126,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 ----------
@@ -651,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(
+                    "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(
-                    "You must specify either 'address', 'place_id', or 'components'."
+                    "Cannot mix reverse geocoding (latlng) with forward geocoding (address/components) or place_id lookup."
                 )
         return data
 
@@ -690,18 +826,37 @@ 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