Quick Start Guide

This guide will get you up and running with RequestX in just a few minutes.

Installation

Install RequestX using pip:

pip install requestx

That’s it! RequestX comes with all dependencies bundled, so no additional setup is required.

Basic Usage

RequestX provides the exact same API as the popular requests library. If you’re familiar with requests, you already know how to use RequestX!

Making Your First Request

import requestx

# Make a simple GET request
response = requestx.get('https://httpbin.org/json')

# Check the status
print(f"Status: {response.status_code}")

# Get JSON data
data = response.json()
print(f"Data: {data}")

Common HTTP Methods

RequestX supports all standard HTTP methods:

import requestx

# GET request
response = requestx.get('https://httpbin.org/get')

# POST request with JSON data
response = requestx.post('https://httpbin.org/post', json={'key': 'value'})

# PUT request with data
response = requestx.put('https://httpbin.org/put', data='some data')

# DELETE request
response = requestx.delete('https://httpbin.org/delete')

# HEAD request
response = requestx.head('https://httpbin.org/get')

# OPTIONS request
response = requestx.options('https://httpbin.org/get')

# PATCH request
response = requestx.patch('https://httpbin.org/patch', json={'update': 'value'})

Working with Parameters

Add URL parameters using the params argument:

import requestx

# URL parameters
params = {'key1': 'value1', 'key2': 'value2'}
response = requestx.get('https://httpbin.org/get', params=params)

# This makes a request to: https://httpbin.org/get?key1=value1&key2=value2
print(response.url)

Sending Data

Send data in various formats:

import requestx

# Send form data
data = {'username': 'user', 'password': 'pass'}
response = requestx.post('https://httpbin.org/post', data=data)

# Send JSON data
json_data = {'name': 'John', 'age': 30}
response = requestx.post('https://httpbin.org/post', json=json_data)

# Send raw data
response = requestx.post('https://httpbin.org/post', data='raw string data')

Custom Headers

Add custom headers to your requests:

import requestx

headers = {
    'User-Agent': 'RequestX/1.0',
    'Authorization': 'Bearer your-token-here',
    'Content-Type': 'application/json'
}

response = requestx.get('https://httpbin.org/headers', headers=headers)

Response Handling

Work with response data:

import requestx

response = requestx.get('https://httpbin.org/json')

# Status code
print(f"Status: {response.status_code}")

# Response headers
print(f"Content-Type: {response.headers['content-type']}")

# Text content
print(f"Text: {response.text}")

# JSON content (if applicable)
if response.headers.get('content-type', '').startswith('application/json'):
    data = response.json()
    print(f"JSON: {data}")

# Raw bytes
print(f"Content length: {len(response.content)} bytes")

Error Handling

Handle errors gracefully:

import requestx
from requestx import RequestException, HTTPError, ConnectionError, Timeout

try:
    response = requestx.get('https://httpbin.org/status/404', timeout=5)
    response.raise_for_status()  # Raises HTTPError for 4xx/5xx status codes
except HTTPError as e:
    print(f"HTTP Error: {e}")
except ConnectionError as e:
    print(f"Connection Error: {e}")
except Timeout as e:
    print(f"Timeout Error: {e}")
except RequestException as e:
    print(f"Request Error: {e}")

Async/Await Support

RequestX automatically detects async contexts and works seamlessly with async/await:

import asyncio
import requestx

async def fetch_data():
    # Same API, but automatically works in async context!
    response = await requestx.get('https://httpbin.org/json')
    return response.json()

async def main():
    data = await fetch_data()
    print(f"Received: {data}")

# Run the async function
asyncio.run(main())

Sessions for Connection Reuse

Use sessions for better performance when making multiple requests:

import requestx

# Create a session
session = requestx.Session()

# Set default headers for all requests in this session
session.headers.update({'User-Agent': 'RequestX-Session/1.0'})

# Make multiple requests - connections will be reused
response1 = session.get('https://httpbin.org/get')
response2 = session.get('https://httpbin.org/json')
response3 = session.post('https://httpbin.org/post', json={'session': 'data'})

# Sessions also work with async/await
async def async_session_example():
    async with requestx.Session() as session:
        response = await session.get('https://httpbin.org/json')
        return response.json()

Migration from Requests

If you’re migrating from the requests library, it’s as simple as changing the import:

# Before
import requests

response = requests.get('https://api.example.com/data')
data = response.json()

# After - just change the import!
import requestx as requests  # Drop-in replacement

response = requests.get('https://api.example.com/data')
data = response.json()

Or use RequestX directly:

import requestx

response = requestx.get('https://api.example.com/data')
data = response.json()

Next Steps

Now that you’ve learned the basics, explore more advanced features:

Performance Tips

To get the best performance from RequestX:

  1. Use sessions for multiple requests to the same host

  2. Enable connection pooling by reusing session objects

  3. Use async/await for I/O-bound operations

  4. Set appropriate timeouts to avoid hanging requests

  5. Consider HTTP/2 for modern APIs (automatically handled by RequestX)

import requestx

# Good: Reuse session for multiple requests
session = requestx.Session()
for i in range(10):
    response = session.get(f'https://api.example.com/item/{i}')
    process_response(response)

# Even better: Use async for concurrent requests
import asyncio

async def fetch_all():
    session = requestx.Session()
    tasks = []
    for i in range(10):
        task = session.get(f'https://api.example.com/item/{i}')
        tasks.append(task)

    responses = await asyncio.gather(*tasks)
    return responses