Merge pull request #49 from pomponchik/develop

0.0.35

Author: pomponchik

.github/ISSUE_TEMPLATE/documentation.md

@@ -8,7 +8,7 @@ assignees: pomponchik
 
 ## It's cool that you're here!
 
-Documentation is an important part of the project, we strive to make it high-quality and keep it up to date. Please adjust this template by outlining your proposal.
+Documentation is an important part of the project; we strive to make it high-quality and keep it up to date. Please adjust this template by outlining your proposal.
 
 
 ## Type of action
@@ -18,7 +18,7 @@ What do you want to do: remove something, add it, or change it?
 
 ## Where?
 
-Specify which part of the documentation you want to make a change to? For example, the name of an existing documentation section or the line number in a file `README.md`.
+Specify which part of the documentation you want to make a change to. For example, the name of an existing documentation section or the line number in a file `README.md`.
 
 
 ## The essence

.gitignore

@@ -16,3 +16,4 @@ test.py
 html
 .qwen
 .claude
+CLAUDE.md

README.md

@@ -18,7 +18,7 @@
 ![logo](https://raw.githubusercontent.com/pomponchik/cantok/main/docs/assets/logo_5.png)
 
 
-Cancellation Token is a pattern that allows us to refuse to continue calculations that we no longer need. It is implemented out of the box in many programming languages, for example in [C#](https://learn.microsoft.com/en-us/dotnet/api/system.threading.cancellationtoken) and in [Go](https://pkg.go.dev/context). However, there was still no sane implementation in Python, until the [cantok](https://github.com/pomponchik/cantok) library.
+Cancellation Token is a pattern that allows us to cancel calculations that we no longer need. It is implemented out of the box in many programming languages, for example in [C#](https://learn.microsoft.com/en-us/dotnet/api/system.threading.cancellationtoken) and in [Go](https://pkg.go.dev/context). However, there was still no sane implementation in Python, until the [cantok](https://github.com/pomponchik/cantok) library appeared.
 
 
 ## Quick start

cantok/tokens/abstract/abstract_token.py

@@ -11,6 +11,34 @@
 
 
 class AbstractToken(ABC):
+    """
+    Abstract base class for all cancellation tokens.
+
+    A cancellation token represents a signal that can be used to cooperatively
+    cancel a long-running operation. Most subclasses add an automatic cancellation
+    condition (superpower) evaluated on every check; SimpleToken and DefaultToken
+    rely on manual cancellation only.
+
+    Tokens can be composed with the + operator: the resulting token is cancelled
+    when any of the combined tokens is cancelled.
+
+    Use AbstractToken as a type hint when a function accepts any token type.
+    Pass DefaultToken() as the default to make the token optional:
+
+    >>> def run(token: AbstractToken = DefaultToken()) -> bool:
+    ...     return token.keep_on()
+    >>> run()                        # DefaultToken never cancels
+    True
+    >>> run(SimpleToken().cancel())  # cancelled token passed explicitly
+    False
+
+    The idiomatic loop pattern:
+
+    >>> token = SimpleToken()
+    >>> while token:
+    ...     ...  # loop exits when token is cancelled
+    """
+
     exception = CancellationError
     _rollback_if_nondirect_polling = False
 
@@ -112,6 +140,20 @@ def __bool__(self) -> bool:
 
     @property
     def cancelled(self) -> bool:
+        """
+        Whether the token is currently cancelled.
+
+        Evaluated dynamically on each access, taking into account the token's own
+        cancellation rules and all embedded tokens. Setting to True cancels the token;
+        setting to False on an already cancelled token raises ValueError.
+
+        >>> token = SimpleToken()
+        >>> token.cancelled
+        False
+        >>> token.cancel()
+        >>> token.cancelled
+        True
+        """
         return self.is_cancelled()
 
     @cancelled.setter
@@ -123,12 +165,53 @@ def cancelled(self, new_value: bool) -> None:
                 raise ValueError('You cannot restore a cancelled token.')
 
     def keep_on(self) -> bool:
+        """
+        Returns True if the token is not cancelled, False otherwise.
+        The opposite of is_cancelled().
+
+        >>> token = SimpleToken()
+        >>> token.keep_on()
+        True
+        >>> token.cancel()
+        >>> token.keep_on()
+        False
+        """
         return not self.is_cancelled()
 
     def is_cancelled(self, direct: bool = True) -> bool:
+        """
+        Returns True if the token is cancelled, False otherwise.
+
+        :param direct: When False, tokens with rollback behaviour (e.g. CounterToken
+                       with direct=True) do not apply their side effects while being
+                       polled indirectly through a parent token. Defaults to True.
+
+        >>> token = SimpleToken()
+        >>> token.is_cancelled()
+        False
+        >>> token.cancel()
+        >>> token.is_cancelled()
+        True
+        """
         return self._get_report(direct=direct).cause != CancelCause.NOT_CANCELLED
 
     def wait(self, step: Union[int, float] = 0.0001, timeout: Optional[Union[int, float]] = None) -> Awaitable:  # type: ignore[type-arg]
+        """
+        Waits until the token is cancelled.
+
+        When used with ``await``, runs non-blocking inside an asyncio event loop.
+        When called without ``await``, blocks the current thread.
+
+        :param step: Interval between status checks, in seconds. Defaults to 0.0001.
+        :param timeout: Maximum time to wait, in seconds. If exceeded,
+                        raises TimeoutCancellationError. Defaults to None (no limit).
+
+        >>> import asyncio
+        >>>
+        >>> token = TimeoutToken(5)
+        >>> token.wait()   # blocks for ~5 seconds, then returns
+        >>> asyncio.run(token.wait())   # non-blocking, inside an asyncio event loop
+        """
         if step < 0:
             raise ValueError('The token polling iteration time cannot be less than zero.')
         if timeout is not None and timeout < 0:
@@ -146,10 +229,33 @@ def wait(self, step: Union[int, float] = 0.0001, timeout: Optional[Union[int, fl
         return WaitCoroutineWrapper(step, self + token, token)
 
     def cancel(self) -> 'AbstractToken':
+        """
+        Cancels the token. Returns the token itself to allow method chaining.
+
+        Cancellation is irreversible: once cancelled, the token cannot be restored.
+
+        >>> token = SimpleToken()
+        >>> token.cancel()
+        >>> token.cancelled
+        True
+        """
         self._cancelled = True
         return self
 
     def check(self) -> None:
+        """
+        Raises an exception if the token is cancelled; does nothing otherwise.
+
+        The exception type depends on the cancellation cause:
+        - Manual cancellation via cancel() raises CancellationError.
+        - Automatic cancellation by a specific token type raises the corresponding
+          subclass (e.g. TimeoutCancellationError for TimeoutToken).
+
+        >>> token = SimpleToken()
+        >>> token.check()   # nothing happens
+        >>> token.cancel()
+        >>> token.check()   # raises CancellationError
+        """
         with self._lock:
             report = self._get_report()
 

cantok/tokens/condition_token.py

@@ -6,6 +6,31 @@
 
 
 class ConditionToken(AbstractToken):
+    """
+    A token that cancels automatically when a condition function returns True.
+
+    The condition function is evaluated on every cancellation check. Once it
+    returns True, the result is cached by default and the token stays cancelled.
+
+    :param function: A callable returning bool. Called on each cancellation check.
+    :param suppress_exceptions: If True (default), exceptions from the function
+                                are swallowed and treated as the default value.
+    :param default: Value to use when the function raises and suppress_exceptions
+                    is True. Defaults to False.
+    :param before: Callable invoked before the condition function on each check.
+    :param after: Callable invoked after the condition function on each check.
+    :param caching: If True (default), the token stays cancelled once the
+                    condition has returned True, without re-evaluating it.
+
+    >>> items = []
+    >>> token = ConditionToken(lambda: len(items) >= 3)
+    >>> token.cancelled
+    False
+    >>> items += [1, 2, 3]
+    >>> token.cancelled
+    True
+    """
+
     exception = ConditionCancellationError
 
     def __init__(self, function: Callable[[], bool], *tokens: AbstractToken, cancelled: bool = False, suppress_exceptions: bool = True, default: bool = False, before: Callable[[], Any] = lambda: None, after: Callable[[], Any] = lambda: None, caching: bool = True):  # noqa: PLR0913
@@ -25,7 +50,7 @@ def _superpower(self) -> bool:
 
         if not self._suppress_exceptions:
             self._before()
-            result = self.run_function()
+            result = self._run_function()
             self._after()
             return result
 
@@ -34,13 +59,13 @@ def _superpower(self) -> bool:
         with suppress(Exception):
             self._before()
         with suppress(Exception):
-            result = self.run_function()
+            result = self._run_function()
         with suppress(Exception):
             self._after()
 
         return result
 
-    def run_function(self) -> bool:
+    def _run_function(self) -> bool:
         result = self._function()
 
         if not isinstance(result, bool):

cantok/tokens/counter_token.py

@@ -5,6 +5,23 @@
 
 
 class CounterToken(ConditionToken):
+    """
+    A token that cancels automatically after a fixed number of iterations.
+
+    The internal counter decrements on each direct cancellation check. When it
+    reaches zero, the token is cancelled. Useful for limiting the number of
+    iterations of a loop without tracking state externally.
+
+    :param counter: Number of iterations before cancellation. Must be >= 0.
+    :param direct: If True (default), counter decrements even when polled
+                   indirectly through a parent token. If False, indirect polls
+                   are rolled back, so only direct checks consume the counter.
+
+    >>> token = CounterToken(3)
+    >>> while token:
+    ...     ...  # loop body executes exactly 3 times
+    """
+
     exception = CounterCancellationError
 
     def __init__(self, counter: int, *tokens: AbstractToken, cancelled: bool = False, direct: bool = True):

cantok/tokens/default_token.py

@@ -3,6 +3,21 @@
 
 
 class DefaultToken(AbstractToken):
+    """
+    An immutable token that never cancels.
+
+    Useful as a neutral default argument: a function that accepts a token can
+    receive a DefaultToken when no real cancellation is needed, without
+    requiring None checks. Calling cancel() raises ImpossibleCancelError.
+
+    >>> def run(token: AbstractToken = DefaultToken()) -> bool:
+    ...     return token.keep_on()
+    >>> run()               # True — DefaultToken never cancels
+    True
+    >>> run(SimpleToken())  # True — SimpleToken not yet cancelled
+    True
+    """
+
     exception = ImpossibleCancelError
 
     def __init__(self) -> None:

cantok/tokens/simple_token.py

@@ -3,6 +3,18 @@
 
 
 class SimpleToken(AbstractToken):
+    """
+    A basic cancellation token with no automatic cancellation condition.
+
+    Can only be cancelled explicitly by calling cancel() or setting
+    cancelled = True. Useful as a manual stop signal passed between threads.
+
+    >>> token = SimpleToken()
+    >>> token.cancel()
+    >>> token.cancelled
+    True
+    """
+
     exception = CancellationError
 
     def _superpower(self) -> bool:

cantok/tokens/timeout_token.py

@@ -6,6 +6,28 @@
 
 
 class TimeoutToken(ConditionToken):
+    """
+    A token that cancels automatically after a specified duration.
+
+    The timeout is measured from the moment the token is created. When the
+    deadline is reached, any cancellation check will return True and subsequent
+    check() calls will raise TimeoutCancellationError.
+
+    :param timeout: Duration in seconds before cancellation. Must be >= 0.
+    :param monotonic: If True, uses time.monotonic_ns() instead of
+                      time.perf_counter(), which is unaffected by system
+                      clock adjustments. Defaults to False.
+
+    >>> import time
+    >>>
+    >>> token = TimeoutToken(0.1)
+    >>> token.cancelled
+    False
+    >>> time.sleep(0.2)
+    >>> token.cancelled
+    True
+    """
+
     exception = TimeoutCancellationError
 
     def __init__(self, timeout: Union[int, float], *tokens: AbstractToken, cancelled: bool = False, monotonic: bool = False):

docs/ecosystem/projects/regular_functions_calling.md

@@ -38,7 +38,7 @@ metronome = Metronome(0.2, lambda: None, token=TimeoutToken(1))
 metronome.start()
 print(metronome.stopped)
 #> False
-sleep(1.5)  # Here I specify a little more time than in the constructor of the token itself, since a small margin is needed for operations related to the creation of the metronome object itself.
+sleep(1.5)  # We specify a slightly longer sleep time than the token timeout to allow for the overhead of creating the metronome object.
 print(metronome.stopped)
 #> True
 ```