Requests — Python HTTP for Humans

Introduction

Requests is the most downloaded Python package for making HTTP calls. It provides an intuitive API that abstracts away the complexity of urllib3, connection pooling, and content negotiation so developers can focus on interacting with web services rather than managing sockets.

What Requests Does

• Sends GET, POST, PUT, PATCH, DELETE, and HEAD requests with a single function call
• Handles JSON encoding and decoding automatically via r.json()
• Manages sessions with cookies, headers, and auth persisted across requests
• Supports file uploads, streaming downloads, and multipart form data
• Provides built-in authentication helpers for Basic, Digest, and token-based auth

Architecture Overview

Requests is a thin ergonomic layer on top of urllib3. Each call creates a PreparedRequest, passes it through a session (which applies default headers, cookies, and auth), sends it via an HTTPAdapter backed by a urllib3 PoolManager, and returns a Response object with decoded content. Connection pooling and keep-alive are handled transparently.

Setup & Configuration

• Install from PyPI: pip install requests
• Use requests.Session() to persist settings across multiple calls
• Configure retries via HTTPAdapter(max_retries=Retry(total=3))
• Set timeouts globally with session.request(..., timeout=(3.05, 27))
• Use environment variables HTTP_PROXY / HTTPS_PROXY for proxy configuration

Key Features

• Automatic content decoding with charset detection
• Connection pooling and keep-alive by default
• International domain name and URL support
• Streaming request and response bodies for large payloads
• Hook system for request and response inspection

Comparison with Similar Tools

• httpx — async-first with HTTP/2, Requests stays sync-only but simpler
• urllib3 — lower-level with more control, Requests wraps it for convenience
• aiohttp — async client and server, Requests is sync and client-only
• curl / pycurl — C-based with broader protocol support, Requests is pure Python

FAQ

Q: Does Requests support async? A: No. For async HTTP use httpx or aiohttp. Requests is designed for synchronous workflows.

Q: How do I handle rate limiting? A: Attach a retry strategy via HTTPAdapter with Retry(status_forcelist=[429], backoff_factor=1).

Q: Is Requests thread-safe? A: Session objects are not thread-safe. Use one Session per thread or protect access with a lock.

Q: How do I verify SSL certificates? A: Requests verifies SSL by default using certifi. Pass verify=False to disable or verify='/path/to/ca-bundle' for custom CAs.

Sources

• https://github.com/psf/requests
• https://docs.python-requests.org