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: str | bytes, header_len: int, encode=True) str | bytes #
Makes a header of
header_message
, with a maximum header length ofheader_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) 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: 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: str | None = 'Enter name: ', group_prompt: str | None = 'Enter group to connect to: ') tuple[tuple[str, int], str | None, str | None] #
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.