{"library":"socksio","title":"socksio library","type":"library","description":"socksio is a sans-I/O implementation of the SOCKS4, SOCKS4A, and SOCKS5 proxy protocols. It provides the state machines necessary for handling SOCKS proxy negotiation without performing any network I/O itself, making it ideal for integration into asynchronous network frameworks. Currently at version 1.0.0, it follows a stable release cadence with releases primarily for bug fixes or minor enhancements.","language":"python","status":"active","last_verified":"Wed May 20","install":{"commands":["pip install socksio"],"cli":null},"imports":["from socksio import Socks5Connection","from socksio import Socks5AuthMethods","from socksio import SOCKS5_NO_AUTH","from socksio import ConnectionState","from socksio import BadSocksConnectionState"],"auth":{"required":false,"env_vars":[]},"links":{"homepage":null,"github":"https://github.com/sethmlarson/socksio","docs":null,"changelog":null,"pypi":"https://pypi.org/project/socksio/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null},"quickstart":{"code":"from socksio import Socks5Connection, Socks5AuthMethods, SOCKS5_NO_AUTH, ConnectionState\n\n# This example demonstrates the SOCKS5 state machine, it does not perform actual network I/O.\n# In a real application, 'client_greeting_data' would be written to a socket,\n# and 'server_greeting_response' would be read from that socket.\n\n# 1. Initialize a SOCKS5 connection to a target host and port.\ntarget_host = \"example.com\"\ntarget_port = 80\nconn = Socks5Connection(target_host, target_port)\nprint(f\"Initial state: {conn.state}\") # Expected: ConnectionState.INIT\n\n# 2. Client sends greeting with supported authentication methods.\n# For SOCKS5, common is NO_AUTH.\nclient_greeting_data = conn.send(Socks5AuthMethods([SOCKS5_NO_AUTH]))\nprint(f\"\\nClient sends greeting ({len(client_greeting_data)} bytes): {client_greeting_data.hex()}\")\nprint(f\"State after sending greeting: {conn.state}\") # Expected: ConnectionState.WAITING_FOR_AUTH_METHOD_SELECTION\n\n# 3. Simulate server response to greeting.\n# A SOCKS5 server typically responds with version (0x05) and selected method (0x00 for NO_AUTH).\nserver_greeting_response = b'\\x05\\x00'\nconn.receive(server_greeting_response)\nprint(f\"\\nServer responds to greeting ({len(server_greeting_response)} bytes): {server_greeting_response.hex()}\")\nprint(f\"State after receiving greeting response: {conn.state}\") # Expected: ConnectionState.AUTH_SUCCESS\n\n# 4. Client sends connection request.\n# The `send()` method generates the connect request based on target_host/port.\nclient_connect_data = conn.send()\nprint(f\"\\nClient sends connect request ({len(client_connect_data)} bytes): {client_connect_data.hex()}\")\nprint(f\"State after sending connect request: {conn.state}\") # Expected: ConnectionState.WAITING_FOR_CONNECT_REPLY\n\n# 5. Simulate server response to connection request.\n# A successful SOCKS5 connect reply for IPv4 would be:\n# 0x05 (version) 0x00 (success) 0x00 (reserved) 0x01 (IPv4 address type)\n# followed by bound address (4 bytes, e.g., 127.0.0.1) and bound port (2 bytes, e.g., 80)\nserver_connect_response = b'\\x05\\x00\\x00\\x01\\x7f\\x00\\x00\\x01\\x00\\x50' # 127.0.0.1:80\nconn.receive(server_connect_response)\nprint(f\"\\nServer responds to connect request ({len(server_connect_response)} bytes): {server_connect_response.hex()}\")\nprint(f\"Final state: {conn.state}\") # Expected: ConnectionState.OPEN\n\nif conn.is_connected:\n    print(\"\\nSOCKS5 handshake successfully completed (simulated).\")\n    print(f\"Bound address: {conn.bound_address}, Bound port: {conn.bound_port}\")\nelse:\n    print(\"\\nSOCKS5 handshake failed (simulated).\")\n","lang":"python","description":"This quickstart demonstrates the core functionality of `socksio` by simulating a SOCKS5 proxy handshake. It shows how to initialize a connection, send client data, receive simulated server responses, and observe the state transitions. Remember that `socksio` handles only the protocol state machine, not actual network I/O.","tag":null,"tag_description":null,"last_tested":"2026-04-24","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]},"compatibility":{"tag":null,"tag_description":null,"last_tested":"2026-05-20","installed_version":"1.0.0","pypi_latest":"1.0.0","is_stale":false,"summary":{"python_range":"3.10–3.9","success_rate":50,"avg_install_s":1.5,"avg_import_s":null,"wheel_type":"wheel"},"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"socksio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"17.9M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"socksio","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"socksio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":1.4,"import_time_s":null,"mem_mb":null,"disk_size":"18M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"socksio","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"socksio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"19.7M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"socksio","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"socksio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":1.6,"import_time_s":null,"mem_mb":null,"disk_size":"20M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"socksio","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"socksio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"11.6M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"socksio","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"socksio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":1.4,"import_time_s":null,"mem_mb":null,"disk_size":"12M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"socksio","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"socksio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"11.3M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"socksio","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"socksio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":1.4,"import_time_s":null,"mem_mb":null,"disk_size":"12M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"socksio","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"socksio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"17.4M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"socksio","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"socksio","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":1.7,"import_time_s":null,"mem_mb":null,"disk_size":"18M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"socksio","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]}}