Metadata-Version: 2.1
Name: gruv-socks
Version: 0.9.8
Summary: Easy to use standard for abstracting the work needed to transport and reconstruct messages over TCP.
Home-page: https://github.com/ForestJ2/gruv_socks
Author: Forest Jacobsen
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3.9
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown

# gruv-socks

This 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.

## Installation
`pip install gruv_socks`

## Usage
Simple examples to show you how the library can be used.

### Test Install

```py
from gruv_socks.gruv_socks import server_test

print(server_test())
b"If you see this message, that means gruv_socks is working!"
```

### Create Echo Server
This 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 with `Ctrl+C` due to the `blocking=True` parameter 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.

```py
from gruv_socks.gruv_socks import ServerBase, SOCK_ERROR, SOCK_TIMEOUT

def callback(addr, sock):
	status, data = sock.read()  # receive read status, and received data

	# exit if read failed
	if status is False and data == SOCK_ERROR:
		print("client error")
		return
	elif status is False and data == SOCK_TIMEOUT:
		print("client timeout")
		return

	sock.write(data)  # send data back to client
	print(f"{addr[0]} said: {data.decode()}")

def main():
	server = ServerBase()
	server.start(callback, 5551, blocking=True)

if __name__ == "__main__":
	main()
```

### Create Echo Client
This script will connect to the server running from the above script, send the text "Hello world!" disconnect, and then exit.

```py
from gruv_socks.gruv_socks import Socket

def main():
	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 Provided
A breakdown of the provided functions, objects, and variables.

### Variable: SOCK_ERROR
Use to determine if a socket encountered an error.

### Variable: SOCK_TIMEOUT
Use 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: Socket

#### Socket.timeout: int
Timeout (in seconds) to use for socket operations.

#### Socket.debug: bool
Decides if stack trace information is printed to console or not.

#### Socket.__sock: socket.socket
Holds 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) -> str
```py
def __str__(self) -> str:
    return f"gruv_socks.Socket(timeout={self.timeout}, debug={self.debug})"
```

#### Socket.\_\_add__(self, x: bytes) -> bool
Shorthand for Socket.write()

```py
def __add__(self, x: bytes) -> bool:
    return self.write(x)
```

Usage

```py
from gruv_socks.gruv_socks import Socket

sock = Socket()
sock.connect("localhost", 5551)
sock + b"Hello world!"
```

#### Socket.connect(self, host: str, port: int) -> bool
Attempts 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) -> bool
Attempts 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:ServerBase

#### ServerBase.\_\_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.

