Python module one line socket comm.

Overview

PyPi module https://pypi.org/project/socket-oneline.html
git repository https://bitbucket.org/arrizza-public/socket-oneline
git command git clone git@bitbucket.org:arrizza-public/socket-oneline.git
Verification Report https://arrizza.com/web-ver/python-socket-oneline-report.html
Version Info
  • macOS 14.2.1, Python 3.10
  • macOS 14.5, Python 3.10
  • Ubuntu 20.04 focal, Python 3.10
  • Ubuntu 22.04 jammy, Python 3.10
  • win32 Windows 10, Python 3.10

Summary

This module contains a simple base class for handling sockets

The communication protocol has these basic rules:

  • socket based using TCPIP; only one server per port
  • only one client connected at any time. When that client disconnects, another client is allowed to connect.
  • a "packet" is terminated by a line feed (0x0A).
  • a client sends a packet (aka "command") to the server.
  • Alternatively the server may respond with zero, one or more packets (aka "responses")
  • The server cannot initiate a response asynchronously by itself i.e. it must wait for an incoming command to send any packets to the client.
  • the following commands are predefined:
    • "ping" : the server will respond with "pong". The client can use this to confirm that the socket and communication channel are alive and responsive
    • "disconnect" : the server will initiate a disconnect from the current client
    • "shutdown" : the server will disconnect and then shutdown
    • "invalid" - the server has caught an exception when converting the incoming packet to ASCII (e.g. decode ('utf-8'))

More details

  • The server reads the incoming characters from the client one character at a time.
  • Once it sees the 0x0A character, it sets up a string buffer of all ASCII characters seen so far (less the 0x0A) and calls a callback function with that string.
  • The user must define that callback function.
  • The following is up to the user to define:
    • Which incoming commands are legal
    • What response to send if an illegal command is received
    • What response or responses should be sent for all legal commands
    • Determine whether an empty string is a legal command
    • How to handle the scenario when a linefeed needs to be part of a command
    • How to handle non-ASCII scenarios e.g. Unicode or byte strings.

Scripts

Sample code

see the sample directory for a sample client and server. Use doit script to run the sample server.

./doit
  • starts a server as a background process
  • starts a client and sends various commands to the server
  • stops that client
  • starts another client
  • sends some additional commands to the server
  • asks the server to shutdown

Other scripts and files

  • do_doc: generates doxygen
  • do_install: installs python environment
  • do_lint: runs static analysis tools
  • do_publish: publish the python module
  • do_ver: runs verification scripts
  • doit: runs a sample client & server
  • srs.json: holds a list of requirements the client/server must adhere to
  • test_ver.py: run by do_ver to perform verification
  • todo.md known issues to fix/address

- John Arrizza