tests: add comments and docstrings

tests/test_calendar.py

@@ -12,19 +12,24 @@
 
 @pytest.mark.asyncio
 async def test_init():
+    """Test initializing a Calendar"""
 
     c: Calendar[MyItem] = Calendar()
 
 
 @pytest.mark.asyncio
 async def test_schedule():
+    """Test scheduling an event result in having a the correct event
+    scheduled as next and at the correct time.
+    """
 
     c: Calendar[str] = Calendar()
 
     ts = datetime.now() + timedelta(seconds=10)
 
     c.schedule("foo", ts)
 
+    # check that the next in line is the correct one and that the time remaining is approximately the same (can't check exact)
     assert c.next_scheduled() == "foo" and math.isclose(
         c.time_remaining(), ts.timestamp() - time(), abs_tol=ABS_TOLERANCE
     )
@@ -33,33 +38,53 @@ async def test_schedule():
 
     c.schedule("bar", ts.timestamp())
 
+    # check that the next in line is the correct one and that the time remaining is approximately the same (can't check exact)
     assert c.next_scheduled() == "bar" and math.isclose(
         c.time_remaining(), ts.timestamp() - time(), abs_tol=ABS_TOLERANCE
     )
 
 
 @pytest.mark.asyncio
 async def test_events_generator():
+    """Test that the events generator yields event at the correct time
+    and in the correct order.
+    """
 
     c: Calendar[int] = Calendar()
 
     ts = datetime.now()
 
+    # add some elements
     for i in range(5):
         c.schedule(i, ts + timedelta(seconds=i * 1))
 
     count = 0
     async for ts, event in c.events():
+        # ensure events are yielded at the right time
         assert time() >= ts or math.isclose(time(), ts)
         assert event == count
         count += 1
 
+        if count == 2:
+            # cancel an event, make sure it is cancelled
+            # so that we can test that the generator
+            # works correctly when events are cancelled
+            # while it's being used.
+            ce = c.cancel_event(lambda x: x[1] == 2)
+            assert len(ce) == 1
+            # increase the count so that the checks
+            # that are based on the index can pass
+            # (we removed the next one)
+            count += 1
+
         if count == 5:
+            assert len(c.remaining_events()) == 0
             c.stop()
 
 
 @pytest.mark.asyncio
 async def test_run_async_executor():
+    """Test the run method with an async executor"""
 
     c: Calendar[int] = Calendar()
 
@@ -94,6 +119,7 @@ async def async_executor(ts, item, calendar):
 
 @pytest.mark.asyncio
 async def test_run_executor():
+    """Test the run method with a regular synchronous function as executor"""
 
     c: Calendar[int] = Calendar()
 
@@ -139,6 +165,8 @@ def executor(ts, item, calendar):
 
 @pytest.mark.asyncio
 async def test_cancel_events():
+    """Test that cancelling events remove them from the calendar
+    and that the next in line is correctly scheduled"""
 
     c: Calendar[int] = Calendar()
 

tests/test_calendar_queue.py

@@ -17,6 +17,10 @@ def test_init():
 
 @pytest.mark.asyncio
 async def test_simple_put():
+    """Test put by putting one element and checking that
+    the it is present in the queue and verifying that the
+    timer is correctly set for the given timestamp
+    """
 
     cq = CalendarQueue()
 
@@ -32,6 +36,7 @@ async def test_simple_put():
 
     assert cq.peek() == foo[-1]
 
+    # check timer is correct (we can't match the exact timestamp)
     assert math.isclose(
         cq._getter_timer.when(), base_loop_ts + 10, abs_tol=ABS_TOLERANCE
     )
@@ -44,27 +49,36 @@ async def test_simple_put():
 
     assert cq.peek() == bar[-1]
 
+    # check timer is correct (we can't match the exact timestamp)
     assert math.isclose(
         cq._getter_timer.when(), base_loop_ts + 5, abs_tol=ABS_TOLERANCE
     )
 
 
 @pytest.mark.asyncio
 async def test_get():
