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

bookalimo/__init__.py

@@ -1,31 +1,24 @@
 """
-Book-A-Limo API Wrapper Package.
-Provides a clean, typed interface to the Book-A-Limo API.
-"""
+Bookalimo SDK - Python client for the Book-A-Limo API.
 
-import importlib.metadata
+Provides clean, typed interfaces for booking transportation services.
+"""
 
-from ._logging import disable_debug_logging, enable_debug_logging
-from .wrapper import (
-    BookALimo,
-    create_address_location,
-    create_airport_location,
-    create_credentials,
-    create_credit_card,
-    create_passenger,
-    create_stop,
+from ._version import __version__
+from .client import AsyncBookalimo, Bookalimo
+from .exceptions import (
+    BookalimoError,
+    BookalimoHTTPError,
+    BookalimoTimeout,
+    BookalimoValidationError,
 )
 
 __all__ = [
-    "BookALimo",
-    "create_credentials",
-    "create_address_location",
-    "create_airport_location",
-    "create_stop",
-    "create_passenger",
-    "create_credit_card",
-    "enable_debug_logging",
-    "disable_debug_logging",
+    "Bookalimo",
+    "AsyncBookalimo",
+    "BookalimoError",
+    "BookalimoHTTPError",
+    "BookalimoTimeout",
+    "BookalimoValidationError",
+    "__version__",
 ]
-
-__version__ = importlib.metadata.version(__package__ or __name__)

bookalimo/_version.py

@@ -0,0 +1,9 @@
+"""Version information for the bookalimo package."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("bookalimo")
+except PackageNotFoundError:
+    # Development/editable install fallback
+    __version__ = "0.0.0"

bookalimo/client.py

