hisock.client#

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

class hisock.client.HiSockClient(addr: tuple[str, int], name: str | None = None, group: str | None = None, header_len: int = 16, cache_size: int = -1)#

The client class for HiSock.

Parameters:

addr (tuple) – A two-element tuple, containing the IP address and the port number of where the server is hosted. Only IPv4 is 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).
header_len (int, optional) – An integer defining the header length of every message. A larger header length would mean a larger maximum message length (about 10**header_len). MUST be the same header length as the server, or else it will crash (hard to debug too!). Default sets to 16 (maximum length of content: 10 quadrillion bytes).
cache_size (int, optional) – The size of the message cache. -1 or below for no message cache, 0 for an unlimited cache size, and any other number for the cache size.

Variables:

addr (tuple) – A two-element tuple containing the IP address and the port number of the server.
header_len (int) – An integer storing the header length of each “message”.
name (str) – A string representing the name of the client to identify by. Default is None.
group (str) – A string representing the group of the client to identify by. Default is None.
funcs (dict) – A list of functions registered with decorator on(). This is mainly used for under-the-hood-code.
connect_time (int) – An integer sotring the Unix timestamp of when the client connected to the server.

change_group(new_group: str | None)#

Changes the client’s group.

Parameters:: new_group (Union[str, None]) – The new group name for the client to be called. if left blank, then the group will be reset

change_name(new_name: str | None)#

Changes the name of the client

Parameters:: new_name (Union[str, None]) – The new name for the client to be called. If left blank, then the name will be reset.

close(emit_leave: bool = True)#

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

Parameters:: emit_leave (bool) – Decides if the client will emit leave to the server or not

get_cache(idx: int | slice | None = None) → list[MessageCacheMember]#

Gets the message cache.

Parameters:: idx (Union[int, slice], optional) – An integer or slice, specifying what specific message caches to return. Default is None (retrieves the entire cache).
Returns:: A list of dictionaries, representing the cache
Return type:: list[dict]

get_client(client: tuple[str, int] | str) → ClientInfo#

Gets the client data for a client.

Parameters:

client (Client) – The client name or IP+port to get.

Returns:

The client data.

Return type:

Union[ClientInfo, dict]

Raises:

ValueError – If the client IP is invalid.
ClientNotFound – If the client couldn’t be found.
ServerException – If another error occurred.

get_client_addr() → tuple[str, int]#

Gets the address of the client.

Returns:: A tuple, with the format (IP, port).
Return type:: tuple[str, int]

get_server_addr() → tuple[str, int]#

Gets the address of where the client is connected to.

Returns:: A tuple, with the format (str IP, int port)
Return type:: tuple[str, int]

on(command: str, threaded: bool = False, override: bool = False) → Callable#

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, and they are:

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 unreserved functions get the message passed in.

Changed in version 3.0: Manual type casting has been removed in favor of automatic type casting. This means that annotations now do not matter in the context of how data will be manipulated, and that supported datatypes should automatically be casted to and from bytes.

For more information, read the documentation for type casting.

Parameters:

command (str) – A string, representing the command the function should activate when receiving it.
threaded (bool, optional) – A boolean, representing if the function should be run in a thread in order to not block the update loop. Default is False.
override (bool, optional) – A boolean representing if the function should override the reserved function with the same name and to treat it as an unreserved function. Default is False.

Returns:

The same function (the decorator just appended the function to a stack).

Return type:

function

Raises:

TypeError – If the number of function arguments is invalid.

Sends a command & content to the server.

Parameters:

command (str) – A string, containing the command to send
content (Sendable, optional) – The message / content to send

start(callback: Callable | None = None, error_handler: Callable | None = None)#

Start the main loop for the client.

Parameters:

callback (Callable, optional) – A function that will be called every time the client receives and handles a message.
error_handler (Callable, optional) – A function that will be called every time the client encounters an error.

class hisock.client.ThreadedHiSockClient(*args, **kwargs)#

HiSockClient, but running in its own thread as to not block the main loop. Please note that while this is running in its own thread, the event handlers will still be running in the main thread. To avoid this, use the threaded=True argument for the on decorator.

For documentation purposes, see HiSockClient.

start(callback: Callable | None = None, error_handler: Callable | None = None)#: Starts the main client loop. For documentation, see HiSockClient.start().

close(*args, **kwargs)#: Closes the client. Blocks the thread until the client is closed. For documentation, see HiSockClient.close().

hisock.client.connect(addr, name=None, group=None, header_len=16, cache_size=-1)#

Creates a HiSockClient instance. See HiSockClient for more details

Parameters:

addr (tuple) – A two-element tuple containing the IP address and the port number of the server.
name (str, optional) – A string containing the name of what the client should go by. This argument is optional.
group (str, optional) – A string, containing the “group” the client is in. Groups can be utilized to send specific messages to them only. This argument is optional.
header_len (int, optional) – An integer defining the header length of every message. Default is True.
cache_size (int, optional) – The size of the message cache. -1 or below for no message cache, 0 for an unlimited cache size, and any other number for the cache size.

Returns:

A HiSockClient instance.

Return type:

instance

Note

A simple way to use this function is to use utils.input_client_config() which will ask you for the server IP, port, name, and group. Then, you can call this function by simply doing connect(*input_client_config())

hisock.client.threaded_connect(*args, **kwargs)#: Creates a ThreadedHiSockClient instance. See ThreadedHiSockClient for more details :return: A ThreadedHiSockClient instance