oon 0.0.5

Package for simplify classes and objects transfer over network

OON

Objects Over Network protocol

OON - module for python, which allows you to quickly and conveniently transfer objects of python classes over network

install:

install python oon module with pip:

pip3 install oon

usage:

OON is able to automaticly convert objects of your custom classes to dicts and strings and to form network message for transfering it

It can act like a server or a client depends on what you need

For example let's assume your python programs with some data related to cars and you have sepparate file cars.py with classes for different cars:

################# cars.py ###################
import enum
class CarMark(enum.Enum):
    Volvo = 0
    Toyota = 1
    Ford = 2

class Car:
    mark : CarMark = None
    speed : int = None

class TrucTrailer:
    car_inside : Car = None
    car_count : int = None

class Truc(Car):
    trailer : TrucTrailer = None

class VolvoCar(Car):
    __slots__ = ['wheels']
    mark = CarMark.Volvo
    def __init__(self, speed = 10, wheels = 4):
        self.speed = speed
        self.wheels = wheels
    def show_info(self):
        print(f"VolvoCar\n wheels:{self.wheels} speed:{self.speed}, mark:{self.mark}")

class FordTruck(Truc):
    mark = CarMark.Ford
    def __init__(self, speed = 10, car : Car = None, count = 0):
        self.trailer = TrucTrailer()
        self.speed = speed
        self.trailer.car_inside = car
        self.trailer.car_count = count
    def show_info(self):
        print(f"FordTruck\n speed:{self.speed}, mark:{self.mark}, cars inside trailer:{self.trailer.car_count}")
        print(f"car inside trailer info:")
        self.trailer.car_inside.show_info()

So you also have main.py file where all other work done:

################# main.py ###################
import cars    #import file with all classes defenitions

my_car = cars.VolvoCar(speed=35, wheels=4)
my_truck = cars.FordTruck(speed=20, car=my_car, count=1)
print("\n")
my_truck.show_info()   #show info about car
print("\n")

Now you want to transfer my_truck object to other host. Let's assume this side will be server and other - client

To do this - just import oon and turn it on with server mode, wait for client connection and send your my_truck object:

Note: ALL FIELDS IN YOUR CLASSES MUST HAVE DEFAULT VALUES

also fields of type list, dict, tuple which contain several objects of other classes does not supported YET

################# new main.py - now server side ###################
import oon     #import objects over network protocol
import cars

my_car = cars.VolvoCar(speed=35, wheels=4)
my_truck = cars.FordTruck(speed=20, car=my_car, count=1)
print("\n")
my_truck.show_info()
print("\n")

exitcode = oon.turn_on(modules=[cars], is_server=True)   #turn on oon - returns ExCode
if exitcode != oon.ExCode.Success:
    print(f"failed to start server! {exitcode}")
    exit(1)

client, exitcode = oon.accept_net_connection()   #wait for client connection - returns object of _NetClient
print(f"client with ip {client.addr}")
if exitcode != oon.ExCode.Success:
    print(f"something wrong with connection or timeouted! {exitcode}")
    exit(1)

netmessage, exitcode = oon.generate_net_message(my_truck)   #generate network message from your object - returns _NetMessage and ExCode
if exitcode != oon.ExCode.Success:
    print(f"failed to generate network message! {exitcode}")

exitcode = oon.send_data(netmessage, client)    #send generated message - returns ExCode
if exitcode != oon.ExCode.Success:
    print(f"failed to transfer data! {exitcode}")

oon.close_client_connection(client)    # close connection with client
client = None
exitcode = oon.turn_off()      #turn server off
if exitcode == oon.ExCode.Success:
    print("server is off")
else: print("failed to stop server")

now you can create client.py which will be client (it also needs cars.py file):

################# client.py ###################
import oon
import cars

exitcode = oon.turn_on(modules=[cars], is_server=False)

if exitcode != oon.ExCode.Success:
    print(f"failed to start client! {exitcode}")
    exit(1)

exitcode = oon.connect_to_srv()
if exitcode != oon.ExCode.Success:
    print(f"failed to connect to srv! {exitcode}")
    exit(1)

netmessage, exitcode = oon.receive_data(bytes=1024)
car = netmessage.netobj
print("\n")
car.show_info()
print("\n")

now to test - start python main.py and python client.py

on server:

FordTruck
 speed:20, mark:CarMark.Ford, cars inside trailer:1
car inside trailer info:
VolvoCar
wheels:4 speed:35, mark:CarMark.Volvo


client with ip 127.0.0.1
server is off

