API Reference¶

hisock.server¶

A module containing the main server classes and functions, including HiSockServer and start_server()

Note

Header lengths usually should not be that long; on average, header lengths are about 64 bytes long, which is more than enough for most cases (10 vigintillion, 10**64). Plus, a release is planned for hisock that utilizes ints to bump the header utilization from 10**x to 2**(7x) (where x is the header length)

class server.HiSockServer(addr: tuple[str, int], blocking: bool = True, max_connections: int = 0, header_len: int = 16, tls: Union[dict, str] = None)¶

The server class for hisock HiSockServer offers a neater way to send and receive data than sockets. You don’t need to worry about headers now, yay!

Parameters

addr (tuple) – A two-element tuple, containing the IP address and the port number of where the server should be hosted. Due to the nature of reserved ports, it is recommended to host the server with a port number that’s higher than 1023. Only IPv4 currently supported
blocking (bool, optional) – A boolean, set to whether the server should block the loop while waiting for message or not. Default passed in by start_server() is True
max_connections (int, optional) – The number of maximum connections HiSockServer should accept, before refusing clients’ connections. Pass in 0 for unlimited connections. Default passed in by start_server() is 0
header_len (int, optional) – An integer, defining the header length of every message. A smaller header length would mean a smaller maximum message length (about 10**header_len). Any client connecting MUST have the same header length as the server, or else it will crash. Default passed in by start_server() is 16 (maximum length: 10 quadrillion bytes)

get_addr()¶

Gets the address of where the hisock server is serving at.

Returns: A tuple, with the format (str IP, int port)

get_all_clients(key: Optional[Union[Callable, str]] = None)¶

Get all clients currently connected to the server. This is recommended over the class attribute self._clients or self.clients_rev, as it is in a dictionary-like format

Parameters: key (Union[Callable, str], optional) – If specified, there are two outcomes: If it is a string, it will search for the dictionary for the key, and output it to a list (currently support “ip”, “name”, “group”). Finally, if it is a callable, it will try to integrate the callable into the output (CURRENTLY NOT SUPPORTED YET)
Returns: A list of dictionaries, with the clients
Return type: list[dict, …]

get_client(client: Union[str, tuple[str, int]])¶

Gets a specific client’s information, based on either:

The client name
The client IP+Port
The client IP+Port, in a 2-element tuple

Parameters

client (Union[str, tuple]) – A parameter, representing the specific client to look up. As shown above, it can either be represented as a string, or as a tuple.

Raises

ValueError – Client argument is invalid
TypeError – Client does not exist

Returns

A dictionary of the client’s info, including IP+Port, Name, Group, and Socket

Return type

dict

get_group(group: str)¶

Gets all clients from a specific group

Parameters: group (str) – A string, representing the group to look up
Raises: TypeError – Group does not exist
Returns: A list of dictionaries of clients in that group, containing the address, name, group, and socket
Return type: list

on(command: str)¶

A decorator that adds a function that gets called when the server receives a matching command

Reserved functions are functions that get activated on specific events. Currently, there are 3 for HiSockServer:

join - Activated when a client connects to the server
leave - Activated when a client disconnects from the server
message - Activated when a client messages to the server

The parameters of the function depend on the command to listen. For example, reserved commands join and leave have only one client parameter passed, while reserved command message has two: Client Data, and Message. Other nonreserved functions will also be passed in the same parameters as message

In addition, certain type casting is available to nonreserved functions. That means, that, using type hints, you can automatically convert between needed instances. The type casting currently supports:

bytes -> int (Will raise exception if bytes is not numerical)
bytes -> str (Will raise exception if there’s a unicode error)

Type casting for reserved commands is scheduled to be implemented, and is currently being worked on.

Parameters: command (str) – A string, representing the command the function should activate when receiving it
Returns: The same function (The decorator just appended the function to a stack)
Return type: function

run()¶: Runs the server. This method handles the sending and receiving of data, so it should be run once every iteration of a while loop, as to not lose valuable information

Note

This is the main method to run HiSockServer. This MUST be called every iteration in a while loop, as to keep waiting time as short as possible between client and server. It is also recommended to put this in a thread.

send_all_clients(command: str, content: bytes)¶

Sends the commmand and content to ALL clients connected

Parameters

command (str) – A string, representing the command to send to every client
content (bytes) – A bytes-like object, containing the message/content to send to each client

send_client(client: Union[str, tuple], command: str, content: bytes)¶

Sends data to a specific client. Different formats of the client is supported. It can be:

An IP + Port format, written as “ip:port”
A client name, if it exists

Parameters

client (Union[str, tuple]) – The client to send data to. The format could be either by IP+Port, or a client name
command (str) – A string, containing the command to send
content (bytes) – A bytes-like object, with the content/message to send

