dsmq 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

dsmq/demo_linux.py

@@ -11,7 +11,7 @@ PORT = 25252
 
 
 def test_server_with_clients():
-    p_server = mp.Process(target=dsmq.run, args=(HOST, PORT))
+    p_server = mp.Process(target=dsmq.start_server, args=(HOST, PORT))
     p_server.start()
 
     p_putter = mp.Process(target=example_put_client.run, args=(HOST, PORT, 20))

dsmq/dsmq.py

@@ -5,11 +5,19 @@ import sys
 from threading import Thread
 import time
 
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 30008
+
 N_RETRIES = 5
 FIRST_RETRY = 0.01  # seconds
 
 
-def run(host="127.0.0.1", port=30008):
+def start_server(host=DEFAULT_HOST, port=DEFAULT_PORT):
+    """
+    For best results, start this running in its own process and walk away.
+
+
+    """
     sqlite_conn = sqlite3.connect("file:mem1?mode=memory&cache=shared")
     cursor = sqlite_conn.cursor()
 
@@ -34,12 +42,40 @@ def run(host="127.0.0.1", port=30008):
         while True:
             socket_conn, addr = s.accept()
             print(f"Connected by {addr}")
-            Thread(target=handle_socket, args=(socket_conn,)).start()
+            Thread(target=_handle_client_connection, args=(socket_conn,)).start()
 
     sqlite_conn.close()
 
 
-def handle_socket(socket_conn):
+def connect_to_server(host=DEFAULT_HOST, port=DEFAULT_PORT):
+    return DSMQClientSideConnection(host, port)
+
+
+class DSMQClientSideConnection:
+    def __init__(self, host, port):
+        self.dsmq_conn = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self.dsmq_conn.connect((host, port))
+
+    def get(self, topic):
+        msg = json.dumps({"action": "get", "topic": topic})
+        self.dsmq_conn.sendall(bytes(msg, "utf-8"))
+
+        data = self.dsmq_conn.recv(1024)
+        if not data:
+            raise RuntimeError("Connection terminated by server")
+        msg_str = data.decode("utf-8")
+        msg = json.loads(msg_str)
+        try:
+            return msg["message"]
+        except KeyError:
+            return ""
+
+    def put(self, topic, msg):
+        msg = json.dumps({"action": "put", "topic": topic, "message": msg})
+        self.dsmq_conn.sendall(bytes(msg, "utf-8"))
+
+
+def _handle_client_connection(socket_conn):
     sqlite_conn = sqlite3.connect("file:mem1?mode=memory&cache=shared")
     cursor = sqlite_conn.cursor()
 
@@ -140,12 +176,12 @@ if __name__ == "__main__":
     if len(sys.argv) == 3:
         host = sys.argv[1]
         port = int(sys.argv[2])
-        run(host=host, port=port)
+        start_server(host=host, port=port)
     elif len(sys.argv) == 2:
         host = sys.argv[1]
-        run(host=host)
+        start_server(host=host)
     elif len(sys.argv) == 1:
-        run()
+        start_server()
     else:
         print(
             """

dsmq/example_get_client.py

@@ -1,21 +1,14 @@
-import json
-import socket
 import time
+import dsmq
 
 
 def run(host="127.0.0.1", port=30008, n_iter=1000):
-    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-        s.connect((host, port))
+    mq = dsmq.connect_to_server(host=host, port=port)
 
-        for i in range(n_iter):
-            time.sleep(1)
-            msg = json.dumps({"action": "get", "topic": "greetings"})
-            s.sendall(bytes(msg, "utf-8"))
-            data = s.recv(1024)
-            if not data:
-                raise RuntimeError("Connection terminated by server")
-            msg_str = data.decode("utf-8")
-            print(f"client received {json.loads(msg_str)}")
+    for i in range(n_iter):
+        time.sleep(1)
+        msg = mq.get("greetings")
+        print(f"client received {msg}")
 
 
 if __name__ == "__main__":

dsmq/example_put_client.py

@@ -1,18 +1,16 @@
-import json
-import socket
 import time
+import dsmq
 
 
 def run(host="127.0.0.1", port=30008, n_iter=1000):
-    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-        s.connect((host, port))
+    mq = dsmq.connect_to_server(host=host, port=port)
 
-        for i in range(n_iter):
-            time.sleep(1)
-            note = f"{i}. Hello, world"
-            msg = json.dumps({"action": "put", "topic": "greetings", "message": note})
-            s.sendall(bytes(msg, "utf-8"))
-            print(f"client sent {msg}")
+    for i in range(n_iter):
+        time.sleep(1)
+        msg = f"{i}. Hello, world"
+        topic = "greetings"
+        mq.put(topic, msg)
+        print(f"client sent {msg}")
 
 
 if __name__ == "__main__":

dsmq/example_server.py

@@ -1,3 +1,3 @@
-from dsmq import dsmq
+import dsmq
 
-dsmq.run(host="127.0.0.1", port=12345)
+dsmq.start_server(host="127.0.0.1", port=30008)

dsmq-0.4.0.dist-info/METADATA

@@ -0,0 +1,146 @@
+Metadata-Version: 2.3
+Name: dsmq
+Version: 0.4.0
+Summary: A dead simple message queue
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Dead Simple Message Queue
+
+## What it does
+
+Part mail room, part bulletin board, dsmq is a central location for sharing messages
+between processes, even when they are running on computers scattered around the world.
+
+Its defining characteristic is bare-bones simplicity.
+
+## How to use it
+
+### Install
+
+```bash
+pip install dsmq
+```
+### Create a dsmq server
+
+As in `src/dsmq/example_server.py`
+
+```python
+from dsmq import dsmq
+
+dsmq.start_server(host="127.0.0.1", port=30008)
+```
+
+### Connect a client to a dsmq server
+
+As in `src/dsmq/example_put_client.py`
+
+```python
+mq = dsmq.connect_to_server(host="127.0.0.1", port=12345)
+```
+### Add a message to a queue
+
+As in `src/dsmq/example_put_client.py`
+
+```python
+topic = "greetings"
+msg = "hello world!"
+mq.put(topic, msg)
+```
+
+### Read a message from a queue
+
+As in `src/dsmq/example_get_client.py`
+
+```python
+topic = "greetings"
+msg = mq.get(topic)
+```
+
+### Spin up and shut down a dsmq in its own process
+
+A dsmq server doesn't come with a built-in way to shut itself down. 
+It can be helpful to have it running in a separate process that can be
+managed
+
+```python
+import multiprocessing as mp
+
+p_mq = mp.Process(target=dsmq.start_server, args=(config.MQ_HOST, config.MQ_PORT))
+p_mq.start()
+
+p_mq.join()
+# or 
+p_mq.kill()
+p_mq.close()
+```
+
+### Demo
+
+1. Open 3 separate terminal windows.
+1. In the first, run `src/dsmq/dsmq.py`.
+1. In the second, run `src/dsmq/example_put_client.py`.
+1. In the third, run `src/dsmq/example_get_client.py`.
+
+Alternatively, if you're on Linux just run `src/dsmq/demo_linux.py`.
+
+## How it works
+
+### Expected behavior and limitations
+
+- Many clients can read messages of the same topic. It is a one-to-many
+publication model.
+
+- A client will not be able to read any of the messages that were put into
+a queue before it connected.
+
+- A client will get the oldest message available on a requested topic.
+Queues are first-in-first-out.
+
+- Put and get operations are fairly quick--less than 100 $`\mu`$s of processing
+time plus any network latency--so it can comfortably handle requests at rates of
+hundreds of times per second. But if you have several clients reading and writing
+at 1 kHz or more, you may overload the queue.
+
+- The queue is backed by an in-memory SQLite database. If your message volumes
+get larger than your RAM, you will reach an out-of-memory condition.
+
+
+# API Reference
+[[source](https://github.com/brohrer/dsmq/blob/main/src/dsmq/dsmq.py)]
+
+### `start_server(host="127.0.0.1", port=30008)`
+
+Kicks off the mesage queue server. This process will be the central exchange
+for all incoming and outgoing messages.
+- `host` (str), IP address on which the server will be visible and
+- `port` (int), port. These will be used by all clients.
+Non-privileged ports are numbered 1024 and higher.
+
+### `connect_to_server(host="127.0.0.1", port=30008)`
+
+Connects to an existing message queue server.
+- `host` (str), IP address of the *server*.
+- `port` (int), port on which the server is listening.
+- returns a `DSMQClientSideConnection` object.
+
+## `DSMQClientSideConnection` class
+
+This is a convenience wrapper, to make the `get()` and `put()` functions
+easy to write and remember.
+
+### `put(topic, msg)`
+
+Puts `msg` into the queue named `topic`. If the queue doesn't exist yet, it is created.
+- msg (str), the content of the message.
+- topic (str), name of the message queue in which to put this message.
+
+### `get(topic)`
+
+Get the oldest eligible message from the queue named `topic`.
+The client is only elgibile to receive messages that were added after it
+connected to the server.
+- `topic` (str)
+- returns str, the content of the message. If there was no eligble message
+in the topic, or the topic doesn't yet exist,
+returns "".

dsmq-0.4.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+dsmq/__init__.py,sha256=YCgbnQAk8YbtHRyMcU0v2O7RdRhPhlT-vS_q40a7Q6g,50
+dsmq/demo_linux.py,sha256=7yLglGmirDLuuyMxppYSK-dfx2Fg2Q0dIWB4cl2yV1c,622
+dsmq/dsmq.py,sha256=5fo3wQfw2lIXiDGB05sRwVLDN0ZoUSw7e7WO8xOLXJY,5558
+dsmq/example_get_client.py,sha256=chFfB2949PBENmgdUc3ASrATq1m4wvHGBzEnOC-o_Xs,296
+dsmq/example_put_client.py,sha256=mUKCRhmUieMZEpHLFWFvzeKB6IR7A8l4tWN8TvPzdKU,348
+dsmq/example_server.py,sha256=kkXOPaaTzVxf9_iIM76zU9pZhkPna_1vcGWkPrhCjus,61
+dsmq-0.4.0.dist-info/METADATA,sha256=T3godcTW__I3b2hj2dgJCjMJEGEo6S1HP_Iq5EQD6Ok,3878
+dsmq-0.4.0.dist-info/WHEEL,sha256=3U_NnUcV_1B1kPkYaPzN-irRckL5VW_lytn0ytO_kRY,87
+dsmq-0.4.0.dist-info/licenses/LICENSE,sha256=3Yu1mAp5VsKmnDtzkiOY7BdmrLeNwwZ3t6iWaLnlL0Y,1071
+dsmq-0.4.0.dist-info/RECORD,,

{dsmq-0.2.0.dist-info → dsmq-0.4.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.25.0
+Generator: hatchling 1.26.1
 Root-Is-Purelib: true
 Tag: py3-none-any

dsmq-0.2.0.dist-info/METADATA

@@ -1,156 +0,0 @@
-Metadata-Version: 2.3
-Name: dsmq
-Version: 0.2.0
-Summary: A dead simple message queue
-License-File: LICENSE
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-
-# Dead Simple Message Queue
-
-## What it does
-
-Part mail room, part bulletin board, dsmq is a central location for sharing messages
-between processes, even when they are running on computers scattered around the world.
-
-Its defining characteristic is its bare-bones simplicity.
-
-## How to use it
-
-### Install
-
-```bash
-pip install dsmq
-```
-### Create a dsmq server
-
-As in `src/dsmq/example_server.py`
-
-```python
-from dsmq import dsmq
-
-dsmq.run(host="127.0.0.1", port=12345)
-```
-
-### Add a message to a queue
-
-As in `src/dsmq/example_put_client.py`
-
-```python
-import json
-import socket
-
-with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-    s.connect(("127.0.0.1", 12345))
-    message_content = {"action": "put", "topic": "greetings", "message": "Hello!"}
-    msg = json.dumps(message_content)
-    s.sendall(bytes(msg, "utf-8"))
-```
-
-### Read a message from a queue
-
-As in `src/dsmq/example_get_client.py`
-
-```python
-import json
-import socket
-
-with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-    s.connect(("127.0.0.1", 12345))
-
-    for i in range(n_iter):
-        request_message_content = {"action": "get", "topic": "greetings"}
-        request_msg = json.dumps(request_message_content)
-        s.sendall(bytes(reequest_msg, "utf-8"))
-
-        reply_msg = s.recv(1024)
-        if not reply_msg:
-            raise RuntimeError("Connection terminated by server")
-        reply_msg_content = reply_msg.decode("utf-8")
-```
-
-### Demo
-
-1. Open 3 separate terminal windows.
-1. In the first, run `src/dsmq/dsmq.py`.
-1. In the second, run `src/dsmq/example_put_client.py`.
-1. In the third, run `src/dsmq/example_get_client.py`.
-
-
-## How it works
-
-### Expected behavior and limitations
-
-- Many clients can read messages of the same topic. It is a one-to-many
-pulication model.
-
-- A client will not be able to read any of the messages that were put into
-a queue before it connected.
-
-- A client will get the oldest message available on a requested topic.
-Queues are first-in-first-out.
-
-- Put and get operations are fairly quick--less than 100 $`\mu`$s of processing
-time plus any network latency--so it can comfortably handle operations at
-hundreds of Hz. But if you try to have several clients reading and writing
-at 1 kHz or more, you may overload the queue.
-
-- The queue is backed by an in-memory SQLite database. If your message volumes
-get larger than your RAM, you may reach an out-of-memory condition.
-
-
-# API Reference and Cookbook
-[[source](https://github.com/brohrer/dsmq/blob/main/src/dsmq/dsmq.py)]
-
-### Start a server
-
-```python
-run(host="127.0.0.1", port=30008)
-```
-
-Kicks off the mesage queue server. This process will be the central exchange
-for all incoming and outgoing messages.
-- `host` (str), IP address on which the server will be visible and
-- `port` (int), port. These will be used by all clients.
-Non-privileged ports are numbered 1024 and higher.
-
-### Open a connection from a client
-
-```python
-import socket
-
-with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-    s.connect((host, port ))
-```
-
-### Add a message to a queue
-
-```python
-import json
-msg = json.dumps({
-    "action": "put",
-    "topic": <queue-name>,
-    "message": <message-content>
-})
-s.sendall(bytes(msg, "utf-8"))
-```
-
-- `s`, the socket connection to the server
-- `<queue-name>` (str), a name for the queue where the message will be added
-- `<message-content>` (str), whatever message content you want
-
-Place `message-content` into the queue named `queue-name`.
-If the queue doesn't exist yet, create it.
-
-### Get a message from a queue
-
-```python
-request_msg = json.dumps({"action": "get", "topic": <queue-name>})
-s.sendall(bytes(request_msg, "utf-8"))
-data = s.recv(1024)
-msg_str = data.decode("utf-8")
-```
-
-Get the oldest eligible message from the queue named `<queue-name>`.
-The client is only elgibile to receive messages added after it
-connected to the server.

dsmq-0.2.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-dsmq/__init__.py,sha256=YCgbnQAk8YbtHRyMcU0v2O7RdRhPhlT-vS_q40a7Q6g,50
-dsmq/demo_linux.py,sha256=D5NjEvPG-fTGRRbYzMJXgtwfrigOt_eaR6D0AozBNbA,613
-dsmq/dsmq.py,sha256=EJW6tMeG57QYBneqBEM4R_5CrtG-Lx2qz0D1BM0YtjI,4452
-dsmq/example_get_client.py,sha256=ZWZrAu7sIEn8VwCK09cTwsm1XnF3Jkor3r7Gl4ljUMw,630
-dsmq/example_put_client.py,sha256=bSjSJZsFZB6inVGUlTnJn0jgrpVNXvrN46STTvgwCzs,497
-dsmq/example_server.py,sha256=UM69GN7uORDetXQM8LlW68nrA-1i7Jgp2dZREVEqxaU,62
-dsmq/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-dsmq-0.2.0.dist-info/METADATA,sha256=TW6tM_oF2LuyRrmOBSBTHFCkJvNDA8O3QfuEtgD1-S8,4055
-dsmq-0.2.0.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
-dsmq-0.2.0.dist-info/licenses/LICENSE,sha256=3Yu1mAp5VsKmnDtzkiOY7BdmrLeNwwZ3t6iWaLnlL0Y,1071
-dsmq-0.2.0.dist-info/RECORD,,