on client:

FordTruck
 speed:20, mark:CarMark.Ford, cars inside trailer:1
car inside trailer info:
VolvoCar
wheels:4 speed:35, mark:CarMark.Volvo

docs:

info about all supported data types, all available functions, returns and objects:

all functions:

Function	Parameters	Purpose	Condition to Use	Return
turn_on()	modules : list - list of modules with your custom classes, classes : list - list of your custom unit classes which aren't located in your modules, is_server : bool - start as server or as client, ip : str - ip, port : int - port, encoding : str - what encoding to use, timeout : int - timeout of future operations, queue_size : int - size of connections in queue	start oon	if not started	ExCode.Success or ExCode.StartFail
turn_off()	no	turn off oon	if started and if no clients active if in server mode	ExCode.Success or ExCode.StopFail If StopFail on server mode - maybe some clients are still active, close them before stopping
accept_net_connection()	client_timeout : int - timeout of future operations with client connection	wait for client connection until timeout	if started in server mode	(_NetClient, ExCode.Success) - if all ok (None, ExCode.BadConn) - if something wrong with listening socket (None, ExCode.Timeout) - if timeouted (None, ExCode.StartFail) - if you forgot to start oon
close_client_connection()	client : _NetClient - client	close connection with client	if started in server mode	(_NetClient, ExCode.Success) - if all ok (None, ExCode.BadConn) - if something wrong with client (None, ExCode.StartFail) - if you forgot to start oon
connect_to_srv()	no	connect to server	if started in client mode and not connected	ExCode.Success - if all ok ExCode.BadConn - if something wrong with connection, or already connected ExCode.Timeout - if timeouted ExCode.StartFail - if you forgot to start oon
disconnect_from_srv()	no	disconnect from server	if started in client mode and connected	ExCode.Success - if all ok ExCode.BadConn - if something wrong with connection, or already disconnected ExCode.Timeout - if timeouted ExCode.StartFail - if you forgot to start oon
generate_net_message()	netobj : Any - object you want to transfer, fields_to_ignore : list - what fileds of object you don't want to transfer, uuid : str - generated if nothing specified	generate network message	if started	(_NetMessage, ExCode.Success) - if all ok (_NetMessage, ExCode.BadData) - if your objects does not meet the requirements (None, ExCode.StartFail) - if you forgot to start oon
load_net_message_from_str()	messtr : str - json string, fields_to_ignore : list - field not to load from string	load network message from it's json string variant. Uses automatically inside receive_data() method	if started	(_NetMessage, ExCode.Success) - if all ok (_NetMessage, ExCode.BadData) - if something wrong with json string or with your classes in your module (None, ExCode.StartFail) - if you forgot to start oon
receive_data()	bytes : int - size of message to expect, client : _NetClient - client. Only if started in server mode!	receive data from client or server	if started. If in client mode, needs to be connected to server	(_NetMessage, ExCode.Success) - if all ok (_NetMessage, ExCode.BadData) - if failed to load_net_message_from_str() (None, ExCode.BadConn) - if something wrong with connection (None, ExCode.Timeout) - if timeouted (None, ExCode.StartFail) - if you forgot to start oon
send_data()	netmessage : _NetMessage - generated network message, client : _NetClient - client. Only if started in server mode!	send data to client or server	if started. If in client mode, needs to be connected to server	ExCode.Success - if all ok ExCode.BadData - if you give strange data ExCode.BadConn - if something wrong with client ExCode.Timeout - if timeouted ExCode.StartFail - if you forgot to start oon
is_running()	no	get info about oon status	no	True - running False - not running
is_connected()	no	get info about connect status (Does not tell info about other side connection state!)	if started in client mode	True - connected False - not connected

all objects:

_NetMessage (message for transfering between hosts):

Field	Purpose
create_code : ExCode	signals if object created as expected. This field returns as exitcode of related functions when generating or loading message
json_string : str	message in json string form, this is data that is actually being transferred
netobj : Any	actual object from your custom module
uuid : str	uuid of message

_NetClient (container for all data related to client connection):

Field	Purpose
alive : Bool	if connection wasn't closed manually.This field does not reflect the connection status at the other end
socket : socket.socket	clisent connection socket
addr : str	ip
port : int	port
uuid : str	uuid

usefull info:

ExCode.BadConn in most cases means that connection was closed by other side, or you are transmitting wrong data to the function

Every function argument has default value. You can change it.

Note: this module was originally developed as part of a NAM project - https://github.com/Ivashkka/nam