Raises

ValueError – Client format is wrong
TypeError – Client does not exist
Warning – Using client name, and more than one client with the same name is detected

send_client_raw(client, content: bytes)¶

Sends data to a specific client, without a command Different formats of the client is supported. It can be:

An IP + Port format, written as “ip:port”
A client name, if it exists

Parameters

client (Union[str, tuple]) – The client to send data to. The format could be either by IP+Port, or a client name
content (bytes) – A bytes-like object, with the content/message to send

Raises

ValueError – Client format is wrong
TypeError – Client does not exist
Warning – Using client name and more than one client with the same name is detected

send_group(group: str, command: str, content: bytes)¶

Sends data to a specific group. Groups are recommended for more complicated servers or multipurpose servers, as it allows clients to be divided, which allows clients to be sent different data for different purposes.

Parameters

group (str) – A string, representing the group to send data to
command (str) – A string, containing the command to send
content (bytes) – A bytes-like object, with the content/message to send

Raises

TypeError – The group does not exist

send_group_raw(group: str, content: bytes)¶

Sends data to a specific group, without commands. Groups are recommended for more complicated servers or multipurpose servers, as it allows clients to be divided, which allows clients to be sent different data for different purposes.

Non-command-attached content is recommended to be used alongside with HiSockClient.recv_raw()

Parameters

group (str) – A string, representing the group to send data to
content (bytes) – A bytes-like object, with the content/message to send

Raises

TypeError – The group does not exist

hisock.client¶

A module containing the main client classes and functions, including HiSockClient and connect()

class client.HiSockClient(addr: tuple[str, int], name: Union[str, None], group: Union[str, None], blocking: bool = True, header_len: int = 16)¶

The client class for hisock. HiSockClient offers a higher-level version of sockets. No need to worry about headers now, yay! HiSockClient also utilizes decorators to receive messages, as an easy way of organizing your code structure (methods are provided, like recv_raw(), of course)

Parameters

addr (tuple) – A two-element tuple, containing the IP address and the port number of the server wishing to connect to Only IPv4 currently supported
name (str, optional) –
Either a string or NoneType, representing the name the client goes by. Having a name provides an easy interface of sending data to a specific client and identifying clients. It is therefore highly recommended to pass in a name

Pass in NoneType for no name (connect should handle that)
group (str, optional) –
Either a string or NoneType, representing the group the client is in. Being in a group provides an easy interface of sending data to multiple specific clients, and identifying multiple clients. It is highly recommended to provide a group for complex servers

Pass in NoneType for no group (connect should handle that)
blocking (bool, optional) – A boolean, set to whether the client should block the loop while waiting for message or not. Default sets to True
header_len (int, optional) – An integer, defining the header length of every message. A smaller header length would mean a smaller maximum message length (about 10**header_len). The header length MUST be the same as the server connecting, or it will crash (hard to debug though). Default sets to 16 (maximum length of content: 10 quadrillion bytes)

close()¶: Closes the client; running client.update() won’t do anything now

on(command: str)¶

A decorator that adds a function that gets called when the client receives a matching command

Reserved functions are functions that get activated on specific events. Currently, there are 2 for HiSockClient:

client_connect - Activated when a client connects to the server
client_disconnect - Activated when a client disconnects from the server

The parameters of the function depend on the command to listen. For example, reserved functions client_connect and client_disconnect gets the client’s data passed in as an argument. All other nonreserved functions get the message passed in.

bytes -> int (Will raise exception if bytes is not numerical)
bytes -> str (Will raise exception if there’s a unicode error)

Type casting for reserved commands is scheduled to be implemented, and is currently being worked on.

Parameters: command (str) – A string, representing the command the function should activate when receiving it
Returns: The same function (The decorator just appended the function to a stack
Return type: function

raw_send(content: bytes)¶

Sends a message to the server: NO COMMAND REQUIRED. This is preferable in some situations, where clients need to send multiple data over the server, without overcomplicating it with commands

Parameters: content (bytes) – A bytes-like object, with the content/message to send

recv_raw()¶

Waits (blocks) until a message is sent, and returns that message. This is not recommended for content with commands attached; it is meant to be used alongside with HiSockServer.send_client_raw() and HiSockServer.send_group_raw()

Returns: A bytes-like object, containing the content/message the client first receives
Return type: bytes

update()¶: Handles newly received messages, excluding the received messages for wait_recv This method must be called every iteration of a while loop, as to not lose valuable info. In some cases, it is recommended to run this in a thread, as to not block the program

Note

This is the main method to run HiSockClient. This MUST be called every iteration in a while loop, as to keep waiting time as short as possible between client and server. It is also recommended to put this in a thread.