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

bookalimo/transport/utils.py

@@ -1,9 +1,18 @@
 import logging
-from typing import Any, Optional
+from contextlib import contextmanager
+from time import perf_counter
+from typing import Any, Callable, Generator, NoReturn, Optional, Union, cast, overload
 
 import httpx
 
-from ..exceptions import BookalimoError, BookalimoHTTPError, BookalimoTimeout
+from ..exceptions import (
+    BookalimoConnectionError,
+    BookalimoError,
+    BookalimoHTTPError,
+    BookalimoRequestError,
+    BookalimoTimeout,
+)
+from ..logging import configure_httpx_logging, redact_url
 
 logger = logging.getLogger("bookalimo.transport")
 
@@ -31,7 +40,7 @@ def handle_api_errors(
 
 def handle_http_error(
     response: httpx.Response, req_id: Optional[str], path: str
-) -> None:
+) -> NoReturn:
     """Handle HTTP status errors."""
     status = response.status_code
 
@@ -57,3 +66,195 @@ def handle_http_error(
         status_code=status,
         payload=payload if isinstance(payload, dict) else {"raw": payload},
     )
+
+
+def build_url(base_url: str, path: str) -> str:
+    """Build full URL ensuring a single leading slash on path and no trailing slash on base."""
+    norm_base = base_url.rstrip("/")
+    norm_path = path if path.startswith("/") else f"/{path}"
+    return f"{norm_base}{norm_path}"
+
+
+def get_request_id(resp: httpx.Response) -> Optional[str]:
+    """Extract a request id header if present."""
+    return cast(Optional[str], resp.headers.get("x-request-id")) or cast(
+        Optional[str], resp.headers.get("request-id")
+    )
+
+
+def parse_json_or_raise(
+    response: httpx.Response, path: str, req_id: Optional[str]
+) -> Any:
+    """Parse response JSON or raise a helpful error with preview.
+
+    Returns parsed JSON value on success; raises BookalimoError on invalid JSON.
+    """
+    try:
+        return 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 ""
+        raise BookalimoError(f"Invalid JSON response: {preview}") from e
+
+
+def raise_if_retryable_status(
+    response: httpx.Response, should_retry_status: Callable[[int], bool]
+) -> None:
+    """Raise httpx.HTTPStatusError for retryable status codes so retry logic can handle it."""
+    if should_retry_status(response.status_code):
+        raise httpx.HTTPStatusError(
+            message=f"Retryable HTTP status: {response.status_code}",
+            request=response.request,
+            response=response,
+        )
+
+
+def pre_log(url: str, body_keys: list[str], req_id: str) -> None:
+    """Standard pre-request debug log."""
+    logger.debug("→ [%s] POST %s body_keys=%s", req_id, redact_url(url), body_keys)
+
+
+def post_log(url: str, response: httpx.Response, start: float, req_id: str) -> None:
+    """Standard post-response debug log."""
+    dur_ms = (perf_counter() - start) * 1000.0
+    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,
+        redact_url(url),
+        dur_ms,
+        content_len,
+        get_request_id(response),
+    )
+
+
+@contextmanager
+def map_httpx_exceptions(
+    req_id: Optional[str], path: str
+) -> Generator[None, None, None]:
+    """Map common httpx exceptions to domain-specific exceptions.
+
+    Ensures we consistently translate low-level httpx errors.
+    """
+    try:
+        yield
+    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__
+            )
+        # Preserve underlying message
+        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
+
+
+def log_request(request: httpx.Request) -> None:
+    """Event hook to log HTTP requests with redacted URLs (sync version)."""
+    if logger.isEnabledFor(logging.DEBUG):
+        logger.debug(
+            "HTTP Request: %s %s",
+            request.method,
+            redact_url(str(request.url)),
+        )
+
+
+async def log_request_async(request: httpx.Request) -> None:
+    """Event hook to log HTTP requests with redacted URLs (async version)."""
+    if logger.isEnabledFor(logging.DEBUG):
+        logger.debug(
+            "HTTP Request: %s %s",
+            request.method,
+            redact_url(str(request.url)),
+        )
+
+
+def _log_response(response: httpx.Response) -> None:
+    """Event hook to log HTTP responses with redacted URLs."""
+    if logger.isEnabledFor(logging.DEBUG):
+        request = response.request
+        logger.debug(
+            "HTTP Response: %s %s -> %d",
+            request.method,
+            redact_url(str(request.url)),
+            response.status_code,
+        )
+
+
+def log_response(response: httpx.Response) -> None:
+    """Event hook to log HTTP responses with redacted URLs."""
+    _log_response(response)
+
+
+async def log_response_async(response: httpx.Response) -> None:
+    """Event hook to log HTTP responses with redacted URLs."""
+    _log_response(response)
+
+
+@overload
+def setup_secure_logging_and_client(
+    *,
+    is_async: bool,
+    timeout: Any,
+    client: Optional[httpx.AsyncClient],
+) -> tuple[httpx.AsyncClient, bool]: ...
+
+
+@overload
+def setup_secure_logging_and_client(
+    *,
+    is_async: bool,
+    timeout: Any,
+    client: Optional[httpx.Client],
+) -> tuple[httpx.Client, bool]: ...
+
+
+def setup_secure_logging_and_client(
+    *,
+    is_async: bool,
+    timeout: Any,
+    client: Optional[Union[httpx.Client, httpx.AsyncClient]] = None,
+) -> tuple[Union[httpx.Client, httpx.AsyncClient], bool]:
+    """
+    Configure secure logging and create httpx client with event hooks if needed.
+
+    Returns:
+        Tuple of (client, owns_client_flag)
+    """
+    # Configure httpx logging to prevent sensitive data exposure
+    configure_httpx_logging()
+
+    if client is not None:
+        return client, False
+
+    # Create client with secure logging event hooks
+    event_hooks: dict[str, list[Callable[..., Any]]] = (
+        {
+            "request": [log_request_async if is_async else log_request],
+            "response": [log_response_async if is_async else log_response],
+        }
+        if logger.isEnabledFor(logging.DEBUG)
+        else {}
+    )
+
+    if is_async:
+        return httpx.AsyncClient(timeout=timeout, event_hooks=event_hooks), True
+    else:
+        return httpx.Client(timeout=timeout, event_hooks=event_hooks), True

