or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdconnection-pools.mdexceptions.mdindex.mdpool-management.mdresponse-handling.mdsimple-requests.mdutilities.md
tile.json

tessl/pypi-urllib3

HTTP library with thread-safe connection pooling, file post support, user friendly interface, and more.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/urllib3@2.0.x

To install, run

npx @tessl/cli install tessl/pypi-urllib3@2.0.0

index.mddocs/

urllib3

A powerful, user-friendly HTTP client for Python that brings many critical features missing from the Python standard libraries. urllib3 provides thread-safe connection pooling, client-side SSL/TLS verification, file uploads with multipart encoding, helpers for retrying requests and dealing with HTTP redirects, support for gzip/deflate/brotli/zstd encoding, and proxy support for HTTP and SOCKS.

Package Information

  • Package Name: urllib3
  • Package Type: pypi
  • Language: Python
  • Installation: pip install urllib3

Core Imports

import urllib3

Common usage patterns:

# Basic request functionality
from urllib3 import request

# Pool management
from urllib3 import PoolManager, ProxyManager

# Connection pools
from urllib3 import HTTPConnectionPool, HTTPSConnectionPool

# Configuration objects
from urllib3 import Retry, Timeout

# Response handling
from urllib3 import HTTPResponse, BaseHTTPResponse

# Header management
from urllib3 import HTTPHeaderDict

# Utility functions
from urllib3 import make_headers, encode_multipart_formdata

# Form field handling
from urllib3.fields import RequestField

Basic Usage

import urllib3

# Simple GET request using module-level function
resp = urllib3.request('GET', 'https://httpbin.org/json')
print(resp.status)  # 200
print(resp.data.decode('utf-8'))  # JSON response

# Using PoolManager for better performance and connection reuse
http = urllib3.PoolManager()
resp = http.request('GET', 'https://httpbin.org/json')
print(resp.status)  # 200
print(resp.data.decode('utf-8'))  # JSON response

# POST request with data
resp = http.request('POST', 'https://httpbin.org/post',
                   fields={'key': 'value'})

# Request with custom headers
resp = http.request('GET', 'https://httpbin.org/headers',
                   headers={'User-Agent': 'urllib3/2.0'})

# Request with JSON data
import json
resp = http.request('POST', 'https://httpbin.org/post',
                   body=json.dumps({'key': 'value'}),
                   headers={'Content-Type': 'application/json'})

Architecture

urllib3 uses a layered architecture that provides both simple interfaces and fine-grained control:

  • PoolManager: High-level interface that automatically manages connection pools across different hosts and protocols
  • Connection Pools: Per-host connection management with thread-safe connection reuse (HTTPConnectionPool, HTTPSConnectionPool)
  • Connections: Individual HTTP/HTTPS connections with SSL/TLS support
  • Response Objects: Comprehensive response handling with automatic content decoding and streaming support
  • Retry Logic: Configurable retry behavior with exponential backoff for various failure scenarios
  • Proxy Support: Built-in support for HTTP and SOCKS proxies with authentication

This design enables urllib3 to serve as the foundation HTTP library for many Python packages including requests, and provides the performance and reliability needed for production applications.

Capabilities

High-Level Request Interface

Simple, convenient functions for making HTTP requests without managing connection pools directly.

def request(method: str, url: str, *, body=None, fields=None, headers=None, 
           preload_content=True, decode_content=True, redirect=True, 
           retries=None, timeout=3, json=None) -> BaseHTTPResponse: ...

Simple Requests

Pool Management

Sophisticated connection pool management for high-performance HTTP clients with automatic host-based pooling and connection reuse.

class PoolManager:
    def __init__(self, num_pools=10, headers=None, **connection_pool_kw): ...
    def request(self, method: str, url: str, **kw) -> BaseHTTPResponse: ...
    def urlopen(self, method: str, url: str, **kw) -> BaseHTTPResponse: ...

class ProxyManager(PoolManager):
    def __init__(self, proxy_url, num_pools=10, headers=None, **connection_pool_kw): ...

Pool Management

Connection Pools

Direct connection pool management for specific hosts with fine-grained control over connection behavior and SSL/TLS settings.

class HTTPConnectionPool:
    def __init__(self, host: str, port=None, timeout=None, maxsize=1, 
                block=False, headers=None, retries=None, **conn_kw): ...
    def urlopen(self, method: str, url: str, **kw) -> BaseHTTPResponse: ...

class HTTPSConnectionPool(HTTPConnectionPool):
    def __init__(self, host: str, port=None, timeout=None, maxsize=1,
                block=False, headers=None, retries=None, **conn_kw): ...

Connection Pools

Response Handling

Comprehensive HTTP response objects with content decoding, streaming support, and metadata access.

class HTTPResponse(BaseHTTPResponse):
    @property
    def status(self) -> int: ...
    @property
    def headers(self) -> HTTPHeaderDict: ...
    @property
    def data(self) -> bytes: ...
    
    def read(self, amt=None, decode_content=None) -> bytes: ...
    def stream(self, amt=None, decode_content=None): ...
    def json(self) -> any: ...

Response Handling

Configuration Objects

Configuration classes for retry behavior, timeouts, and request customization.

class Retry:
    def __init__(self, total=10, connect=None, read=None, redirect=None,
                status=None, other=None, allowed_methods=None,
                status_forcelist=None, backoff_factor=0,
                backoff_max=120, raise_on_redirect=True,
                raise_on_status=True, history=None, **kw): ...

class Timeout:
    def __init__(self, total=None, connect=None, read=None): ...

Configuration

Utility Functions

Helper functions for header generation, multipart encoding, URL parsing, logging, and advanced field operations.

def make_headers(basic_auth=None, proxy_basic_auth=None, user_agent=None,
                keep_alive=None, accept_encoding=None) -> dict: ...

def encode_multipart_formdata(fields, boundary=None) -> tuple[bytes, str]: ...

def connection_from_url(url: str, **kw) -> HTTPConnectionPool: ...

def proxy_from_url(url: str, **kw) -> ProxyManager: ...

def add_stderr_logger(level: int = logging.DEBUG) -> logging.StreamHandler: ...

def disable_warnings(category: type[Warning] = exceptions.HTTPWarning) -> None: ...

def is_fp_closed(obj) -> bool: ...

def format_multipart_header_param(name: str, value: str | bytes) -> str: ...

Utilities

Exception Handling

Comprehensive exception hierarchy for handling various HTTP and network errors.

class HTTPError(Exception): ...
class PoolError(HTTPError): ...
class RequestError(PoolError): ...
class MaxRetryError(RequestError): ...
class TimeoutError(HTTPError): ...
class SSLError(HTTPError): ...
class ProxyError(HTTPError): ...

Exception Handling