{"id":9433,"library":"adafruit-circuitpython-requests","title":"Adafruit CircuitPython Requests","description":"Adafruit CircuitPython Requests provides a requests-like API for making HTTP requests from CircuitPython microcontrollers. It offers a familiar interface for GET, POST, PUT, DELETE, and HEAD operations, allowing microcontrollers with network capabilities (like WiFi or Ethernet) to interact with web services. The current version is 4.1.16, and it typically follows a rapid release cadence with bug fixes and minor improvements.","status":"active","version":"4.1.16","language":"python","source_language":"en","source_url":"https://github.com/adafruit/Adafruit_CircuitPython_Requests","tags":["CircuitPython","networking","HTTP","requests-like","microcontroller","IoT"],"install":[{"cmd":"pip install adafruit-circuitpython-requests","lang":"bash","label":"For host computer (e.g., Raspberry Pi with Blinka)"},{"cmd":"circup install adafruit_requests","lang":"bash","label":"For CircuitPython device (via circup)"}],"dependencies":[{"reason":"Enables running some CircuitPython libraries on single-board computers like Raspberry Pi with CPython.","package":"adafruit-blinka","optional":true},{"reason":"Provides low-level bus communication utilities, often used by network hardware drivers.","package":"adafruit-circuitpython-busdevice","optional":false},{"reason":"Provides type hinting support for CircuitPython specific types.","package":"adafruit-circuitpython-typing","optional":false}],"imports":[{"wrong":"import adafruit_requests","symbol":"Session","correct":"from adafruit_requests import Session"},{"symbol":"Response","correct":"from adafruit_requests import Response"},{"symbol":"OutOfRetries","correct":"from adafruit_requests import OutOfRetries"}],"quickstart":{"code":"import ssl\nimport socketpool # Required for network communication\nimport wifi # Required for WiFi connectivity\nimport adafruit_requests\n\n# --- This section requires CircuitPython board setup ---\n# In a real CircuitPython environment, you'd connect to WiFi:\n# try:\n#     from secrets import secrets\n# except ImportError:\n#     print(\"WiFi secrets are kept in secrets.py, please add them there!\")\n#     raise\n# wifi.radio.connect(secrets[\"ssid\"], secrets[\"password\"])\n# pool = socketpool.SocketPool(wifi.radio)\n\n# --- For demonstration purposes (not runnable without actual network setup) ---\n# Mock objects for local run-ability, replace with real ones on device:\nclass MockRadio:\n    ipv4_address = \"192.168.1.100\"\nclass MockSocketPool:\n    def __init__(self, radio):\n        pass\n    # In a real scenario, this would create actual sockets\n    def socket(self, family, type, proto=0):\n        raise NotImplementedError(\"Mock socketpool does not provide real sockets\")\nclass MockSSLContext:\n    def __init__(self):\n        pass\n# Replace these mocks with real objects on a CircuitPython board\nwifi.radio = MockRadio()\npool = MockSocketPool(wifi.radio)\nssl_context = MockSSLContext()\n\n# Initialize the requests session with a socket pool and SSL context\n# On a real CircuitPython device: requests = adafruit_requests.Session(pool, ssl.create_default_context())\nrequests = adafruit_requests.Session(pool, ssl_context)\n\n# Make a GET request (this will fail in mock, but demonstrates API)\ntry:\n    response = requests.get(\"http://example.com/api/data\")\n    print(f\"Status Code: {response.status_code}\")\n    print(f\"Response Text: {response.text}\")\n    response.close()\nexcept Exception as e:\n    print(f\"Error making request (expected in mock setup): {e}\")\n\n# Make a POST request with JSON data\npost_data = {\"key\": \"value\"}\ntry:\n    response = requests.post(\"http://example.com/api/submit\", json=post_data)\n    print(f\"POST Status Code: {response.status_code}\")\n    print(f\"POST Response Text: {response.text}\")\n    response.close()\nexcept Exception as e:\n    print(f\"Error making POST request (expected in mock setup): {e}\")","lang":"python","description":"This quickstart demonstrates the `adafruit_requests.Session` API. Note that actual network operations on CircuitPython require configuring `wifi.radio` (or Ethernet) and creating a `socketpool.SocketPool` instance, which involves specific hardware and `secrets.py` setup not fully runnable in a generic Python environment. The provided code includes mock objects to illustrate the API without requiring actual hardware, but real network requests will fail."},"warnings":[{"fix":"Ensure you are targeting a CircuitPython board with proper network hardware (WiFi, Ethernet) and an initialized `socketpool`.","message":"This library is designed for CircuitPython microcontrollers. Running it on a standard CPython environment (e.g., PC) will require `adafruit-blinka` and potentially custom `socketpool` and `wifi` implementations or mocks, and won't interact with physical network hardware directly.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Request only necessary data, use streaming where possible, or parse responses chunk by chunk if the API allows. Consider the `response.iter_content()` method for streaming large responses.","message":"Microcontrollers have limited memory. Large HTTP responses (e.g., big JSON files, images) can quickly exhaust RAM, leading to `MemoryError` or system crashes.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use `ssl.create_default_context()` where possible for HTTPS. For custom certificates or older hardware, consult Adafruit's CircuitPython documentation for specific SSL setup instructions for your board.","message":"SSL/TLS support on microcontrollers is resource-intensive. `ssl.create_default_context()` might not always be available or performant, and specific certificate handling might be required, especially for HTTPS.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Design your application to handle blocking operations gracefully. Consider using asynchronous patterns if available (e.g., `asyncio` on some boards, though not directly supported by `adafruit_requests`), or implement timeouts for requests to prevent indefinite blocking.","message":"HTTP requests are typically blocking operations. A long request or a network timeout can freeze your CircuitPython program until it completes or fails.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'4.1.16':51 'adafruit':1,4 'allow':33 'api':12 'bug':61 'cadenc':59 'capabl':37 'circuitpython':2,5,18,66 'current':48 'delet':29 'ethernet':41 'familiar':23 'fix':62 'follow':55 'get':26 'head':31 'http':15,68 'improv':65 'interact':43 'interfac':24 'iot':73 'like':11,38,71 'make':14 'microcontrol':19,34,72 'minor':64 'network':36,67 'offer':21 'oper':32 'post':27 'provid':7 'put':28 'rapid':57 'releas':58 'request':3,6,10,16,70 'requests-lik':9,69 'servic':46 'typic':54 'version':49 'web':45 'wifi':39","created_at":"2026-04-17T01:18:53.052254+00:00","updated_at":"2026-04-17T01:18:53.052254+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"4.1.17","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/adafruit/Adafruit_CircuitPython_Requests","docs":null,"changelog":null,"pypi":"https://pypi.org/project/adafruit-circuitpython-requests/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-30","last_verified":"2026-06-30","next_check":"2026-07-30","install_tag":null}}