bookalimo-1.0.2.dist-info/METADATA

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: bookalimo
+Version: 1.0.2
+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: Programming Language :: Python :: 3.13
+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"
+Requires-Dist: numpy>=2.0.0; extra == "places"
+Requires-Dist: rapidfuzz>=3.0.0; extra == "places"
+Requires-Dist: typing-extensions>=4.15.0; python_version < "3.11" and 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)
+[![Docs](https://img.shields.io/github/deployments/asparagusbeef/bookalimo-python/github-pages?label=docs&logo=github)](https://asparagusbeef.github.io/bookalimo-python)
+[![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.
+
+## Design philosophy: IDE-first DX
+
+The library is **comprehensively typed** and **richly documented** via docstrings. Most users can rely on IDE hints, docstrings, and autocomplete without reading the docs.
+
+## Features
+
+- **Async & Sync Support** – `AsyncBookalimo` and `Bookalimo` clients
+- **Type Safety** – Full Pydantic models with validation
+- **Google Places Integration** – Location search and geocoding
+- **Automatic Retry** – Built-in exponential backoff
+- **Resource Management** – Context managers for proper cleanup
+
+## Installation
+
+```bash
+pip install bookalimo
+
+# With Google Places integration
+pip install bookalimo[places]
+```
+
+## Quick Example
+
+```python
+import asyncio
+from bookalimo import (
+    AsyncBookalimo,
+)
+from bookalimo.transport.auth import (
+    Credentials,
+)
+from bookalimo.schemas import (
+    RateType,
+    Location,
+    LocationType,
+    Address,
+    City,
+    Airport,
+    PriceRequest,
+    BookRequest,
+)
+
+
+async def book_ride():
+    credentials = Credentials.create(
+        "your_id",
+        "your_password",
+        is_customer=False,
+    )
+
+    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.AIRPORT,
+        airport=Airport(iata_code="JFK"),
+    )
+
+    async with AsyncBookalimo(credentials=credentials) as client:
+        # Get pricing
+        quote = await client.pricing.quote(
+            PriceRequest(
+                rate_type=RateType.P2P,
+                date_time="12/25/2024 03:00 PM",
+                pickup=pickup,
+                dropoff=dropoff,
+                passengers=2,
+                luggage=2,
+            )
+        )
+
+        # Book reservation
+        booking = await client.reservations.book(
+            BookRequest(
+                token=quote.token,
+                method="charge",
+            )
+        )
+        return booking.reservation_id
+
+
+confirmation = asyncio.run(book_ride())
+```
+
+## Sync Usage
+
+```python
+from bookalimo import (
+    Bookalimo,
+)
+
+with Bookalimo(credentials=credentials) as client:
+    quote = client.pricing.quote(PriceRequest(...))
+    booking = client.reservations.book(
+        BookRequest(
+            token=quote.token,
+            method="charge",
+        )
+    )
+```
+
+## 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("Hilton Miami Beach")
+
+    # Resolve airports near landmarks
+    airports = await client.places.resolve_airport(query="eiffel tower")
+    top_airport = airports[0]  # Closest airport with confidence scoring
+
+    # Use in booking flow
+    quote = await client.pricing.quote(...)
+```
+
+## 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}")
+except BookalimoHTTPError as e:
+    if e.status_code == 401:
+        print("Authentication failed")
+```
+
+## Environment
+
+```bash
+export GOOGLE_PLACES_API_KEY="your_google_places_key"
+export BOOKALIMO_LOG_LEVEL="DEBUG"
+```
+
+## Documentation
+
+**📖 Complete Documentation:** [https://asparagusbeef.github.io/bookalimo-python](https://asparagusbeef.github.io/bookalimo-python)
+
+## Requirements
+
+* Python 3.9+
+* Book-A-Limo API credentials
+* Dependencies: httpx, pydantic, pycountry, us, airportsdata, typing-extensions for Python 3.9-3.10
+  - Optional: google-maps-places, google-api-core, numpy, rapidfuzz
+
+## Support & Resources
+
+* GitHub: [https://github.com/asparagusbeef/bookalimo-python](https://github.com/asparagusbeef/bookalimo-python)
+* PyPI: [https://pypi.org/project/bookalimo/](https://pypi.org/project/bookalimo/)
+* Issues: [https://github.com/asparagusbeef/bookalimo-python/issues](https://github.com/asparagusbeef/bookalimo-python/issues)
+* Changelog: [CHANGELOG.md](./CHANGELOG.md)
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.

bookalimo-1.0.2.dist-info/RECORD

@@ -0,0 +1,40 @@
+bookalimo/__init__.py,sha256=ZFDpnSOo5VQEgusbVAxyF-neFxBptPZANZ-eE1PeIsU,516
+bookalimo/_version.py,sha256=KcHRbOssHorjmpk3Xs1RTqGNSA-sw9tjYqwV19Zfa9c,259
+bookalimo/client.py,sha256=g_Mep6yjwCE8l5cYTKsvuy0eW78TpP9NSsRmnqNdUDY,11414
+bookalimo/config.py,sha256=K3HlCj8v34kFM2MaG9evGFomU95hRmenRi1zqe4h8EY,456
+bookalimo/exceptions.py,sha256=pShnuvfMZEP_cChczWhNBLIqa7EOgr4ZNnWj6kphARU,4001
+bookalimo/logging.py,sha256=Z6it7PxjdwQ5P6C8VtyKn14Lftt19WwwZAQ1n5zrMqM,10585
+bookalimo/py.typed,sha256=8PjyZ1aVoQpRVvt71muvuq5qE-jTFZkK-GLHkhdebmc,26
+bookalimo/integrations/__init__.py,sha256=edmQP2Uo8JiNIVaeB4rxM8vagz7BQBhyGEJo70OVS0M,51
+bookalimo/integrations/google_places/__init__.py,sha256=A6jBfGk8ZLYgFiTCGBytBOsyzKVWHI_kjnuZOgdCONc,866
+bookalimo/integrations/google_places/client_async.py,sha256=ai-tZJLsUpmgklRBt2-5n1_nDsBY34dzr2k_ZoqenH4,9144
+bookalimo/integrations/google_places/client_sync.py,sha256=ZfACzI01IEH8w6LGdMui-_t1Kc8lV-VRrV3XOP06M_k,8958
+bookalimo/integrations/google_places/common.py,sha256=lLRRgJnZ-uDincxv9vW5il3_LHhY0yY8eGYhkYItkNA,16140
+bookalimo/integrations/google_places/proto_adapter.py,sha256=XuVDr-PH9fopykRwNZxQTS_kIBCdwPwcNYBIHCZjmRo,6809
+bookalimo/integrations/google_places/resolve_airport.py,sha256=tnsZ5rFteu9HxOj72AQ7O9TJLQPKO3i0oLA_7hNNHDI,14580
+bookalimo/integrations/google_places/transports.py,sha256=O3JB73kRm4BU7MT0eUFQhe5jocZ8Z_gI94bvgvjifJU,3342
+bookalimo/schemas/__init__.py,sha256=7utetaurplWJ-w1PtsbARl2HkuGHhBq3EMorTUuF8Vg,4075
+bookalimo/schemas/base.py,sha256=Qyq72xycTF1TR5ZZIOclUENJ6M9FYhXmnVBSabJ_XJc,3802
+bookalimo/schemas/requests.py,sha256=EoB5GIMCd7eiddoHeV4uPjERRrK0iCXWB1dNNGvuneM,5490
+bookalimo/schemas/responses.py,sha256=3tVfoOblezKcoz5s_CLm4LJwqe9qpO2W9jMVZysZHsQ,4691
+bookalimo/schemas/shared.py,sha256=loXKjpbsTz1-LH17V_IeQ38bXQIplPz_E1Zkgj0gNRM,11053
+bookalimo/schemas/places/__init__.py,sha256=EZvAPG69VDzrtmduvOkMA8mHiOf_bQh4XEsK7777ikk,1451
+bookalimo/schemas/places/common.py,sha256=SjY3FbsAQKM5o6DDtLIBx1yvJJGc29UUVVtWglQoSh8,10927
+bookalimo/schemas/places/field_mask.py,sha256=L6bDkGYpkX63drm4HgDtlNr-GLmgELGCCEWSznlNgWU,6628
+bookalimo/schemas/places/google.py,sha256=_9HU67Coj2UAJyac5F7Cp0GflyjfLRso4tyIWa2rNns,35392
+bookalimo/schemas/places/place.py,sha256=5jBqMbPHbRTtXeoFaUtRoIUdzvJeCgMRdeyVt88Axe0,10681
+bookalimo/services/__init__.py,sha256=4wom7MpoeqKy5y99LYFKkl-CAJ7faDN9ZlXUhKVqlAg,303
+bookalimo/services/pricing.py,sha256=MDgvYZGDuYYncEr8d2sZumVW3phFbj6GFXMGIaz3kuc,2095
+bookalimo/services/reservations.py,sha256=CLfvHKl81jb50yk9kPuD37O1F4rmYzjoJ6aioQw-byY,4101
+bookalimo/transport/__init__.py,sha256=yD5TDnoqg1xtex41jqJ7Hes849efiYgvW3nkaYr6ZjE,221
+bookalimo/transport/auth.py,sha256=Uq9ybiBg51FMs4NWJ50idX8v2MOOomawluZ7Ca2Xs4I,1257
+bookalimo/transport/base.py,sha256=qeX2HfLaE6gUT5evjOdPiBh8x7z7A84UuWVsgBK3Pyo,1394
+bookalimo/transport/httpx_async.py,sha256=feVBMPzWBUA_bBT_oHLK1-lhYSuhWSGjW_E6s9ZhWZ4,4717
+bookalimo/transport/httpx_sync.py,sha256=XVGlt4HTpNHFndPQi4cy0V2XzRhZ7G6VjZi-3yXv8fg,4868
+bookalimo/transport/retry.py,sha256=YiJtcdNZUbkrLa1CtKsRtcFO273XJX8naKd8d6ht0LU,2688
+bookalimo/transport/utils.py,sha256=YPAPRCC2FIPpR-AFuccQ0IZDvg5r3aNSvHWyXdYw-BM,8472
+bookalimo-1.0.2.dist-info/licenses/LICENSE,sha256=dW9UYOWGfs9eFlJvwSSkJBDhPRic2mrgFkg6aA0xkMM,1070
+bookalimo-1.0.2.dist-info/METADATA,sha256=DD52pPu_uOQVpq6PVgjP-tQ3ztO9eHfaouBKfpTlX-4,8136
+bookalimo-1.0.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+bookalimo-1.0.2.dist-info/top_level.txt,sha256=ZgYiDX2GfZCp4pevWn4X2qyEr-Dh7-cq5Y1j2jMhB1s,10
+bookalimo-1.0.2.dist-info/RECORD,,