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

bookalimo/transport/httpx_sync.py

@@ -0,0 +1,230 @@
+"""Sync HTTP transport using httpx."""
+
+import logging
+from time import perf_counter
+from typing import Any, Optional, TypeVar, Union, overload
+from uuid import uuid4
+
+import httpx
+from pydantic import BaseModel
+
+from ..config import (
+    DEFAULT_BACKOFF,
+    DEFAULT_BASE_URL,
+    DEFAULT_RETRIES,
+    DEFAULT_TIMEOUTS,
+    DEFAULT_USER_AGENT,
+)
+from ..exceptions import (
+    BookalimoConnectionError,
+    BookalimoError,
+    BookalimoHTTPError,
+    BookalimoRequestError,
+    BookalimoTimeout,
+)
+from .auth import Credentials, inject_credentials
+from .base import BaseTransport
+from .retry import should_retry_exception, should_retry_status, sync_retry
+from .utils import handle_api_errors, handle_http_error
+
+logger = logging.getLogger("bookalimo.transport")
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class SyncTransport(BaseTransport):
+    """Sync HTTP transport using httpx."""
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        timeouts: Any = DEFAULT_TIMEOUTS,
+        user_agent: str = DEFAULT_USER_AGENT,
+        credentials: Optional[Credentials] = None,
+        client: Optional[httpx.Client] = None,
+        retries: int = DEFAULT_RETRIES,
+        backoff: float = DEFAULT_BACKOFF,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.credentials = credentials
+        self.retries = retries
+        self.backoff = backoff
+        self.headers = {
+            "content-type": "application/json",
+            "user-agent": user_agent,
+        }
+
+        # Create client if not provided
+        self._owns_client = client is None
+        self.client = client or httpx.Client(timeout=timeouts)
+
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug(
+                "SyncTransport initialized (base_url=%s, timeout=%s, user_agent=%s)",
+                self.base_url,
+                timeouts,
+                user_agent,
+            )
+
+    @overload
+    def post(self, path: str, model: BaseModel) -> Any: ...
+    @overload
+    def post(self, path: str, model: BaseModel, response_model: type[T]) -> T: ...
+
+    def post(
+        self, path: str, model: BaseModel, response_model: Optional[type[T]] = None
+    ) -> Union[T, Any]:
+        """Make a POST request and return parsed response."""
+        # Prepare URL
+        path = path if path.startswith("/") else f"/{path}"
+        url = f"{self.base_url}{path}"
+
+        # Prepare data and inject credentials
+        data = self.prepare_data(model)
+        data = inject_credentials(data, self.credentials)
+
+        # Debug logging
+        req_id = None
+        start = 0.0
+        if logger.isEnabledFor(logging.DEBUG):
+            req_id = uuid4().hex[:8]
+            start = perf_counter()
+            body_keys = sorted(k for k in data.keys() if k != "credentials")
+            logger.debug(
+                "→ [%s] POST %s body_keys=%s",
+                req_id,
+                path,
+                body_keys,
+            )
+
+        try:
+            # Make request with retry logic
+            response = sync_retry(
+                lambda: self._make_request(url, data),
+                retries=self.retries,
+                backoff=self.backoff,
+                should_retry=lambda e: should_retry_exception(e)
+                or (
+                    isinstance(e, httpx.HTTPStatusError)
+                    and should_retry_status(e.response.status_code)
+                ),
+            )
+
+            # Handle HTTP errors
+            if response.status_code >= 400:
+                handle_http_error(response, req_id, path)
+
+            # Parse JSON
+            try:
+                json_data = response.json()
+            except ValueError as e:
+                if logger.isEnabledFor(logging.DEBUG):
+                    logger.warning("× [%s] %s invalid JSON", req_id or "-", path)
+                preview = (
+                    (response.text or "")[:256] if hasattr(response, "text") else None
+                )
+                raise BookalimoError(
+                    f"Invalid JSON response: {preview}",
+                ) from e
+
+            # Handle API-level errors
+            handle_api_errors(json_data, req_id, path)
+
+            # Debug logging for success
+            if logger.isEnabledFor(logging.DEBUG):
+                dur_ms = (perf_counter() - start) * 1000.0
+                reqid_hdr = response.headers.get(
+                    "x-request-id"
+                ) or response.headers.get("request-id")
+                content_len = (
+                    len(response.content) if hasattr(response, "content") else None
+                )
+                logger.debug(
+                    "← [%s] %s %s in %.1f ms len=%s reqid=%s",
+                    req_id,
+                    response.status_code,
+                    path,
+                    dur_ms,
+                    content_len,
+                    reqid_hdr,
+                )
+
+            # Parse and return response
+            return (
+                response_model.model_validate(json_data)
+                if response_model
+                else json_data
+            )
+
+        except httpx.TimeoutException:
+            if logger.isEnabledFor(logging.DEBUG):
+                logger.warning("× [%s] %s timeout", req_id or "-", path)
+            raise BookalimoTimeout("Request timeout") from None
+
+        except httpx.ConnectError:
+            if logger.isEnabledFor(logging.DEBUG):
+                logger.warning("× [%s] %s connection error", req_id or "-", path)
+            raise BookalimoConnectionError(
+                "Connection error - unable to reach Book-A-Limo API"
+            ) from None
+        except httpx.RequestError as e:
+            if logger.isEnabledFor(logging.DEBUG):
+                logger.warning(
+                    "× [%s] %s request error: %s",
+                    req_id or "-",
+                    path,
+                    e.__class__.__name__,
+                )
+            raise BookalimoRequestError(f"Request Error: {e}") from e
+
+        except httpx.HTTPStatusError as e:
+            if logger.isEnabledFor(logging.DEBUG):
+                logger.warning(
+                    "× [%s] %s HTTP error: %s",
+                    req_id or "-",
+                    path,
+                    e.__class__.__name__,
+                )
+            status_code = getattr(getattr(e, "response", None), "status_code", None)
+            raise BookalimoHTTPError(f"HTTP Error: {e}", status_code=status_code) from e
+
+        except (BookalimoError, BookalimoHTTPError):
+            # Already handled above
+            raise
+
+        except Exception as e:
+            if logger.isEnabledFor(logging.DEBUG):
+                logger.warning(
+                    "× [%s] %s unexpected error: %s",
+                    req_id or "-",
+                    path,
+                    e.__class__.__name__,
+                )
+            raise BookalimoError(f"Unexpected error: {str(e)}") from e
+
+    def _make_request(self, url: str, data: dict[str, Any]) -> httpx.Response:
+        """Make the actual HTTP request."""
+        resp = self.client.post(url, json=data, headers=self.headers)
+        if should_retry_status(resp.status_code):
+            # Construct an HTTPStatusError so sync_retry can catch & decide.
+            raise httpx.HTTPStatusError(
+                message=f"Retryable HTTP status: {resp.status_code}",
+                request=resp.request,
+                response=resp,
+            )
+        return resp
+
+    def close(self) -> None:
+        """Close the HTTP client if we own it."""
+        if self._owns_client and not self.client.is_closed:
+            self.client.close()
+            if logger.isEnabledFor(logging.DEBUG):
+                logger.debug("SyncTransport HTTP client closed")
+
+    def __enter__(self) -> "SyncTransport":
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Context manager exit."""
+        self.close()

bookalimo/transport/retry.py

@@ -0,0 +1,102 @@
+"""Retry logic and backoff utilities."""
+
+import asyncio
+import random
+from collections.abc import Awaitable
+from typing import Callable, TypeVar, Union
+
+import httpx
+
+from ..config import DEFAULT_STATUS_FORCELIST
+
+T = TypeVar("T")
+
+
+def should_retry_status(
+    status_code: int, status_forcelist: tuple[int, ...] = DEFAULT_STATUS_FORCELIST
+) -> bool:
+    """Check if a status code should trigger a retry."""
+    return status_code in status_forcelist
+
+
+def should_retry_exception(exc: Exception) -> bool:
+    """Check if an exception should trigger a retry."""
+    return isinstance(
+        exc,
+        (
+            httpx.TimeoutException,
+            httpx.ConnectError,
+            httpx.ReadTimeout,
+            httpx.ConnectError,
+            ConnectionError,
+        ),
+    )
+
+
+def calculate_backoff(attempt: int, base_backoff: float) -> float:
+    """Calculate exponential backoff with jitter."""
+    # Exponential backoff: base * (2 ^ attempt)
+    backoff = base_backoff * (2**attempt)
+    # Add jitter: ±25% randomization
+    jitter = backoff * 0.25 * (random.random() * 2 - 1)  # nosec B311: non-crypto jitter
+    return float(max(0.1, backoff + jitter))  # Minimum 100ms
+
+
+async def async_retry(
+    func: Callable[[], Awaitable[T]],
+    retries: int,
+    backoff: float,
+    should_retry: Callable[[Exception], bool],
+) -> T:
+    """Retry an async function with exponential backoff."""
+    attempt = 0
+    last_exc: Union[Exception, None] = None
+
+    while attempt <= retries:
+        try:
+            return await func()
+        except Exception as e:
+            last_exc = e
+            if attempt >= retries or not should_retry(e):
+                break
+
+            wait_time = calculate_backoff(attempt, backoff)
+            await asyncio.sleep(wait_time)
+            attempt += 1
+
+    if last_exc is not None:
+        raise last_exc
+    else:
+        raise RuntimeError("Last exception is None")
+
+
+def sync_retry(
+    func: Callable[[], T],
+    retries: int,
+    backoff: float,
+    should_retry: Callable[[Exception], bool],
+) -> T:
+    """Retry a sync function with exponential backoff."""
+    import time
+
+    attempt = 0
+    last_exc: Union[Exception, None] = None
+
+    while attempt <= retries:
+        try:
+            return func()
+        except Exception as e:
+            last_exc = e
+            if attempt >= retries or not should_retry(e):
+                break
+
+            wait_time = calculate_backoff(attempt, backoff)
+            time.sleep(wait_time)
+            attempt += 1
+
+    # Re-raise the last exception
+    if last_exc is not None:
+        raise last_exc
+    else:
+        raise RuntimeError("Last exception is None")
+    raise last_exc

bookalimo/transport/utils.py

@@ -0,0 +1,59 @@
+import logging
+from typing import Any, Optional
+
+import httpx
+
+from ..exceptions import BookalimoError, BookalimoHTTPError, BookalimoTimeout
+
+logger = logging.getLogger("bookalimo.transport")
+
+
+def handle_api_errors(
+    json_data: Any,
+    req_id: Optional[str],
+    path: str,
+) -> None:
+    """Handle API-level errors in the response."""
+    if not isinstance(json_data, dict):
+        return
+
+    if json_data.get("error"):
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.warning("× [%s] %s API error", req_id or "-", path)
+        raise BookalimoError(f"API Error: {json_data['error']}")
+
+    if "success" in json_data and not json_data["success"]:
+        msg = json_data.get("error", "Unknown API error")
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.warning("× [%s] %s API error", req_id or "-", path)
+        raise BookalimoError(f"API Error: {msg}")
+
+
+def handle_http_error(
+    response: httpx.Response, req_id: Optional[str], path: str
+) -> None:
+    """Handle HTTP status errors."""
+    status = response.status_code
+
+    if status == 408:
+        raise BookalimoTimeout(f"HTTP {status}: Request timeout")
+    elif status in (502, 503, 504):
+        raise BookalimoHTTPError(
+            f"HTTP {status}: Service unavailable", status_code=status
+        )
+
+    # Try to parse error payload
+    try:
+        payload = response.json()
+    except Exception as e:
+        text_preview = (response.text or "")[:256] if hasattr(response, "text") else ""
+        raise BookalimoHTTPError(
+            f"HTTP {status}: {text_preview}",
+            status_code=status,
+        ) from e
+
+    raise BookalimoHTTPError(
+        f"HTTP {status}",
+        status_code=status,
+        payload=payload if isinstance(payload, dict) else {"raw": payload},
+    )

bookalimo-1.0.0.dist-info/METADATA

@@ -0,0 +1,307 @@
+Metadata-Version: 2.4
+Name: bookalimo
+Version: 1.0.0
+Summary: Python wrapper for the Book-A-Limo API
+Author-email: Jonathan Oren <jonathan@bookalimo.com>
+Maintainer-email: Jonathan Oren <jonathan@bookalimo.com>
+License: MIT
+Project-URL: Homepage, https://github.com/asparagusbeef/bookalimo-python
+Project-URL: Documentation, https://asparagusbeef.github.io/bookalimo-python
+Project-URL: Repository, https://github.com/asparagusbeef/bookalimo-python
+Project-URL: Issues, https://github.com/asparagusbeef/bookalimo-python/issues
+Project-URL: Changelog, https://github.com/asparagusbeef/bookalimo-python/blob/main/CHANGELOG.md
+Keywords: bookalimo,api,transportation,booking
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.11.0
+Requires-Dist: pycountry>=22.0.0
+Requires-Dist: us>=3.0.0
+Requires-Dist: airportsdata>=20230101
+Provides-Extra: places
+Requires-Dist: google-maps-places>=0.1.0; extra == "places"
+Requires-Dist: google-api-core>=2.0.0; extra == "places"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
+Requires-Dist: httpx[mock]>=0.25.0; extra == "dev"
+Requires-Dist: respx>=0.20.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Requires-Dist: python-dotenv>=1.0.0; extra == "dev"
+Requires-Dist: types-protobuf>=6.0.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0.0; extra == "test"
+Requires-Dist: pytest-mock>=3.10.0; extra == "test"
+Requires-Dist: httpx[mock]>=0.25.0; extra == "test"
+Requires-Dist: respx>=0.20.0; extra == "test"
+Dynamic: license-file
+
+# Bookalimo Python SDK
+
+[![codecov](https://codecov.io/gh/asparagusbeef/bookalimo-python/branch/main/graph/badge.svg?token=H588J8Q1M8)](https://codecov.io/gh/asparagusbeef/bookalimo-python)
+[![Documentation Status](https://readthedocs.org/projects/bookalimo-python/badge/?version=latest)](https://bookalimo-python.readthedocs.io/en/latest/?badge=latest)
+[![PyPI version](https://badge.fury.io/py/bookalimo.svg)](https://badge.fury.io/py/bookalimo)
+[![Python Support](https://img.shields.io/pypi/pyversions/bookalimo.svg)](https://pypi.org/project/bookalimo/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+Python client library for the Book-A-Limo transportation booking API with async/sync support, type safety, and Google Places integration.
+
+## Features
+
+- **Async & Sync Support** - Choose the right client for your use case
+- **Type Safety** - Full Pydantic models with validation
+- **Google Places Integration** - Location search and geocoding
+- **Automatic Retry** - Built-in exponential backoff for reliability
+- **Comprehensive Error Handling** - Detailed exceptions with context
+
+## Installation
+
+```bash
+pip install bookalimo
+
+# With Google Places integration
+pip install bookalimo[places]
+```
+
+## Core API
+
+### Clients
+- `AsyncBookalimo` - Async client for high-concurrency applications
+- `Bookalimo` - Sync client for simple scripts and legacy code
+
+### Services
+- `client.pricing` - Get quotes and update booking details
+- `client.reservations` - Book, list, modify, and cancel reservations
+- `client.places` - Google Places search and geocoding (optional)
+
+### Authentication
+SHA256-based credential system with automatic password hashing:
+```python
+from bookalimo.transport.auth import Credentials
+
+# Agency account
+credentials = Credentials.create("AGENCY123", "password", is_customer=False)
+
+# Customer account
+credentials = Credentials.create("user@email.com", "password", is_customer=True)
+```
+
+### Booking Flow
+1. **Get Pricing** - `client.pricing.quote()` returns session token + vehicle options
+2. **Update Details** - `client.pricing.update_details()` modifies booking (optional)
+3. **Book Reservation** - `client.reservations.book()` confirms with payment
+
+## Quick Example
+
+```python
+import asyncio
+from bookalimo import AsyncBookalimo
+from bookalimo.transport.auth import Credentials
+from bookalimo.schemas.booking import RateType, Location, LocationType, Address, City
+
+async def book_ride():
+    credentials = Credentials.create("your_id", "your_password")
+
+    # Define locations
+    pickup = Location(
+        type=LocationType.ADDRESS,
+        address=Address(
+            place_name="Empire State Building",
+            city=City(city_name="New York", country_code="US", state_code="NY")
+        )
+    )
+
+    dropoff = Location(
+        type=LocationType.ADDRESS,
+        address=Address(
+            place_name="JFK Airport",
+            city=City(city_name="New York", country_code="US", state_code="NY")
+        )
+    )
+
+    async with AsyncBookalimo(credentials=credentials) as client:
+        # 1. Get pricing
+        quote = await client.pricing.quote(
+            rate_type=RateType.P2P,
+            date_time="12/25/2024 03:00 PM",
+            pickup=pickup,
+            dropoff=dropoff,
+            passengers=2,
+            luggage=2
+        )
+
+        # 2. Book reservation
+        booking = await client.reservations.book(
+            token=quote.token,
+            method="charge"  # or credit_card=CreditCard(...)
+        )
+
+        return booking.reservation_id
+
+confirmation = asyncio.run(book_ride())
+```
+
+## Rate Types & Options
+
+```python
+from bookalimo.schemas.booking import RateType
+
+# Point-to-point transfer
+quote = await client.pricing.quote(
+    rate_type=RateType.P2P,
+    pickup=pickup_location,
+    dropoff=dropoff_location,
+    # ...
+)
+
+# Hourly service (minimum 2 hours)
+quote = await client.pricing.quote(
+    rate_type=RateType.HOURLY,
+    hours=4,
+    pickup=pickup_location,
+    dropoff=pickup_location,  # Same for hourly
+    # ...
+)
+
+# Daily service
+quote = await client.pricing.quote(
+    rate_type=RateType.DAILY,
+    pickup=hotel_location,
+    dropoff=hotel_location,
+    # ...
+)
+```
+
+## Location Types
+
+```python
+from bookalimo.schemas.booking import Location, LocationType, Address, Airport, City
+
+# Street address
+address_location = Location(
+    type=LocationType.ADDRESS,
+    address=Address(
+        place_name="Empire State Building",
+        street_name="350 5th Ave",
+        city=City(city_name="New York", country_code="US", state_code="NY")
+    )
+)
+
+# Airport with flight details
+airport_location = Location(
+    type=LocationType.AIRPORT,
+    airport=Airport(
+        iata_code="JFK",
+        flight_number="UA123",
+        terminal="4"
+    )
+)
+```
+
+## Google Places Integration
+
+```python
+async with AsyncBookalimo(
+    credentials=credentials,
+    google_places_api_key="your-google-places-key"
+) as client:
+    # Search locations
+    results = await client.places.search("JFK Airport Terminal 4")
+
+    # Convert to booking location
+    location = Location(
+        type=LocationType.ADDRESS,
+        address=Address(
+            google_geocode=results[0].google_place.model_dump(),
+            place_name=results[0].formatted_address
+        )
+    )
+```
+
+## Reservation Management
+
+```python
+# List reservations
+reservations = await client.reservations.list(is_archive=False)
+
+# Get details
+details = await client.reservations.get("ABC123")
+
+# Modify reservation
+edit_result = await client.reservations.edit(
+    confirmation="ABC123",
+    passengers=3,
+    pickup_date="12/26/2024"
+)
+
+# Cancel reservation
+cancel_result = await client.reservations.edit(
+    confirmation="ABC123",
+    is_cancel=True
+)
+```
+
+## Error Handling
+
+```python
+from bookalimo.exceptions import BookalimoHTTPError, BookalimoValidationError
+
+try:
+    booking = await client.reservations.book(...)
+except BookalimoValidationError as e:
+    print(f"Invalid input: {e.message}")
+    for error in e.errors():
+        print(f"  {error['loc']}: {error['msg']}")
+except BookalimoHTTPError as e:
+    if e.status_code == 401:
+        print("Authentication failed")
+    elif e.status_code == 400:
+        print(f"Bad request: {e.payload}")
+```
+
+## Documentation
+
+**📖 [Complete Documentation](https://asparagusbeef.github.io/bookalimo-python)**
+
+- [Quick Start Guide](https://asparagusbeef.github.io/bookalimo-python/guide/quickstart/)
+- [API Reference](https://asparagusbeef.github.io/bookalimo-python/api/)
+- [Examples](https://asparagusbeef.github.io/bookalimo-python/examples/basic/)
+
+## Environment Options
+
+```bash
+export GOOGLE_PLACES_API_KEY="your_google_places_key"
+export BOOKALIMO_LOG_LEVEL="DEBUG"
+```
+
+## Requirements
+
+- Python 3.9+
+- Book-A-Limo API credentials
+- Dependencies: httpx, pydantic, pycountry, us, airportsdata
+- Optional: google-maps-places (for Places integration)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.