Merge pull request #59 from mutating/develop

0.0.42

Author: pomponchik

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cantok"
-version = "0.0.41"
+version = "0.0.42"
 authors = [{ name = "Evgeniy Blinov", email = "zheni-b@yandex.ru" }]
 description = 'Implementation of the "Cancellation Token" pattern'
 readme = "README.md"

tests/examples/test_examples.py

@@ -6,6 +6,13 @@
 counter = 0
 
 def test_cancel_simple_token_with_function_and_thread():
+    """
+    A quick-start Condition, Counter, and Timeout composition can stop a worker thread.
+
+    The worker receives the composed token, performs some work while `.cancelled`
+    is false, and exits once the random condition, indirect counter poll, or
+    timeout cancels the shared token.
+    """
     def function(token):
         global counter  # noqa: PLW0603
         while not token.cancelled:
@@ -20,6 +27,12 @@ def function(token):
 
 
 def test_cancel_simple_token_with_function_and_thread_2():
+    """
+    A quick-start Condition, Counter, and Timeout composition can be a truthy loop guard.
+
+    The loop makes progress while the composed token is active, then stops once the
+    random condition, indirect counter poll, or timeout cancels it.
+    """
     token = ConditionToken(lambda: randint(1, 100_000) == 1984) + CounterToken(400_000, direct=False) + TimeoutToken(1)
     counter = 0
 

tests/units/test_errors.py

@@ -13,13 +13,21 @@
 
 
 def test_exception_inheritance_hierarchy():
+    """Specialized cancellation errors share the common cancellation base class."""
     assert issubclass(ConditionCancellationError, CancellationError)
     assert issubclass(TimeoutCancellationError, CancellationError)
     assert issubclass(CounterCancellationError, CancellationError)
     assert issubclass(ImpossibleCancelError, CancellationError)
 
 
 def test_exception_inheritance_hierarchy_from_view_of_tokens_classes():
+    """
+    Concrete token classes expose their configured cancellation exception types.
+
+    Specialized token exceptions remain compatible with the base error exposed by
+    SimpleToken, and DefaultToken exposes the error used by its impossible-cancel
+    paths.
+    """
     assert issubclass(ConditionToken.exception, SimpleToken.exception)
     assert issubclass(TimeoutToken.exception, SimpleToken.exception)
     assert issubclass(CounterToken.exception, SimpleToken.exception)