hisock.utils#

A module containing some utilities to either:

1. Help hisock.client and hisock.server run (denoted with leading underscore) 1. Provide functions to use alongside HiSock

class hisock.utils.MessageCacheMember(message_dict: dict)#

class hisock.utils.ClientInfo(ip, name, group)#

hisock.utils.make_header(header_message: Union[str, bytes], header_len: int, encode=True) → Union[str, bytes]#

Makes a header of header_message, with a maximum header length of header_len

Parameters

header_message (Union[str, bytes]) – A string OR bytes-like object, representing the data to make a header from
header_len (int) – An integer, specifying the actual header length (will be padded)
encode – A boolean, specifying the

Returns

The constructed header, padded to header_len bytes

Return type

Union[str, bytes]

hisock.utils.receive_message(connection: socket.socket, header_len: int) → Union[dict[str, bytes], bool]#

Receives a message from a server or client.

Parameters

connection (socket.socket) – The socket to listen to for messages. MUST BE A SOCKET
header_len (int) – The length of the header, so that it can successfully retrieve data without loss/gain of data

Returns

A dictionary, with two key-value pairs; The first key-value pair refers to the header, while the second one refers to the actual data

Return type

Union[dict[“header”: bytes, “data”: bytes], False

hisock.utils.validate_command_not_reserved(command: str)#

Checks for illegal $cmd$ notation (used for reserved functions).

Parameters: command (str) – The command to check.
Raises: ValueError – If the command is reserved.

hisock.utils.validate_ipv4(ip: Union[str, tuple], require_ip: bool = True, require_port: bool = True) → bool#

Validates an IPv4 address. If the address isn’t valid, it will raise an exception. Otherwise, it’ll return True

Parameters

ip (Union[str, tuple]) – The IPv4 address to validate.
require_ip (bool) – Whether or not to require an IP address. If True, it will raise an exception if no IP address is given. If False, this will only check the port.
require_port (bool) – Whether or not to require a port to be specified. If True, it will raise an exception if no port is specified. If False, it will return the address as a tuple without a port.

Returns

True if there were no exceptions.

Return type

Literal[“True”]

Raises

ValueError – IP address is not valid

hisock.utils.get_local_ip(all_ips: bool = False) → str#

Gets the local IP of your device, with sockets

Parameters

all_ips (bool, optional) –

A boolean, specifying to return all the local IPs or not. If set to False (the default), it will return the local IP first found by socket.gethostbyname()

Default: False

Returns

A string containing the IP address, in the format “ip:port”

Return type

str

hisock.utils.input_server_config(ip_prompt: str = 'Enter the IP for the server: ', port_prompt: str = 'Enter the port for the server: ') → tuple[str, int]#

Provides a built-in way to obtain the IP and port of where the server should be hosted, through input().

Parameters

ip_prompt (str, optional) – A string, specifying the prompt to show when asking for IP.
port_prompt (str, optional) – A string, specifying the prompt to show when asking for port

Returns

A two-element tuple, consisting of IP and port.

Return type

tuple[str, int]

hisock.utils.input_client_config(ip_prompt: str = 'Enter the IP of the server: ', port_prompt: str = 'Enter the port of the server: ', name_prompt: Union[str, None] = 'Enter name: ', group_prompt: Union[str, None] = 'Enter group to connect to: ') → tuple[tuple[str, int], Optional[str], Optional[str]]#

Provides a built-in way to obtain the IP and port of the configuration of the server to connect to.

Parameters

ip_prompt (str, optional) – A string, specifying the prompt to show when asking for IP.
port_prompt (str, optional) – A string, specifying the prompt to show when asking for port.
name_prompt (Union[str, None], optional) – A string, specifying the prompt to show when asking for client name.
group_prompt (Union[str, None], optional) – A string, specifying the prompt to show when asking for client group.

Returns

A tuple containing the config options of the server. Will filter out the unused options.

Return type

tuple[str, int, Optional[str], Optional[int]]

hisock.utils.ipstr_to_tup(formatted_ip: str) → tuple[str, int]#

Converts a string IP address into a tuple equivalent.

Parameters: formatted_ip (str) – A string, representing the IP address. Must be in the format “ip:port”.
Returns: A tuple, with a string IP address as the first element and an integer port as the second element.
Return type: tuple[str, int]
Raises: ValueError – If the IP address isn’t in the “ip:port” format.

hisock.utils.iptup_to_str(formatted_tuple: tuple[str, int]) → str#

Converts a tuple IP address into a string equivalent. This function is the opposite of ipstr_to_tup().

Parameters: formatted_tuple (tuple[str, int]) – A two-element tuple, containing the IP address and the port. Must be in the format (ip: str, port: int).
Returns: A string, with the format “ip:port”.
Return type: str
Raises: ValueError – If the IP address isn’t in the “ip:port” format.