Extend README and echo_server.py

README.md

@@ -1,4 +1,4 @@
-# pipe_io_server
+# pipe-io-server
 A trivial to use IPC solution based on POSIX named pipes and newlines.
 
 ## Why?
@@ -42,6 +42,7 @@ This may sound discouraging, but this is the exact reason why I've written this
 so you won't have to.
 And solving all these issues are worth it in the end: writing clients is as trivial as it gets.
 
+## What?
 This package provides robust, asynchronous servers capable of IO over a text-based,
 newline delimited protocol using named pipes.
 This makes it extremely easy to integrate any external process as a plugin
@@ -50,15 +51,19 @@ without worrying about anything else.
 
 ## Examples
 
-A working client written in just a 4 lines of bash (`in` and `out` are the paths of the pipes):
+A few lines of code are worth a 100 lines of API documentation.
+You can find a simple usage example of this package in `echo_server.py`.
+
+A client replying to each message of the server in just a few lines of bash
+(`send` and `recv` are the paths of the pipes):
 ```
 while IFS= read -r message; do
-    printf "Received: ${message}"
+    printf "Received: ${message}\n"
-    printf "some response\n" > "out"
+    # ... do something ...
-done < "in"
+    printf "Some response\n" > "send"
+done < "recv"
 ```
 
 Some more examples:
-- `echo_server.py` showcases a simple echo server
 - `pipe_io_server/clients` contains examples on how to use pipes in different languages
 - `pipe_io_server/test_pipe_io_server.py` contains a relatively comprehensive suite of unit tests

echo_server.py

@@ -3,18 +3,30 @@ from signal import signal, SIGTERM, SIGINT
 from pipe_io_server import PipeIOServer
 
 
+# inherit from PipeIOServer for read-write servers,
+# use PipeReaderServer or PipeWriterServer for
+# read-only or write-only servers
 class EchoPipeIOServer(PipeIOServer):
     def handle_message(self, message):
         self.send_message(message)
 
 
-if __name__ == "__main__":
+def main():
-    pipe_io = EchoPipeIOServer('in', 'out')
+    pipe_io = EchoPipeIOServer('send', 'recv')
+    # or in case you'd prefer to do it without inheritance:
+    # pipe_io = PipeIOServer('send', 'recv')
+    # pipe_io.handle_message = pipe_io.send_message
+
     signal(SIGTERM, lambda a, b: pipe_io.stop())
     signal(SIGINT, lambda a, b: pipe_io.stop())
     pipe_io.on_stop = lambda: print('Stopping...')
-    pipe_io.start()
+
+    pipe_io.start()  # start the server without blocking
     print('Running pipe IO server with named pipes:')
     print(f'Input:  {pipe_io.in_pipe}')
     print(f'Output: {pipe_io.out_pipe}')
-    pipe_io.wait()
+    pipe_io.wait()  # block until the server stops
+
+
+if __name__ == "__main__":
+    main()