@@ -0,0 +1,310 @@
+"""Main client classes for the Bookalimo SDK."""
+
+import warnings
+from typing import TYPE_CHECKING, Any, Optional
+
+if TYPE_CHECKING:
+    from .integrations.google_places import AsyncGooglePlaces, GooglePlaces
+
+from .config import DEFAULT_BASE_URL, DEFAULT_TIMEOUTS, DEFAULT_USER_AGENT
+from .exceptions import DuplicateCredentialsWarning, MissingCredentialsWarning
+from .services import (
+    AsyncPricingService,
+    AsyncReservationsService,
+    PricingService,
+    ReservationsService,
+)
+from .transport import AsyncTransport, SyncTransport
+from .transport.auth import Credentials
+
+# Optional integrations
+try:
+    from .integrations.google_places import (
+        AsyncGooglePlaces as _AsyncGooglePlaces,
+    )
+    from .integrations.google_places import (
+        GooglePlaces as _GooglePlaces,
+    )
+
+    _GOOGLE_PLACES_AVAILABLE = True
+except ImportError:
+    _GOOGLE_PLACES_AVAILABLE = False
+    _AsyncGooglePlaces = None  # type: ignore
+    _GooglePlaces = None  # type: ignore
+
+
+class AsyncBookalimo:
+    """
+    Async client for the Book-A-Limo API.
+
+    Provides access to reservations and pricing services through a clean,
+    resource-style interface. Optionally includes Google Places integration
+    for location services.
+
+    Examples:
+        # Basic usage
+        async with AsyncBookalimo(credentials=creds) as client:
+            quote = await client.pricing.quote(
+                rate_type=RateType.P2P,
+                date_time="09/10/2025 03:00 PM",
+                pickup=pickup_location,
+                dropoff=dropoff_location,
+                passengers=2,
+                luggage=2,
+            )
+
+        # With Google Places integration
+        async with AsyncBookalimo(
+            credentials=creds,
+            google_places_api_key="your-google-api-key"
+        ) as client:
+            # Find locations using Google Places
+            places = await client.places.search_text("Empire State Building")
+
+            # Use in booking
+            quote = await client.pricing.quote(
+                rate_type=RateType.P2P,
+                date_time="09/10/2025 03:00 PM",
+                pickup=pickup_location,
+                dropoff=dropoff_location,
+                passengers=2,
+                luggage=2,
+            )
+    """
+
+    def __init__(
+        self,
+        *,
+        credentials: Optional[Credentials] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeouts: Any = DEFAULT_TIMEOUTS,
+        user_agent: str = DEFAULT_USER_AGENT,
+        transport: Optional[AsyncTransport] = None,
+        google_places_api_key: Optional[str] = None,
+    ):
+        """
+        Initialize the async Bookalimo client.
+
+        Args:
+            credentials: Authentication credentials (required for API calls)
+            base_url: API base URL
+            timeouts: Request timeout configuration
+            user_agent: User agent string
+            transport: Custom transport instance (optional)
+            google_places_api_key: Google Places API key for location services (optional)
+        """
+
+        transport_credentials = transport.credentials if transport else None
+
+        both_provided = all([transport_credentials, credentials])
+        both_missing = not any([transport_credentials, credentials])
+
+        if both_provided:
+            warnings.warn(
+                "Credentials provided in both transport and constructor. "
+                "The transport credentials will be used.",
+                DuplicateCredentialsWarning,
+                stacklevel=2,
+            )
+        elif both_missing:
+            warnings.warn(
+                "No credentials provided in transport or constructor; proceeding unauthenticated.",
+                MissingCredentialsWarning,
+                stacklevel=2,
+            )
+
+        # Use whichever exists when we need to build a transport ourselves
+        effective_credentials = (
+            credentials if credentials is not None else transport_credentials
+        )
+        if transport:
+            transport.credentials = effective_credentials
+        self._transport = transport or AsyncTransport(
+            base_url=base_url,
+            timeouts=timeouts,
+            user_agent=user_agent,
+            credentials=effective_credentials,
+        )
+
+        # Initialize service instances
+        self.reservations = AsyncReservationsService(self._transport)
+        self.pricing = AsyncPricingService(self._transport)
+
+        # Initialize Google Places integration if available
+        self._google_places_api_key = google_places_api_key
+        self._google_places_client: Optional[AsyncGooglePlaces] = None
+
+    @property
+    def places(self) -> "AsyncGooglePlaces":
+        """
+        Access Google Places integration for location services.
+
+        Returns:
+            AsyncGooglePlaces client instance
+
+        Raises:
+            ImportError: If Google Places dependencies are not installed
+
+        Note:
+            Auth priority is as follows:
+              - provided api key in constructor
+              - GOOGLE_PLACES_API_KEY environment variable
+              - Google ADC - Except for Geocoding API.
+        """
+        if not _GOOGLE_PLACES_AVAILABLE:
+            raise ImportError(
+                "Google Places integration requires the 'places' extra. "
+                "Install with: pip install bookalimo[places]"
+            )
+
+        if self._google_places_client is None:
+            if _AsyncGooglePlaces is None:
+                raise ImportError("Google Places integration not available")
+            self._google_places_client = _AsyncGooglePlaces(
+                api_key=self._google_places_api_key
+            )
+
+        return self._google_places_client
+
+    async def aclose(self) -> None:
+        """Close the client and clean up resources."""
+        await self._transport.aclose()
+        if self._google_places_client is not None:
+            await self._google_places_client.aclose()
+
+    async def __aenter__(self) -> "AsyncBookalimo":
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Async context manager exit."""
+        await self.aclose()
+
+
+class Bookalimo:
+    """
+    Sync client for the Book-A-Limo API.
+
+    Provides access to reservations and pricing services through a clean,
+    resource-style interface. Optionally includes Google Places integration
+    for location services.
+
+    Examples:
+        # Basic usage
+        with Bookalimo(credentials=creds) as client:
+            quote = client.pricing.quote(
+                rate_type=RateType.P2P,
+                date_time="09/10/2025 03:00 PM",
+                pickup=pickup_location,
+                dropoff=dropoff_location,
+                passengers=2,
+                luggage=2,
+            )
+
+        # With Google Places integration
+        with Bookalimo(
+            credentials=creds,
+            google_places_api_key="your-google-api-key"
+        ) as client:
+            # Find locations using Google Places
+            places = client.places.search_text("Empire State Building")
+
+            # Use in booking
+            quote = client.pricing.quote(
+                rate_type=RateType.P2P,
+                date_time="09/10/2025 03:00 PM",
+                pickup=pickup_location,
+                dropoff=dropoff_location,
+                passengers=2,
+                luggage=2,
+            )
+    """
+
+    def __init__(
+        self,
+        *,
+        credentials: Optional[Credentials] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeouts: Any = DEFAULT_TIMEOUTS,
+        user_agent: str = DEFAULT_USER_AGENT,
+        transport: Optional[SyncTransport] = None,
+        google_places_api_key: Optional[str] = None,
+    ):
+        """
+        Initialize the sync Bookalimo client.
+
+        Args:
+            credentials: Authentication credentials (required for API calls)
+            base_url: API base URL
+            timeouts: Request timeout configuration
+            user_agent: User agent string
+            transport: Custom transport instance (optional)
+            google_places_api_key: Google Places API key for location services (optional)
+        """
+        if transport and transport.credentials is not None and credentials is not None:
+            warnings.warn(
+                "Credentials provided in both transport and constructor. "
+                "The transport credentials will be used.",
+                UserWarning,
+                stacklevel=2,
+            )
+        self._transport = transport or SyncTransport(
+            base_url=base_url,
+            timeouts=timeouts,
+            user_agent=user_agent,
+            credentials=credentials,
+        )
+
+        # Initialize service instances
+        self.reservations = ReservationsService(self._transport)
+        self.pricing = PricingService(self._transport)
+
+        # Initialize Google Places integration if available
+        self._google_places_api_key = google_places_api_key
+        self._google_places_client: Optional[GooglePlaces] = None
+
+    @property
+    def places(self) -> "GooglePlaces":
+        """
+        Access Google Places integration for location services.
+
+        Returns:
+            GooglePlaces client instance
+
+        Raises:
+            ImportError: If Google Places dependencies are not installed
+
+        Note:
+            Auth priority is as follows:
+              - provided api key in constructor
+              - GOOGLE_PLACES_API_KEY environment variable
+              - Google ADC - Except for Geocoding API.
+        """
+        if not _GOOGLE_PLACES_AVAILABLE:
+            raise ImportError(
+                "Google Places integration requires the 'places' extra. "
+                "Install with: pip install bookalimo[places]"
+            )
+
+        if self._google_places_client is None:
+            if _GooglePlaces is None:
+                raise ImportError("Google Places integration not available")
+            self._google_places_client = _GooglePlaces(
+                api_key=self._google_places_api_key
+            )
+
+        return self._google_places_client
+
+    def close(self) -> None:
+        """Close the client and clean up resources."""
+        self._transport.close()
+        if self._google_places_client is not None:
+            self._google_places_client.close()
+
+    def __enter__(self) -> "Bookalimo":
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Context manager exit."""
+        self.close()