+    """Test getting an element by putting one, getting it and
+    checking that the time at which it is returned is correct.
+    """
 
     cq = CalendarQueue()
 
     foo = (time() + 1, "foo")
 
     await cq.put(item=foo)
 
+    # check timer is correct (we can't match the exact timestamp)
     assert (await cq.get()) == foo and (
         time() >= foo[0] or math.isclose(time(), foo[0])
     )
 
 
 @pytest.mark.asyncio
 async def test_delete_items():
+    """Test the routing for deleting the items by inserting
+    a set of numbers, purging only the odd entries
+    and then checking the number of remaining elements.
+    """
 
     cq = CalendarQueue()
 
@@ -78,6 +92,11 @@ async def test_delete_items():
 
 @pytest.mark.asyncio
 async def test_far_schedule():
+    """Test putting an event scheduled far in time.
+    We use time-machine to simulate the time traveling
+    and verify that the elements are returned at the correct
+    timestamp.
+    """
 
     cq = CalendarQueue()
 
@@ -96,6 +115,15 @@ async def test_far_schedule():
 
 @pytest.mark.asyncio
 async def test_far_schedule_alt():
+    """Another far schedule test still using time-machine.
+    This time two tasks are defined, both depends on time-machine's
+    timestamp
+    - task 1 puts an item, verifies that is's not immediately returned,
+        sets an asyncio.Event and awaits for the event to be returned
+    - task 2 awaits for the Event to be set by task 1 and then shifts
+        the time so that the test doesn't have to wait for 1 month to
+        be done.
+    """
 
     cq = CalendarQueue()
 
@@ -146,6 +174,11 @@ async def shift_time():
 
 @pytest.mark.asyncio
 async def test_put():
+    """Another test for put, this time we put events scheduled
+    for several timestamp, willingly in an unordered fashion
+    and each time verify that the timer for returning the next
+    event is correctly updated.
+    """
 
     cq_nosize = CalendarQueue()
 
@@ -154,18 +187,21 @@ async def test_put():
 
     await cq_nosize.put((base_ts + 180, "foo"))
 
+    # check timer is correct (we can't match the exact timestamp)
     assert math.isclose(
         cq_nosize._getter_timer.when(), base_loop_ts + 180, abs_tol=ABS_TOLERANCE
     )
 
     await cq_nosize.put((base_ts + 300, "bar"))
 
+    # check timer is correct (we can't match the exact timestamp)
     assert math.isclose(
         cq_nosize._getter_timer.when(), base_loop_ts + 180, abs_tol=ABS_TOLERANCE
     )
 
     await cq_nosize.put((base_ts + 90, "baz"))
 
+    # check timer is correct (we can't match the exact timestamp)
     assert math.isclose(
         cq_nosize._getter_timer.when(), base_loop_ts + 90, abs_tol=ABS_TOLERANCE
     )
@@ -175,6 +211,8 @@ async def test_put():
 
 @pytest.mark.asyncio
 async def test_put_limited_q():
+    """Test putting elements in a CalendarQueue with maxsize set."""
+
     cq = CalendarQueue(1)
 
     base_ts = time()
@@ -232,6 +270,9 @@ async def get_queue():
 
 @pytest.mark.asyncio
 async def test_next_in():
+    """Test for ensuring that next_in returns the time left
+    until the next scheduled event is correct.
+    """
 
     cq = CalendarQueue()
 
@@ -259,6 +300,9 @@ async def test_next_in():
 
 @pytest.mark.asyncio
 async def test_peek():
+    """Test to make sure that peek returns correctly the
+    next event in the queue.
+    """
 
     cq = CalendarQueue()
 
@@ -280,6 +324,9 @@ async def test_peek():
 
 @pytest.mark.asyncio
 async def test_delete():
+    """Test that every time an event is deleted, the timer for
+    getting the next event in the queue is correctly updated.
+    """
 
     cq = CalendarQueue()