Registry / http-networking / adafruit-circuitpython-connectionmanager

adafruit-circuitpython-connectionmanager

JSON →
library3.1.7pypypi✓ verified 49d ago

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.

http-networking
pip install adafruit-circuitpython-connectionmanager
Install & Compatibility
Where this runs
tested against v3.1.8 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.069s · 28.9MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 3.1s · import 0.063s · 29MB
27MB installed
● package 27MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ConnectionManager
from adafruit_connection_manager import ConnectionManager
PoolManager
from adafruit_connection_manager import PoolManager
PoolManager is an alias for ConnectionManager, often used for CPython compatibility.

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`.

import os import socketpool import adafruit_connection_manager import adafruit_requests as requests import ssl # Required for HTTPS # 1. Initialize a SocketPool. # For CPython, use `pip install socketpool`. # For CircuitPython, this would be provided by your board's firmware or a driver # like `adafruit_esp32spi.adafruit_esp32spi_socket` or `adafruit_wiznet5k.adafruit_wiznet5k_socket`. pool = socketpool.SocketPool() # 2. Create an SSL context for HTTPS requests. # This is crucial for secure connections. ssl_context = ssl.create_default_context() # 3. Instantiate ConnectionManager, passing the socket pool and SSL context. manager = adafruit_connection_manager.ConnectionManager(pool, ssl_context) # 4. Set ConnectionManager as the socket interface for adafruit_requests. # For CPython, use `pip install adafruit-circuitpython-requests`. requests.set_socket(manager) # 5. Make an HTTP(S) request. # Using os.environ.get for a safe default URL. test_url = os.environ.get("TEST_URL", "https://httpbin.org/get") print(f"Attempting to fetch data from: {test_url}") try: response = requests.get(test_url) print(f"Status Code: {response.status_code}") print(f"Response (first 100 chars): {response.text[:100]}...") response.close() # Important to close responses in CircuitPython except Exception as e: print(f"Error fetching URL: {e}")
Debug
Known issues
breakingVersion 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.
fix
Update to 3.0.0+ and review network error handling code. New exceptions are more consistent with `urllib3`.
affects: < 3.0.0
breakingVersion 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.
fix
Ensure that your `adafruit-circuitpython-esp32spi` or `adafruit-circuitpython-wiznet5k` libraries (and associated firmware) are updated to compatible versions, typically the latest available.
affects: < 2.0.0
gotchaConnectionManager 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.
fix
Always pass a properly configured `SocketPool` object to the `ConnectionManager` constructor, e.g., `manager = ConnectionManager(pool)`.
affects: All versions
gotchaFor 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.
fix
When dealing with HTTPS, initialize `ConnectionManager` like this: `manager = ConnectionManager(pool, ssl_context=ssl.create_default_context())`.
affects: All versions
Errors
Common errors & fixes
AttributeError: 'module' object has no attribute 'SocketPool'
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.
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`.
RuntimeError: Please install the 'requests' CircuitPython library (or similar missing dependency error)
You are likely trying to use `adafruit-circuitpython-requests` without it being installed on your CircuitPython board or in your CPython environment.
fix
Install `adafruit-circuitpython-requests`. For CircuitPython, use `circup install adafruit_requests`. For CPython, use `pip install adafruit-circuitpython-requests`.
socket.gaierror: [Errno -2] Name or service not known
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).
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.
TypeError: ConnectionManager() missing 1 required positional argument: 'socket_pool'
You attempted to create a `ConnectionManager` instance without providing the mandatory `socket_pool` object.
fix
Pass an initialized `SocketPool` instance as the first argument to `ConnectionManager`, e.g., `manager = ConnectionManager(pool)`.
Upgrade
Version history
3.1.8latest on PyPI
Audit
Dependencies
socketpoolrequiredProvides the underlying socket interface (e.g., from network hardware drivers or CPython's `socket` module).
adafruit-circuitpython-requestsoptionalCommonly used with ConnectionManager for making HTTP/HTTPS requests.
Agent activity
86 hits · last 30 days
node
8
claudebot
4
mj12bot
3
ahrefsbot
3
amazonbot
1
bytedance
1
Resources