bookalimo/config.py

@@ -0,0 +1,16 @@
+"""Configuration defaults for the Bookalimo SDK."""
+
+from ._version import __version__
+
+# Default API configuration
+DEFAULT_BASE_URL = "https://www.bookalimo.com/web/api"
+DEFAULT_TIMEOUT = 5.0
+DEFAULT_USER_AGENT = f"bookalimo-python/{__version__} (+https://github.com/asparagusbeef/bookalimo-python)"
+
+# Default retry configuration
+DEFAULT_RETRIES = 2
+DEFAULT_BACKOFF = 0.3
+DEFAULT_STATUS_FORCELIST = (500, 502, 503, 504)
+
+# Default timeouts (can be dict for httpx.Timeout)
+DEFAULT_TIMEOUTS = DEFAULT_TIMEOUT

bookalimo/exceptions.py

@@ -1,15 +1,125 @@
-from typing import Any, Optional
+"""Exception classes for the Bookalimo SDK."""
 
+from typing import Any, Literal, Optional
 
-class BookALimoError(Exception):
-    """Base exception for Book-A-Limo API errors."""
+from pydantic import ValidationError
+from pydantic_core import ErrorDetails, InitErrorDetails
+
+
+class BookalimoError(Exception): ...
+
+
+class BookalimoValidationError(BookalimoError):
+    """Validation error for input data that wraps Pydantic ValidationError."""
+
+    def __init__(
+        self, message: str, validation_error: Optional[ValidationError] = None
+    ):
+        """Initialize validation error with message and optional Pydantic ValidationError."""
+        super().__init__(message)
+        self._validation_error = validation_error
+        self._message = message
+
+    @property
+    def message(self) -> str:
+        """Get the error message."""
+        return self._message
+
+    def errors(self, **kwargs: Any) -> list[ErrorDetails]:
+        """Get validation errors if available."""
+        if self._validation_error:
+            return self._validation_error.errors(**kwargs)
+        return []
+
+    def error_count(self) -> int:
+        """Get error count."""
+        if self._validation_error:
+            return self._validation_error.error_count()
+        return 1
+
+    @property
+    def title(self) -> str:
+        """Get validation error title."""
+        if self._validation_error:
+            return self._validation_error.title
+        return "BookalimoValidationError"
+
+    def json(self, **kwargs: Any) -> str:
+        """Get errors as JSON string."""
+        if self._validation_error:
+            return self._validation_error.json(**kwargs)
+        import json
+
+        return json.dumps([{"type": "error", "msg": self._message, "loc": []}])
+
+    @classmethod
+    def from_exception_data(
+        cls,
+        title: str,
+        line_errors: list[InitErrorDetails],
+        input_type: Literal["python", "json"] = "python",
+        hide_input: bool = False,
+    ) -> "BookalimoValidationError":
+        """Create validation error from Pydantic error details."""
+        # Create a proper ValidationError
+        validation_error = ValidationError.from_exception_data(
+            title, line_errors, input_type, hide_input
+        )
+        return cls(f"Validation error in {title}", validation_error)
+
+    @classmethod
+    def from_validation_error(
+        cls, validation_error: ValidationError, message: Optional[str] = None
+    ) -> "BookalimoValidationError":
+        """Create BookalimoValidationError from an existing ValidationError."""
+        if message is None:
+            message = f"Validation error: {validation_error}"
+        return cls(message, validation_error)
+
+
+class BookalimoRequestError(BookalimoError): ...
+
+
+class BookalimoConnectionError(BookalimoError): ...
+
+
+class BookalimoHTTPError(BookalimoError):
+    """HTTP-related errors (4xx, 5xx responses)."""
 
     def __init__(
         self,
         message: str,
+        *,
         status_code: Optional[int] = None,
-        response_data: Optional[dict[str, Any]] = None,
+        payload: Optional[dict[str, Any]] = None,
     ):
         super().__init__(message)
