Merge pull request #57 from mutating/develop

0.0.41

Author: pomponchik

.gitignore

@@ -19,3 +19,4 @@ html
 .claude
 CLAUDE.md
 AGENTS.md
+site

cantok/tokens/abstract/abstract_token.py

@@ -3,6 +3,8 @@
 from time import sleep
 from typing import Any, Dict, List, Optional, Union
 
+from printo import describe_call, not_none
+
 from cantok.errors import CancellationError
 from cantok.tokens.abstract.cancel_cause import CancelCause
 from cantok.tokens.abstract.report import CancellationReport
@@ -64,32 +66,27 @@ def __init__(self, *tokens: 'AbstractToken', cancelled: bool = False, doc: Optio
         self._lock: RLock = RLock()
 
     def __repr__(self) -> str:
-        chunks = []
         superpower = self._text_representation_of_superpower()
-        if superpower:
-            chunks.append(superpower)
-        other_tokens = ', '.join([repr(x) for x in self._tokens])
-        if other_tokens:
-            chunks.append(other_tokens)
         report = self._get_report(direct=False)
-        extra_kwargs: Dict[str, Any]
-        if report.cause == CancelCause.NOT_CANCELLED:
-            extra_kwargs = {}
-        elif report.from_token is self and report.cause == CancelCause.CANCELLED:
-            extra_kwargs = {'cancelled': True}
-        else:
-            extra_kwargs = {}
-        extra_kwargs.update(**(self._get_extra_kwargs()))
-        if self.doc is not None:
-            extra_kwargs['doc'] = self.doc
-        text_representation_of_extra_kwargs = self._text_representation_of_kwargs(
-            **extra_kwargs,
+        cancelled = report.from_token is self and report.cause == CancelCause.CANCELLED
+
+        return describe_call(
+            type(self).__name__,
+            [superpower, *self._tokens],
+            {
+                'cancelled': cancelled,
+                **self._get_extra_kwargs(),
+                'doc': self.doc,
+            },
+            filters={
+                0: lambda argument: bool(argument),
+                'cancelled': lambda argument: bool(argument),
+                'doc': not_none,
+            },
+            placeholders={
+                0: superpower,
+            },
         )
-        if text_representation_of_extra_kwargs:
-            chunks.append(text_representation_of_extra_kwargs)
-
-        glued_chunks = ', '.join(chunks)
-        return f'{type(self).__name__}({glued_chunks})'
 
     def __str__(self) -> str:
         cancelled_flag = (

cantok/tokens/counter_token.py

@@ -1,9 +1,16 @@
+import sys
 from typing import Any, Dict, Optional
 
+if sys.version_info < (3, 13):  # pragma: no cover
+    from typing_extensions import deprecated
+else:  # pragma: no cover
+    from warnings import deprecated
+
 from cantok import AbstractToken, ConditionToken
 from cantok.errors import CounterCancellationError
 
 
+@deprecated('CounterToken is deprecated and will be removed in a future release.')
 class CounterToken(ConditionToken):
     """
     A token that cancels automatically after a fixed number of iterations.

docs/types_of_tokens/CounterToken.md

@@ -1,3 +1,5 @@
+> ⚠️ `CounterToken` is deprecated. A new mechanism for limiting attempts and iterations will be introduced in future releases.
+
 `CounterToken` is the least intuitive of the tokens provided by this library. Do not use it if you are not sure that you understand how it works. However, it can be very useful in situations where you want to limit the number of attempts to perform an operation.
 
 `CounterToken` is initialized with an integer greater than or equal to zero. Each time cancellation is checked, this number is decremented by one. When this number becomes zero, the token is considered cancelled:

pyproject.toml

@@ -4,14 +4,15 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cantok"
-version = "0.0.40"
+version = "0.0.41"
 authors = [{ name = "Evgeniy Blinov", email = "zheni-b@yandex.ru" }]
 description = 'Implementation of the "Cancellation Token" pattern'
 readme = "README.md"
 requires-python = ">=3.8"
 dependencies = [
+    'printo>=0.0.28',
     'transfunctions>=0.0.12',
-    'typing_extensions ; python_version <= "3.9"',
+    'typing_extensions>=4.5.0 ; python_version < "3.13"',
 ]
 classifiers = [
     "Operating System :: OS Independent",
@@ -33,8 +34,9 @@ classifiers = [
     'License :: OSI Approved :: MIT License',
     'Intended Audience :: Developers',
     'Topic :: Software Development :: Libraries',
+    'Typing :: Typed',
 ]
-keywords = ['cancellation tokens', 'parallel programming', 'concurrency']
+keywords = ['cancellation tokens', 'parallel programming', 'concurrency', 'context', 'go context']
 
 [tool.setuptools.package-data]
 "cantok" = ["py.typed"]

tests/units/tokens/test_counter_token.py

@@ -6,6 +6,11 @@
 from cantok.tokens.abstract.abstract_token import CancelCause, CancellationReport
 
 
+def test_counter_token_is_deprecated():
+    with pytest.warns(DeprecationWarning, match='CounterToken is deprecated'):
+        CounterToken(1)
+
+
 @pytest.mark.parametrize(
     'iterations',
     [