queutils 0.10.0__tar.gz → 0.11.0__tar.gz

{queutils-0.10.0 → queutils-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: queutils
-Version: 0.10.0
+Version: 0.11.0
 Summary: Handy Python Queue utilies
 Project-URL: Homepage, https://github.com/Jylpah/queutils
 Project-URL: Bug Tracker, https://github.com/Jylpah/queutils/issues
@@ -58,11 +58,10 @@ an `asyncio.Queue` compatible interface to a (non-async) managed `multiprocessin
 `IterableQueue` is an `asyncio.Queue` subclass that is `AsyncIterable[T]` i.e. it can be 
 iterated in `async for` loop. `IterableQueue` terminates automatically when the queue has been filled and emptied. 
 
-The `IterableQueue` requires "producers" (functions adding items to the queue) to register themselves with `add_producer()` call and it 
-keeps count of registered producers which are "finished" adding items to the queue. Once all the registered 
-producers are "finished", the queue enters into "filled" state and no new items can be added. Once an 
-"filled" queue is emptied, the queue becomes "done" and all new `get()` calls to the queue will 
-`raise QueueDone` exception. 
+The `IterableQueue` requires "producers" (functions adding items to the queue) to register themselves with `add_producer()` call. It keeps count of registered producers. When a producer "finishes" adding items to the queue, 
+it needs to unregister itself with `finish_producer()` call. Once all the registered 
+producers are "finished", the queue enters into "filled" state and no new items can be added. Once a "filled" queue has been emptied, the queue becomes "done" and 
+all new `get()` calls to the queue will `raise QueueDone` exception. 
     
 ## Features
 
@@ -70,7 +69,7 @@ producers are "finished", the queue enters into "filled" state and no new items
 - `AsyncIterable` support: `async for item in queue:`
 - Automatic termination of the consumers with `QueueDone` exception when the queue has been emptied 
 - Producers must be registered with `add_producer()` and they must notify the queue
-  with `finish()` once they have finished adding items 
+  with `finish_producer()` once they have finished adding items 
 - Countable interface to count number of items task_done() through `count` property
 
 # EventCounterQueue

{queutils-0.10.0 → queutils-0.11.0}/README.md

@@ -27,11 +27,10 @@ an `asyncio.Queue` compatible interface to a (non-async) managed `multiprocessin
 [`IterableQueue`](docs/iterablequeue.md) is an `asyncio.Queue` subclass that is `AsyncIterable[T]` i.e. it can be 
 iterated in `async for` loop. `IterableQueue` terminates automatically when the queue has been filled and emptied. 
 
-The `IterableQueue` requires "producers" (functions adding items to the queue) to register themselves with `add_producer()` call and it 
-keeps count of registered producers which are "finished" adding items to the queue. Once all the registered 
-producers are "finished", the queue enters into "filled" state and no new items can be added. Once an 
-"filled" queue is emptied, the queue becomes "done" and all new `get()` calls to the queue will 
-`raise QueueDone` exception. 
+The `IterableQueue` requires "producers" (functions adding items to the queue) to register themselves with `add_producer()` call. It keeps count of registered producers. When a producer "finishes" adding items to the queue, 
+it needs to unregister itself with `finish_producer()` call. Once all the registered 
+producers are "finished", the queue enters into "filled" state and no new items can be added. Once a "filled" queue has been emptied, the queue becomes "done" and 
+all new `get()` calls to the queue will `raise QueueDone` exception. 
     
 ## Features
 
@@ -39,7 +38,7 @@ producers are "finished", the queue enters into "filled" state and no new items
 - `AsyncIterable` support: `async for item in queue:`
 - Automatic termination of the consumers with `QueueDone` exception when the queue has been emptied 
 - Producers must be registered with `add_producer()` and they must notify the queue
-  with `finish()` once they have finished adding items 
+  with `finish_producer()` once they have finished adding items 
 - Countable interface to count number of items task_done() through `count` property
 
 # EventCounterQueue

{queutils-0.10.0 → queutils-0.11.0}/demos/iterablequeue_demo.py

@@ -3,14 +3,14 @@ from random import random
 from queutils import IterableQueue, QueueDone
 from time import time
 
-start : float = time()
+start: float = time()
+
 
 def since() -> float:
     return time() - start
 
-async def producer(
-    Q: IterableQueue[int], N: int, id: int
-) -> None:
+
+async def producer(Q: IterableQueue[int], N: int, id: int) -> None:
     """
     Fill the queue with N items
     """
@@ -21,11 +21,12 @@ async def producer(
             print(f"{since():.2f} producer {id}: awaiting to put {i} to queue")
             await Q.put(i)
             print(f"{since():.2f} producer {id}: put {i} to queue")
-        await Q.finish()
+        await Q.finish_producer()
     except QueueDone:
         print(f"ERROR: producer {id}, this should not happen")
     return None
 
+
 async def consumer(Q: IterableQueue[int], id: int = 1):
     """
     Consume the queue
@@ -35,19 +36,21 @@ async def consumer(Q: IterableQueue[int], id: int = 1):
         await sleep(0.5 * random())
     print(f"{since():.2f} consumer {id}: queue is done")
 
+
 async def main() -> None:
     """
-    Create a queue with maxsize and have multiple producers to fill it and 
+    Create a queue with maxsize and have multiple producers to fill it and
     multiple consumers to consume it over async for loop
     """
-    queue : IterableQueue[int] = IterableQueue(maxsize=5)
+    queue: IterableQueue[int] = IterableQueue(maxsize=5)
 
     async with TaskGroup() as tg:
-        for i in range(1,3):
+        for i in range(1, 3):
             tg.create_task(producer(Q=queue, N=5, id=i))
         await sleep(2)
-        for  i in range(1,4):
+        for i in range(1, 4):
             tg.create_task(consumer(Q=queue, id=i))
 
+
 if __name__ == "__main__":
     run(main())

{queutils-0.10.0 → queutils-0.11.0}/docs/iterablequeue.md

@@ -9,7 +9,7 @@ iterated in `async for` loop. The great benefit of `IterableQueue` is that it te
 - `AsyncIterable` support: `async for item in queue:`
 - Automatic termination of the consumers with `QueueDone` exception when the queue has been emptied 
 - Producers must be registered with `add_producer()` and they must notify the queue
-  with `finish()` once they have finished adding items 
+  with `finish_producer()` once they have finished adding items 
 - Countable interface to count number of items task_done() through `count` property
 
 ### Experimental
@@ -21,7 +21,7 @@ iterated in `async for` loop. The great benefit of `IterableQueue` is that it te
 
 ### Producers fill a queue
 
-A *Producer* is "process" that adds items to the queue. A producer needs to be registered to the queue with `add_producer()` coroutine. Once a producer has added all the items it intends to, it notifies the queue with `finish()`
+A *Producer* is "process" that adds items to the queue. A producer needs to be registered to the queue with `add_producer()` coroutine. Once a producer has added all the items it intends to, it notifies the queue with `finish_producer()`
 
 ```python
 from queutils.iterablequeue import IterableQueue
@@ -37,7 +37,7 @@ async def producer(
         await Q.put(i)
     
     # notify the queue that this producer does not add more
-    await Q.finish()
+    await Q.finish_producer()
     
     return None
 ```
@@ -88,7 +88,7 @@ async def producer(
             print(f"{since():.2f} producer {id}: awaiting to put {i} to queue")
             await Q.put(i)
             print(f"{since():.2f} producer {id}: put {i} to queue")
-        await Q.finish()
+        await Q.finish_producer()
     except QueueDone:
         print(f"ERROR: producer {id}, this should not happen")
     return None

{queutils-0.10.0 → queutils-0.11.0}/pypi.md

@@ -27,11 +27,10 @@ an `asyncio.Queue` compatible interface to a (non-async) managed `multiprocessin
 `IterableQueue` is an `asyncio.Queue` subclass that is `AsyncIterable[T]` i.e. it can be 
 iterated in `async for` loop. `IterableQueue` terminates automatically when the queue has been filled and emptied. 
 
-The `IterableQueue` requires "producers" (functions adding items to the queue) to register themselves with `add_producer()` call and it 
-keeps count of registered producers which are "finished" adding items to the queue. Once all the registered 
-producers are "finished", the queue enters into "filled" state and no new items can be added. Once an 
-"filled" queue is emptied, the queue becomes "done" and all new `get()` calls to the queue will 
-`raise QueueDone` exception. 
+The `IterableQueue` requires "producers" (functions adding items to the queue) to register themselves with `add_producer()` call. It keeps count of registered producers. When a producer "finishes" adding items to the queue, 
+it needs to unregister itself with `finish_producer()` call. Once all the registered 
+producers are "finished", the queue enters into "filled" state and no new items can be added. Once a "filled" queue has been emptied, the queue becomes "done" and 
+all new `get()` calls to the queue will `raise QueueDone` exception. 
     
 ## Features
 
@@ -39,7 +38,7 @@ producers are "finished", the queue enters into "filled" state and no new items
 - `AsyncIterable` support: `async for item in queue:`
 - Automatic termination of the consumers with `QueueDone` exception when the queue has been emptied 
 - Producers must be registered with `add_producer()` and they must notify the queue
-  with `finish()` once they have finished adding items 
+  with `finish_producer()` once they have finished adding items 
 - Countable interface to count number of items task_done() through `count` property
 
 # EventCounterQueue

{queutils-0.10.0 → queutils-0.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "queutils"
-version = "0.10.0"
+version = "0.11.0"
 authors = [{ name = "Jylpah", email = "jylpah@gmail.com" }]
 description = "Handy Python Queue utilies"
 readme = { file = "pypi.md", content-type = "text/markdown" }

{queutils-0.10.0 → queutils-0.11.0}/src/queutils/iterablequeue.py

@@ -50,7 +50,7 @@ class IterableQueue(Queue[T], AsyncIterable[T], Countable):
     - AsyncIterable(): async for item in queue:
     - Automatic termination of the consumers when the queue has been emptied with QueueDone exception
     - Producers must be registered with add_producer() and they must notify the queue
-      with finish() once they have finished adding items
+      with finish_producer() once they have finished adding items
     - Countable interface to count number of items task_done() through 'count' property
 
     IterableQueue stages:
@@ -82,6 +82,17 @@ class IterableQueue(Queue[T], AsyncIterable[T], Countable):
 
         self._empty.clear()  # this will be tested only after queue is filled
 
+    @classmethod
+    def from_queue(cls, Q: Queue[Optional[T]]) -> "IterableQueue[T]":
+        """
+        Create IterableQueue from existing asyncio.Queue
+        """
+        if not isinstance(Q, Queue):
+            raise TypeError("Q must be an instance of asyncio.Queue")
+        iq: IterableQueue[T] = cls(maxsize=Q.maxsize)
+        iq._Q = Q
+        return iq
+
     @property
     def is_filled(self) -> bool:
         """ "
@@ -166,7 +177,7 @@ class IterableQueue(Queue[T], AsyncIterable[T], Countable):
         """
         Producer has finished adding items to the queue.
         Once the last producers has finished, the queue is_filled.
-        - all: finish() queue for all producers at once
+        - all: finish_producer() queue for all producers at once
 
         Return True if the last producer is 'finished'
         """
@@ -177,7 +188,7 @@ class IterableQueue(Queue[T], AsyncIterable[T], Countable):
             self._producers -= 1
 
             if self._producers < 0:
-                raise ValueError("Too many finish() calls")
+                raise ValueError("Too many finish_producer() calls")
             elif all or self._producers == 0:
                 self._filled.set()
                 self._producers = 0

{queutils-0.10.0 → queutils-0.11.0}/tests/test_iterablequeue.py

@@ -1,5 +1,5 @@
 import pytest  # type: ignore
-from asyncio.queues import QueueEmpty, QueueFull
+from asyncio.queues import QueueEmpty, QueueFull, Queue
 from asyncio import (
     Task,
     create_task,
@@ -9,6 +9,7 @@ from asyncio import (
     TimeoutError,
     CancelledError,
 )
+from typing import Optional
 from random import random
 
 from queutils import IterableQueue, QueueDone
@@ -232,7 +233,7 @@ async def test_6_finish_full_queue(test_interablequeue_int: IterableQueue[int]):
         )
         assert Q.is_done, "Queue is not done"
     except TimeoutError:
-        assert False, f"await IterableQueue.finish() failed. qsize={Q.qsize()}"
+        assert False, f"await IterableQueue.finish_producer() failed. qsize={Q.qsize()}"
     await sleep(0.1)
     assert Q.is_done, "Queue is not done"
     producer.cancel()
@@ -281,3 +282,17 @@ async def test_8_aiter_1_item(test_interablequeue_int: IterableQueue[int]):
         )
     except TimeoutError:
         assert False, "await IterableQueue.join() failed with an empty queue finished"
+
+
+@pytest.mark.asyncio
+async def test_9_from_queue():
+    """Test from_queue class method"""
+    Q = Queue[Optional[int]](maxsize=QSIZE)
+    iq = IterableQueue.from_queue(Q)
+    assert iq.maxsize == Q.maxsize, "maxsize does not match"
+    assert iq.qsize() == Q.qsize(), "qsize does not match"
+    assert iq.empty() == Q.empty(), "empty() does not match"
+    assert iq.full() == Q.full(), "full() does not match"
+
+    with pytest.raises(TypeError):
+        IterableQueue.from_queue("not a queue")