Simplified HTTP REST Client

Warnings

• gotcha The library utilizes a dynamic approach for building API paths and calling HTTP methods, using `client._('path_segment').method()`. This can be less explicit than other HTTP clients and might cause confusion if a path segment name clashes with an HTTP method (e.g., 'get') or a built-in client method.
  Fix: Be mindful of path segment names and understand the dynamic method resolution. Always consult the API documentation you are integrating with to correctly structure your calls.
• gotcha `python-http-client` internally uses the standard library's `urllib.request`. This means that lower-level HTTP errors (e.g., `urllib.error.HTTPError`) might be raised or wrapped, and direct inspection of the `Response` object's `status_code` and `body` is often necessary for comprehensive error handling, rather than relying solely on exception types for all HTTP status errors.
  Fix: Implement robust error handling that checks the `response.status_code` after a request and handles common HTTP status codes (e.g., 4xx, 5xx) appropriately. Leverage the `Response` object's attributes for detailed error information.
• gotcha Failing to set a `timeout` parameter when initializing the `Client` can lead to hanging requests if the remote server is unresponsive or slow. This can cause applications to freeze or consume resources indefinitely.
  Fix: Always provide a `timeout` value (in seconds) to the `Client` constructor. For example: `client = Client(host=HOST, timeout=30)`. Consider using separate connect and read timeouts for finer control if your application requires it, though the library's `timeout` parameter is a single value.

Install

• pip install python-http-client Install stable version

Imports

• Client

  from python_http_client import Client

  The standard library's `http.client` is a different, much lower-level module. This library provides a higher-level, simplified interface.

Quickstart

This quickstart demonstrates how to initialize the `Client` with a base host and optional headers, then construct and execute a GET and POST request to a generic API endpoint using its dynamic path building and HTTP verb methods. It includes placeholders for API host and key, ideally read from environment variables.

import os
from python_http_client import Client

# Replace with your actual API host (e.g., "https://api.example.com")
# Using httpbin.org for a simple example.
HOST = os.environ.get('API_HOST', 'https://httpbin.org')
API_KEY = os.environ.get('API_KEY', '') # For APIs requiring authorization

def make_request():
    try:
        # Instantiate the client with base host and optional headers
        # For an API like SendGrid, 'version' might be a parameter.
        client = Client(host=HOST, request_headers={
            "Authorization": f"Bearer {API_KEY}"
        } if API_KEY else {}) 

        # Example: GET request to /get endpoint
        # The _() method adds path segments dynamically
        # .get() performs the GET request
        print(f"\nMaking GET request to {HOST}/get")
        response = client._('get').get()

        print(f"GET Status Code: {response.status_code}")
        print(f"GET Response Body: {response.to_dict()}")

        # Example: POST request to /post endpoint with data
        data = {"message": "Hello from python-http-client!"}
        print(f"\nMaking POST request to {HOST}/post with body: {data}")
        post_response = client._('post').post(request_body=data)

        print(f"POST Status Code: {post_response.status_code}")
        print(f"POST Response Body: {post_response.to_dict()}")

    except Exception as e:
        print(f"An error occurred: {e}")

if __name__ == "__main__":
    make_request()