CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-bravado

Library for accessing Swagger-enabled APIs

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

http-clients.mddocs/

HTTP Clients

Synchronous and asynchronous HTTP client implementations with pluggable adapters. Bravado provides two main HTTP client implementations: RequestsClient for synchronous operations and FidoClient for asynchronous/Twisted-based operations.

Capabilities

HttpClient (Base Interface)

Abstract base class defining the HTTP client interface that all implementations must follow.

class HttpClient:
    def request(self, request_params: dict, operation=None, request_config=None) -> HttpFuture: ...
    def __repr__(self) -> str: ...

Parameters:

  • request_params (dict): Complete request data including URL, method, headers, body, params, timeouts
  • operation: bravado_core.operation.Operation object (optional)
  • request_config: RequestConfig instance for per-request configuration

Returns:

  • HttpFuture object for handling the response

RequestsClient (Synchronous)

HTTP client implementation using the requests library for synchronous operations. Supports SSL configuration, authentication, and connection pooling.

class RequestsClient(HttpClient):
    def __init__(self, ssl_verify: bool = True, ssl_cert=None, future_adapter_class=RequestsFutureAdapter, response_adapter_class=RequestsResponseAdapter): ...
    def __hash__(self) -> int: ...
    def __eq__(self, other) -> bool: ...
    def __ne__(self, other) -> bool: ...
    def request(self, request_params: dict, operation=None, request_config=None) -> HttpFuture: ...
    def set_basic_auth(self, host: str, username: str, password: str): ...
    def set_api_key(self, host: str, api_key: str, param_name: str = 'api_key', param_in: str = 'query'): ...
    def separate_params(self, request_params: dict) -> tuple: ...
    def authenticated_request(self, request_params: dict): ...
    def apply_authentication(self, request): ...

Parameters:

  • ssl_verify (bool): Whether to verify SSL certificates (default: True)
  • ssl_cert: Path to SSL certificate file or (cert_file, key_file) tuple
  • future_adapter_class: Class to use for future adaptation
  • response_adapter_class: Class to use for response adaptation
  • host (str): Hostname for authentication
  • username (str): Username for basic auth
  • password (str): Password for basic auth
  • api_key (str): API key value
  • param_name (str): Parameter name for API key
  • param_in (str): Where to put API key ('query' or 'header')

Usage Example:

from bravado.requests_client import RequestsClient
from bravado.client import SwaggerClient

# Basic client
http_client = RequestsClient()
client = SwaggerClient.from_url(spec_url, http_client=http_client)

# With SSL configuration
http_client = RequestsClient(ssl_verify=False)  # Disable SSL verification
# or
http_client = RequestsClient(ssl_cert='/path/to/cert.pem')  # Custom certificate

# With authentication
http_client = RequestsClient()
http_client.set_basic_auth('api.example.com', 'username', 'secret')
client = SwaggerClient.from_url(spec_url, http_client=http_client)

FidoClient (Asynchronous)

HTTP client implementation using the fido library for asynchronous operations with Twisted. Requires the fido extra to be installed.

class FidoClient(HttpClient):
    def __init__(self, future_adapter_class=FidoFutureAdapter, response_adapter_class=FidoResponseAdapter): ...
    def __hash__(self) -> int: ...
    def __eq__(self, other) -> bool: ...
    def __ne__(self, other) -> bool: ...
    def request(self, request_params: dict, operation=None, request_config=None) -> HttpFuture: ...
    @staticmethod
    def prepare_request_for_twisted(request_params: dict): ...

Parameters:

  • future_adapter_class: Class to use for future adaptation (default: FidoFutureAdapter)
  • response_adapter_class: Class to use for response adaptation (default: FidoResponseAdapter)

Usage Example:

# Install: pip install bravado[fido]
from bravado.fido_client import FidoClient
from bravado.client import SwaggerClient

# Async client
http_client = FidoClient()
client = SwaggerClient.from_url(spec_url, http_client=http_client)

# Operations return HttpFuture objects that work with Twisted
future = client.pet.getPetById(petId=1)
response = future.response()  # This will integrate with Twisted's event loop

Future Adapters

Adapter classes that wrap different HTTP client futures to provide a uniform interface.

RequestsFutureAdapter

class RequestsFutureAdapter(FutureAdapter):
    timeout_errors: tuple  # (requests.exceptions.ReadTimeout,)
    connection_errors: tuple  # (requests.exceptions.ConnectionError,)
    def __init__(self, session, request, misc_options: dict): ...
    def result(self, timeout: float = None): ...
    def cancel(self): ...
    def build_timeout(self, result_timeout: float): ...

FidoFutureAdapter

class FidoFutureAdapter(FutureAdapter):
    timeout_errors: tuple  # (fido.exceptions.HTTPTimeoutError,)
    connection_errors: tuple  # Connection-related exceptions
    def __init__(self, eventual_result): ...
    def result(self, timeout: float = None): ...
    def cancel(self): ...

Response Adapters

Adapter classes that wrap different HTTP client responses to provide a uniform interface.

RequestsResponseAdapter

class RequestsResponseAdapter(IncomingResponse):
    def __init__(self, requests_lib_response): ...
    @property
    def status_code(self) -> int: ...
    @property
    def text(self) -> str: ...
    @property
    def raw_bytes(self) -> bytes: ...
    @property
    def reason(self) -> str: ...
    @property
    def headers(self) -> dict: ...
    def json(self, **kwargs): ...

FidoResponseAdapter

class FidoResponseAdapter(IncomingResponse):
    def __init__(self, fido_response): ...
    @property
    def status_code(self) -> int: ...
    @property
    def text(self) -> str: ...
    @property
    def raw_bytes(self) -> bytes: ...
    @property
    def reason(self) -> str: ...
    @property
    def headers(self) -> dict: ...
    def json(self, **_): ...

Client Selection Guidelines

Use RequestsClient when:

  • Building traditional synchronous applications
  • Using frameworks like Flask, Django, or FastAPI
  • Simple request/response patterns
  • Debugging and development (easier to understand flow)

Use FidoClient when:

  • Building high-concurrency applications
  • Using Twisted-based frameworks
  • Need to handle many concurrent API requests
  • Building microservices with async patterns

Custom HTTP Clients

You can implement custom HTTP clients by inheriting from HttpClient:

from bravado.http_client import HttpClient
from bravado.http_future import HttpFuture

class CustomHttpClient(HttpClient):
    def request(self, request_params, operation=None, request_config=None):
        # Implement your custom HTTP logic
        # Must return an HttpFuture object
        pass

Constants

APP_FORM: str  # 'application/x-www-form-urlencoded'
MULT_FORM: str  # 'multipart/form-data'

These constants are used for content type handling in form submissions.

Install with Tessl CLI

npx tessl i tessl/pypi-bravado

docs

authentication.md

client-management.md

configuration.md

exception-handling.md

http-clients.md

index.md

response-handling.md

spec-loading.md

testing-utilities.md

tile.json