hisock.utils#

A module containing some utility functions and classes.

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

class hisock.utils.ClientInfo(ip: tuple[str, int] | None, name: str | None = None, group: str | None = None)#

The dataclass used to represent a client.

as_dict() → dict#

Returns a dictionary represented by the ClientInfo. The dictionary will have the keys ip, name, group, and ipstr.

Returns:: A dictionary representing ClientInfo.
Return type:: dict

copy()#

Returns a copy of the current ClientInfo.

Returns:: A copy of the current ClientInfo.
Return type:: ClientInfo

classmethod from_dict(dict_: dict) → ClientInfo#

Creates a new ClientInfo instance given a dictionary. The dictionary should have the keys ip, name, and group.

Parameters:: dict (dict) – Dictionary that represents a new ClientInfo to be created from.
Returns:: a new instance of ClientInfo.
Return type:: ClientInfo

property ipstr: str#: A stringified version of self.ip. Is equivalent to f"{self.ip[0]}:{self.ip[1]}.

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.