+        self.message = message
         self.status_code = status_code
-        self.response_data = response_data or {}
+        self.payload = payload
+
+    def __str__(self) -> str:
+        base = super().__str__()
+        if self.payload and isinstance(self.payload, dict) and "error" in self.payload:
+            error_msg = self.payload["error"]
+            if self.status_code:
+                return f"{base}: {error_msg} (status_code={self.status_code})"
+            else:
+                return f"{base}: {error_msg}"
+        return f"{base} (status_code={self.status_code})" if self.status_code else base
+
+
+class BookalimoTimeout(BookalimoHTTPError):
+    """Request timeout errors."""
+
+    def __init__(self, message: str = "Request timeout", **kwargs: Any):
+        super().__init__(message, status_code=408, **kwargs)
+        self.message = message
+        self.status_code = 408
+        self.payload = kwargs.get("payload", None)
+
+
+class DuplicateCredentialsWarning(UserWarning): ...
+
+
+class MissingCredentialsWarning(UserWarning): ...

bookalimo/integrations/__init__.py

@@ -0,0 +1 @@
+"""Optional integrations for the Bookalimo SDK."""

bookalimo/integrations/google_places/__init__.py

@@ -0,0 +1,31 @@
+"""
+Google Places API integration for Bookalimo.
+
+This integration requires the 'places' extra:
+    pip install bookalimo[places]
+
+Examples:
+    # Async client
+    from bookalimo.integrations.google_places import AsyncGooglePlaces
+
+    async with AsyncGooglePlaces() as places:
+        results = await places.autocomplete("Empire State Building")
+
+    # Sync client
+    from bookalimo.integrations.google_places import GooglePlaces
+
+    with GooglePlaces() as places:
+        results = places.autocomplete("Empire State Building")
+"""
+
+try:
+    from .client_async import AsyncGooglePlaces
+    from .client_sync import GooglePlaces
+
+    __all__ = ["AsyncGooglePlaces", "GooglePlaces"]
+
+except ImportError as e:
+    raise ImportError(
+        "Google Places integration requires the 'places' extra. "
+        "Install with: pip install bookalimo[places]"
+    ) from e