socket-oneline

Name	socket-oneline JSON
Version	0.1.0 JSON
	download
home_page	None
Summary	server and client for simple, one line communication protocol
upload_time	2024-12-11 22:40:41
maintainer	None
docs_url	None
author	None
requires_python	>=3.9
license	MIT
keywords	socket client server simple
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

* website: <https://arrizza.com/python-socket-oneline>
* installation: see <https://arrizza.com/setup-common>

## 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

* See [Quick Start](https://arrizza.com/user-guide-quick-start) for information on using scripts.
* See [xplat-utils submodule](https://arrizza.com/xplat-utils) for information on the submodule.

## 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

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "socket-oneline",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": "\"J. Arrizza\" <cppgent0@gmail.com>",
    "keywords": "socket, client server, simple",
    "author": null,
    "author_email": "\"J. Arrizza\" <cppgent0@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/1c/d6/c73ebe9506afc0128685f1d3d21eafe63fb57d80a8a17f8811d7f8e9a76a/socket_oneline-0.1.0.tar.gz",
    "platform": null,
    "description": "* website: <https://arrizza.com/python-socket-oneline>\n* installation: see <https://arrizza.com/setup-common>\n\n## Summary\n\nThis module contains a simple base class for handling sockets\n\nThe communication protocol has these basic rules:\n\n- socket based using TCPIP; only one server per port\n- only one client connected at any time. When that client\n  disconnects, another client is allowed to connect.\n- a \"packet\" is terminated by a line feed (0x0A).\n- a client sends a packet (aka \"command\") to the server.\n- Alternatively the server may respond with zero, one or more\n  packets (aka \"responses\")\n- The server cannot initiate a response asynchronously by\n  itself i.e. it must wait for an incoming command to send\n  any packets to the client.\n- the following commands are predefined:\n    - \"ping\" : the server will respond with \"pong\". The client\n      can use this to confirm that the socket and communication\n      channel are alive and responsive\n    - \"disconnect\" : the server will initiate a disconnect\n      from the current client\n    - \"shutdown\" : the server will disconnect and then\n      shutdown\n    - \"invalid\" - the server has caught an exception when\n      converting the incoming packet to ASCII (e.g. decode\n      ('utf-8'))\n\n## More details\n\n- The server reads the incoming characters from the client one\n  character at a time.\n- Once it sees the 0x0A character, it sets up a string\n  buffer of all ASCII characters seen so far (less the 0x0A) and\n  calls a callback function with that string.\n- The user must define that callback function.\n- The following is up to the user to define:\n    - Which incoming commands are legal\n    - What response to send if an illegal command is received\n    - What response or responses should be sent for all legal\n      commands\n    - Determine whether an empty string is a legal command\n    - How to handle the scenario when a linefeed needs to be\n      part of a command\n    - How to handle non-ASCII scenarios e.g. Unicode or byte\n      strings.\n\n## Scripts\n\n* See [Quick Start](https://arrizza.com/user-guide-quick-start) for information on using scripts.\n* See [xplat-utils submodule](https://arrizza.com/xplat-utils) for information on the submodule.\n\n## Sample code\n\nsee the sample directory for a sample client and server. Use\ndoit script to run the sample server.\n\n```\n    ./doit\n```\n\n- starts a server as a background process\n- starts a client and sends various commands to the server\n- stops that client\n- starts another client\n- sends some additional commands to the server\n- asks the server to shutdown\n\n## Other scripts and files\n\n- do_doc: generates doxygen\n- do_install: installs python environment\n- do_lint: runs static analysis tools\n- do_publish: publish the python module\n- do_ver: runs verification scripts\n- doit: runs a sample client & server\n- srs.json: holds a list of requirements the client/server\n  must adhere to\n- test_ver.py: run by do_ver to perform verification\n- todo.md known issues to fix/address\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "server and client for simple, one line communication protocol",
    "version": "0.1.0",
    "project_urls": {
        "Download": "https://bitbucket.org/arrizza-public/socket-oneline/get/master.zip",
        "Source": "https://bitbucket.org/arrizza-public/socket-oneline/src/master",
        "Website": "https://arrizza.com/python-socket-oneline"
    },
    "split_keywords": [
        "socket",
        " client server",
        " simple"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "1cd6c73ebe9506afc0128685f1d3d21eafe63fb57d80a8a17f8811d7f8e9a76a",
                "md5": "b232fe8be1278b879ac0312d9561d7ba",
                "sha256": "4d419c5338260f403c00acd0925d96f434ace4b3f024dcbcce13292185b5129f"
            },
            "downloads": -1,
            "filename": "socket_oneline-0.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "b232fe8be1278b879ac0312d9561d7ba",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9",
            "size": 10166,
            "upload_time": "2024-12-11T22:40:41",
            "upload_time_iso_8601": "2024-12-11T22:40:41.379990Z",
            "url": "https://files.pythonhosted.org/packages/1c/d6/c73ebe9506afc0128685f1d3d21eafe63fb57d80a8a17f8811d7f8e9a76a/socket_oneline-0.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-12-11 22:40:41",
    "github": false,
    "gitlab": false,
    "bitbucket": true,
    "codeberg": false,
    "bitbucket_user": "arrizza-public",
    "bitbucket_project": "socket-oneline",
    "lcname": "socket-oneline"
}

None