SOCKS4 and SOCKS4A API documentation

SOCKS4 and SOCKS4A are almost identical protocols, as such the API is implemented in a single module and most components are shared.

The only practical difference is the usage of a SOCKS4Request versus SOCKS4ARequest.

Remember SOCKS4 allows only for IPv4 addresses and SOCKS4A supports domain names. Neither support IPv6.

class socksio.socks4.SOCKS4Connection(user_id: bytes)

Encapsulates a SOCKS4 and SOCKS4A connection.

Packs request objects into data suitable to be send and unpacks reply data into their appropriate reply objects.

Parameters:: user_id – The user ID to be sent as part of the requests.

data_to_send() → bytes

Returns the data to be sent via the I/O library of choice.

Also clears the connection’s buffer.

receive_data(data: bytes) → SOCKS4Reply

Unpacks response data into a reply object.

Parameters:: data – The raw response data from the proxy server.
Returns:: The appropriate reply object.

send(request: SOCKS4Request | SOCKS4ARequest) → None

Packs a request object and adds it to the send data buffer.

Parameters:: request – The request instance to be packed.

class socksio.socks4.SOCKS4Request(command: SOCKS4Command, port: int, addr: bytes, user_id: bytes | None = None)

Encapsulates a request to the SOCKS4 proxy server

Parameters:

command – The command to request.
port – The port number to connect to on the target host.
addr – IP address of the target host.
user_id – Optional user ID to be included in the request, if not supplied the user must provide one in the packing operation.

dumps(user_id: bytes | None = None) → bytes

Packs the instance into a raw binary in the appropriate form.

Parameters:: user_id – Optional user ID as an override, if not provided the instance’s will be used, if none was provided at initialization an error is raised.
Returns:: The packed request.
Raises:: SOCKSError – If no user was specified in this call or on initialization.

classmethod from_address(command: SOCKS4Command, address: str | bytes | Tuple[str | bytes, int], user_id: bytes | None = None) → SOCKS4Request

Convenience class method to build an instance from command and address.

Parameters:

command – The command to request.
address – A string in the form ‘HOST:PORT’ or a tuple of ip address string and port number.
user_id – Optional user ID.

Returns:

A SOCKS4Request instance.

Raises:

SOCKSError – If a domain name or IPv6 address was supplied.

class socksio.socks4.SOCKS4ARequest(command: SOCKS4Command, port: int, addr: bytes, user_id: bytes | None = None)

Encapsulates a request to the SOCKS4A proxy server

Parameters:

command – The command to request.
port – The port number to connect to on the target host.
addr – IP address of the target host.
user_id – Optional user ID to be included in the request, if not supplied the user must provide one in the packing operation.

dumps(user_id: bytes | None = None) → bytes

Packs the instance into a raw binary in the appropriate form.

Parameters:: user_id – Optional user ID as an override, if not provided the instance’s will be used, if none was provided at initialization an error is raised.
Returns:: The packed request.
Raises:: SOCKSError – If no user was specified in this call or on initialization.

classmethod from_address(command: SOCKS4Command, address: str | bytes | Tuple[str | bytes, int], user_id: bytes | None = None) → SOCKS4ARequest

Convenience class method to build an instance from command and address.

Parameters:

command – The command to request.
address – A string in the form ‘HOST:PORT’ or a tuple of ip address string and port number.
user_id – Optional user ID.

Returns:

A SOCKS4ARequest instance.

class socksio.socks4.SOCKS4Reply(reply_code: SOCKS4ReplyCode, port: int, addr: str | None)