{"id":9436,"library":"adafruit-circuitpython-connectionmanager","title":"Adafruit CircuitPython ConnectionManager","description":"Adafruit CircuitPython ConnectionManager (current version 3.1.7) provides a `urllib3.poolmanager`/`urllib3.connectionpool`-like interface for managing network sockets and connections, primarily on CircuitPython devices. It abstracts the underlying socket pool, making it easier to integrate with higher-level libraries like `adafruit-circuitpython-requests`. Releases occur periodically, often in response to bug fixes, dependency updates, or CPython compatibility improvements.","status":"active","version":"3.1.7","language":"en","source_language":"en","source_url":"https://github.com/adafruit/Adafruit_CircuitPython_ConnectionManager","tags":["circuitpython","adafruit","networking","sockets","http","https","connection-pooling"],"install":[{"cmd":"pip install adafruit-circuitpython-connectionmanager","lang":"bash","label":"Install library"},{"cmd":"pip install socketpool adafruit-circuitpython-requests","lang":"bash","label":"Install common companion libraries for CPython"}],"dependencies":[{"reason":"Provides the underlying socket interface (e.g., from network hardware drivers or CPython's `socket` module).","package":"socketpool","optional":false},{"reason":"Commonly used with ConnectionManager for making HTTP/HTTPS requests.","package":"adafruit-circuitpython-requests","optional":true}],"imports":[{"symbol":"ConnectionManager","correct":"from adafruit_connection_manager import ConnectionManager"},{"note":"PoolManager is an alias for ConnectionManager, often used for CPython compatibility.","symbol":"PoolManager","correct":"from adafruit_connection_manager import PoolManager"}],"quickstart":{"code":"import os\nimport socketpool\nimport adafruit_connection_manager\nimport adafruit_requests as requests\nimport ssl # Required for HTTPS\n\n# 1. Initialize a SocketPool.\n# For CPython, use `pip install socketpool`.\n# For CircuitPython, this would be provided by your board's firmware or a driver\n# like `adafruit_esp32spi.adafruit_esp32spi_socket` or `adafruit_wiznet5k.adafruit_wiznet5k_socket`.\npool = socketpool.SocketPool()\n\n# 2. Create an SSL context for HTTPS requests.\n# This is crucial for secure connections.\nssl_context = ssl.create_default_context()\n\n# 3. Instantiate ConnectionManager, passing the socket pool and SSL context.\nmanager = adafruit_connection_manager.ConnectionManager(pool, ssl_context)\n\n# 4. Set ConnectionManager as the socket interface for adafruit_requests.\n# For CPython, use `pip install adafruit-circuitpython-requests`.\nrequests.set_socket(manager)\n\n# 5. Make an HTTP(S) request.\n# Using os.environ.get for a safe default URL.\ntest_url = os.environ.get(\"TEST_URL\", \"https://httpbin.org/get\")\nprint(f\"Attempting to fetch data from: {test_url}\")\n\ntry:\n    response = requests.get(test_url)\n    print(f\"Status Code: {response.status_code}\")\n    print(f\"Response (first 100 chars): {response.text[:100]}...\")\n    response.close() # Important to close responses in CircuitPython\nexcept Exception as e:\n    print(f\"Error fetching URL: {e}\")\n\n","lang":"python","description":"This quickstart demonstrates how to initialize `ConnectionManager` with a `SocketPool` and `ssl` context, then integrate it with `adafruit-circuitpython-requests` to perform an HTTP(S) GET request. This example is runnable on CPython after installing `socketpool`, `adafruit-circuitpython-connectionmanager`, and `adafruit-circuitpython-requests`."},"warnings":[{"fix":"Update to 3.0.0+ and review network error handling code. New exceptions are more consistent with `urllib3`.","message":"Version 3.0.0 introduced significant changes related to SSL socket recycling and exception handling. Code relying on specific exception types for network failures or particular SSL behavior might break.","severity":"breaking","affected_versions":"< 3.0.0"},{"fix":"Ensure that your `adafruit-circuitpython-esp32spi` or `adafruit-circuitpython-wiznet5k` libraries (and associated firmware) are updated to compatible versions, typically the latest available.","message":"Version 2.0.0 updated its internal handling to match changes in `ESP32SPI` and `WIZNET5K` APIs. If you're using older versions of these underlying network drivers, `ConnectionManager` might not function correctly.","severity":"breaking","affected_versions":"< 2.0.0"},{"fix":"Always pass a properly configured `SocketPool` object to the `ConnectionManager` constructor, e.g., `manager = ConnectionManager(pool)`.","message":"ConnectionManager requires an initialized `SocketPool` instance, which it does not provide itself. This pool must come from a network driver (e.g., `adafruit_esp32spi_socket`, `adafruit_wiznet5k_socket`) on CircuitPython or the `socketpool` PyPI package on CPython.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When dealing with HTTPS, initialize `ConnectionManager` like this: `manager = ConnectionManager(pool, ssl_context=ssl.create_default_context())`.","message":"For HTTPS connections, a `ssl.create_default_context()` object must be passed to the `ConnectionManager` constructor. Without it, attempts to connect to HTTPS endpoints will fail.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"For CircuitPython, ensure your network driver (e.g., `adafruit_esp32spi`) is initialized and its socket interface is set (e.g., `esp32spi_socket.set_interface(esp)`). For CPython, run `pip install socketpool`.","cause":"This usually occurs when trying to use `socketpool.SocketPool()` in a CircuitPython environment where the `socketpool` module is not correctly set up by a network driver, or on CPython if the `socketpool` PyPI package is not installed.","error":"AttributeError: 'module' object has no attribute 'SocketPool'"},{"fix":"Install `adafruit-circuitpython-requests`. For CircuitPython, use `circup install adafruit_requests`. For CPython, use `pip install adafruit-circuitpython-requests`.","cause":"You are likely trying to use `adafruit-circuitpython-requests` without it being installed on your CircuitPython board or in your CPython environment.","error":"RuntimeError: Please install the 'requests' CircuitPython library (or similar missing dependency error)"},{"fix":"Verify your network connection (Wi-Fi, Ethernet), ensure `secrets.py` (if on CircuitPython) has correct credentials, and check that your network allows DNS lookups.","cause":"This error indicates a DNS resolution failure, meaning the device cannot convert a domain name (like `example.com`) into an IP address. This is typically due to incorrect network configuration (e.g., Wi-Fi credentials, gateway, DNS servers).","error":"socket.gaierror: [Errno -2] Name or service not known"},{"fix":"Pass an initialized `SocketPool` instance as the first argument to `ConnectionManager`, e.g., `manager = ConnectionManager(pool)`.","cause":"You attempted to create a `ConnectionManager` instance without providing the mandatory `socket_pool` object.","error":"TypeError: ConnectionManager() missing 1 required positional argument: 'socket_pool'"}]}