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) → socksio.socks4.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: Union[socksio.socks4.SOCKS4Request, socksio.socks4.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

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: Optional[bytes] = 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: socksio.socks4.SOCKS4Command, address: Union[str, bytes, Tuple[Union[str, bytes], int]], user_id: Optional[bytes] = None) → socksio.socks4.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

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: Optional[bytes] = 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: socksio.socks4.SOCKS4Command, address: Union[str, bytes, Tuple[Union[str, bytes], int]], user_id: Optional[bytes] = None) → socksio.socks4.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

Encapsulates a reply from the SOCKS4 proxy server

Parameters:
  • reply_code – The code representing the type of reply.
  • port – The port number returned.
  • addr – Optional IP address returned.
classmethod loads(data: bytes) → socksio.socks4.SOCKS4Reply

Unpacks the reply data into an instance.

Returns:The unpacked reply instance.
Raises:ProtocolError – If the data does not match the spec.