lib.network

* ATTENTION: This is early work in progress. Interfaces are subject to change. *
* DO NOT USE IN PRODUCTION until you know what you are doing *
* This library is foreseen for SHNG v1.6 release *

This library contains the future network classes for SmartHomeNG.

New network functions and utilities are going to be implemented in this library. This classes, functions and methods are mainly meant to be used by plugin developers

class lib.network.Network[source]

Bases: object

This Class has some usefull static methods that you can use in your projects

static is_mac(mac)[source]

Validates a MAC address

Parameters:mac – MAC address
Returns:True if value is a MAC
Return type:bool
static is_ip(string)[source]

Checks if a string is a valid ip-address (v4 or v6)

Parameters:string (str) – String to check
Returns:True if an ip, false otherwise.
Return type:bool
static is_ipv4(string)[source]

Checks if a string is a valid ip-address (v4)

Parameters:string (str) – String to check
Returns:True if an ip, false otherwise.
Return type:bool
static is_ipv6(string)[source]

Checks if a string is a valid ip-address (v6)

Parameters:string (str) – String to check
Returns:True if an ipv6, false otherwise.
Return type:bool
static is_hostname(string)[source]

Checks if a string is a valid hostname

The hostname has is checked to have a valid format

Parameters:string (str) – String to check
Returns:True if a hostname, false otherwise.
Return type:bool
static get_local_ipv4_address()[source]

Get’s local ipv4 address of the interface with the default gateway. Return ‘127.0.0.1’ if no suitable interface is found

Returns:IPv4 address as a string
Return type:string
static get_local_ipv6_address()[source]

Get’s local ipv6 address of the interface with the default gateway. Return ‘::1’ if no suitable interface is found

Returns:IPv6 address as a string
Return type:string
static ip_port_to_socket(ip, port)[source]

Returns an ip address plus port to a socket string. Format is ‘ip:port’ for IPv4 or ‘[ip]:port’ for IPv6

Returns:Socket address / IPEndPoint as string
Return type:string
static ipver_to_string(ipver)[source]

Converts a socket address family to an ip version string ‘IPv4’ or ‘IPv6’

Parameters:ipver (socket.AF_INET or socket.AF_INET6) – Socket family
Returns:‘IPv4’ or ‘IPv6’
Return type:string
class lib.network.Http(baseurl=None)[source]

Bases: object

Creates an instance of the Http class.

Parameters:baseurl (str) – base URL used everywhere in this instance (example: http://www.myserver.tld)
get_json(url=None, params=None)[source]

Launches a GET request and returns JSON answer as a dict or None on error.

Parameters:
  • url (str) – Optional URL to fetch from. If None (default) use baseurl given on init.
  • params (dict) – Optional dict of parameters to add to URL query string.
Returns:

JSON answer decoded into a dict or None on whatever error occured

Return type:

dict | None

get_text(url=None, params=None, encoding=None, timeout=None)[source]

Launches a GET request and returns answer as string or None on error.

Parameters:
  • url (str) – Optional URL to fetch from. Default is to use baseurl given to constructor.
  • params (dict) – Optional dict of parameters to add to URL query string.
  • encoding (str) – Optional encoding of the received text. Default is to let the lib try to figure out the right encoding.
Returns:

Answer decoded into a string or None on whatever error occured

Return type:

str | None

get_binary(url=None, params=None)[source]

Launches a GET request and returns answer as raw binary data or None on error. This is usefull for downloading binary objects / files.

Parameters:
  • url (str) – Optional URL to fetch from. Default is to use baseurl given to constructor.
  • params (dict) – Optional dict of parameters to add to URL query string.
Returns:

Answer as raw binary objector None on whatever error occured

Return type:

bytes | None

response_status()[source]

Returns the status code (200, 404, …) of the last executed request. If GET request was not possible and thus no HTTP statuscode is available the returned status code = 0.

Returns:Status code and text of last request
Return type:(int, str)
response_headers()[source]

Returns a dictionary with the server return headers of the last executed request

Returns:Headers returned by server
Return type:dict
response_cookies()[source]

Returns a dictionary with the cookies the server may have sent on the last executed request

Returns:Cookies returned by server
Return type:dict
response_object()[source]

Returns the raw response object for advanced ussage. Use if you know what you are doing. Maybe this lib can be extented to your needs instead ?

Returns:Reponse object as returned by underlying requests library
Return type:requests.Response
class lib.network.Tcp_client(host, port, name=None, autoreconnect=True, connect_retries=5, connect_cycle=5, retry_cycle=30, binary=False, terminator=False)[source]

Bases: object

Creates a new instance of the Tcp_client class

Parameters:
  • host (str) – Remote host name or ip address (v4 or v6)
  • port (int) – Remote host port to connect to
  • name (str) – Name of this connection (mainly for logging purposes). Try to keep the name short.
  • autoreconnect (bool) – Should the socket try to reconnect on lost connection (or finished connect cycle)
  • connect_retries (int) – Number of connect retries per cycle
  • connect_cycle (int) – Time between retries inside a connect cycle
  • retry_cycle (int) – Time between cycles if :param:autoreconnect is True
  • binary (bool) – Switch between binary and text mode. Text will be encoded / decoded using encoding parameter.
  • terminator (int | bytes | str) – Terminator to use to split received data into chunks (split lines <cr> for example). If integer then split into n bytes. Default is None means process chunks as received.
set_callbacks(connected=None, receiving=None, data_received=None, disconnected=None)[source]

Set callbacks to caller for different socket events

Parameters:
  • connected (function) – Called whenever a connection is established successfully
  • data_received (function) – Called when data is received
  • disconnected (function) – Called when a connection has been dropped for whatever reason
connect()[source]

Connects the socket

Returns:False if an error prevented us from launching a connection thread. True if a connection thread has been started.
Return type:bool
connected()[source]

Returns the current connection state

Returns:True if an active connection exists,else False.
Return type:bool
send(message)[source]

Sends a message to the server. Can be a string, bytes or a bytes array.

Returns:True if message has been successfully sent, else False.
Return type:bool
close()[source]

Closes the current client socket

class lib.network.Tcp_server(port, interface='', name=None, mode=3, terminator=None)[source]

Bases: object

Creates a new instance of the Tcp_server class

Parameters:
  • interface (str) – Remote interface name or ip address (v4 or v6). Default is ‘::’ which listens on all IPv4 and all IPv6 addresses available.
  • port (int) – Remote interface port to connect to
  • name (str) – Name of this connection (mainly for logging purposes)
MODE_TEXT = 1
MODE_TEXT_LINE = 2
MODE_BINARY = 3
MODE_FIXED_LENGTH = 4
set_callbacks(listening=None, incoming_connection=None, disconnected=None, data_received=None)[source]

Set callbacks to caller for different socket events

Parameters:
  • connected (function) – Called whenever a connection is established successfully
  • data_received (function) – Called when data is received
  • disconnected (function) – Called when a connection has been dropped for whatever reason
start()[source]

Start the server socket

Returns:False if an error prevented us from launching a connection thread. True if a connection thread has been started.
Return type:bool
listening()[source]

Returns the current listening state

Returns:True if the server socket is actually listening, else False.
Return type:bool
send(client, msg)[source]

Send a string to connected client

Parameters:
  • client (network.Client) – Client Object to send message to
  • msg (string | bytes | bytearray) – Message to send
Returns:

True if message has been queued successfully.

Return type:

bool

disconnect(client)[source]

Disconnects a specific client

Parameters:client (network.Client) – Client Object to disconnect
close()[source]

Closes running listening socket