Package: gruv-socks
gruv-socksThis script provides a simple to use base server class and a Socket object that abstracts away the needed work to transport and recieve messages over TCP.NOTE: The method used to reconstruct fragments does not work with protocols such as HTTP. This is designed to be used with simple self designed protocols.Installationpip install gruv_socksUsageSimple examples to show you how the library can be used.Test Installfromgruv_socks.gruv_socksimportserver_testprint(server_test())b"If you see this message, that means gruv_socks is working!"Create Echo ServerThis script will create a server that listens for data from clients, sends it back, then closes the connection. It will continue to run until stopped withCtrl+Cdue to theblocking=Trueparameter in line 14. The deconstructor of the Socket object ensures it is properly closed, so you do not need to explicitly call it unless needed.fromgruv_socks.gruv_socksimportServerBase,SOCK_ERROR,SOCK_TIMEOUTdefcallback(addr,sock):status,data=sock.read()# receive read status, and received data# exit if read failedifstatusisFalseanddata==SOCK_ERROR:print("client error")returnelifstatusisFalseanddata==SOCK_TIMEOUT:print("client timeout")returnsock.write(data)# send data back to clientprint(f"{addr[0]}said:{data.decode()}")defmain():server=ServerBase()server.start(callback,5551,blocking=True)if__name__=="__main__":main()Create Echo ClientThis script will connect to the server running from the above script, send the text "Hello world!" disconnect, and then exit.fromgruv_socks.gruv_socksimportSocketdefmain():sock=Socket()sock.connect("localhost",5551)sock.write("Hello world!")# NOTE: Socket + str/bytes [sock + "foo"] is valid shorthand for sock.write()print(sock.read()[1])sock.disconnect()if__name__=="__main__":main()Items ProvidedA breakdown of the provided functions, objects, and variables.Variable: SOCK_ERRORUse to determine if a socket encountered an error.Variable: SOCK_TIMEOUTUse to determine if a socket encountered a time out.Function: echo_callback(addr: tuple[str, int], sock: Socket)Simple callback function to create an echo server with the ServerBase object.Function: server_test()Direct call function to test the BaseServer and Socket objects locally on the machine running it to ensure the library is working.Object: SocketSocket.timeout: intTimeout (in seconds) to use for socket operations.Socket.debug: boolDecides if stack trace information is printed to console or not.Socket.__sock: socket.socketHolds the underlying socket object that communication is preformed with.Socket.__init__(self, sock=None, timeout: int=60, debug: bool=False)sock: Existing socket to use if supplied.timeout: Time to wait (in seconds) for certain socket operations before stopping. I.e. connecting, reading data.debug: If set to true, the stack trace will be printed to console upon errors for debugging.Socket.__str__(self) -> strdef__str__(self)->str:returnf"gruv_socks.Socket(timeout={self.timeout}, debug={self.debug})"Socket.__add__(self, x: bytes) -> boolShorthand for Socket.write()def__add__(self,x:bytes)->bool:returnself.write(x)Usagefromgruv_socks.gruv_socksimportSocketsock=Socket()sock.connect("localhost",5551)sock+b"Hello world!"Socket.connect(self, host: str, port: int) -> boolAttempts to establish a connection to a given host. Returns bool dictating status.host: Hostname/Address of host to connect to.port: Port on the given host to connect to.Socket.read(self, timeout_override: int=0) -> tuple[bool, bytes]Attempts to read data from the socket object.Returns a tuple containing a boolean dictating success status, and then the received data in byte string.
If the status is False, then either gruv_socks.SOCK_ERROR, or gruv_socks.SOCK_TIMEOUT will be returned as the data.timeout_override: If not 0, then overrides the set timeout for this singular read call.Socket.write(self, data: bytes or str) -> boolAttempts to write data to socket object, sending it to the connected host. Returns boolean dictating status.data: Data to send to connected host.Socket.disconnect(self)Properly disconnects the socket object by shutting down READ/WRITE channels, and then closing the socket.Socket.__del__(self)Socket destructor, ensures the socket object properly closes before being destroyed.Object:ServerBaseServerBase.__init__(self, debug: bool=False)Initializes the ServerBase object.debug: Decides if stack trace information is printed to console or not.ServerBase.__listen(self, callback)Listens for incoming connections and hands them off to the callback function supplied.ServerBase.start(self, callback, port: int, address: str="0.0.0.0", blocking: bool = False)Makes the server listen with the given configuration.The callback function is supplied 2 arguments. The first is a tuple of the remote IP, and the remote port.
The second argument is the Socket object of the remote connection.callback: Callback function to trigger upon new connections.
callback( (host: str, port: int), Socket )port: Port to listen on.address: Address to listen on.blocking: Boolean dictating wether or not this function should block, or spawn a thread to listen.ServerBase.stop(self)Stops the server by shutting down the listening socket and triggering the background thread to stop.ServerBase.__del__(self)Ensures the listening socket is properly closed, and the listening thread exits gracefully.