From f306383d7515ffd39337ca48b5f728abdeff34c8 Mon Sep 17 00:00:00 2001 From: Evgeniy Blinov Date: Fri, 23 Feb 2024 23:31:09 +0300 Subject: [PATCH 1/8] documentation --- docs/quick_start.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/quick_start.md b/docs/quick_start.md index eda60ae..1ca0911 100644 --- a/docs/quick_start.md +++ b/docs/quick_start.md @@ -14,6 +14,6 @@ while token: print(counter) ``` -In this code, we use a token that describes several restrictions: on the [number of iterations](/types_of_tokens/CounterToken/) of the cycle, on [time](/types_of_tokens/TimeoutToken/), as well as on the [occurrence](/types_of_tokens/ConditionToken/) of a random unlikely event. When any of the indicated events occur, the cycle stops. +In this code, we use a token that describes several restrictions: on the [number of iterations](types_of_tokens/CounterToken.md) of the cycle, on [time](types_of_tokens/TimeoutToken.md), as well as on the [occurrence](types_of_tokens/ConditionToken.md) of a random unlikely event. When any of the indicated events occur, the cycle stops. In fact, the library's capabilities are much broader, read the documentation below. From 5673886568e67345ade73780ee215b4c2792a897 Mon Sep 17 00:00:00 2001 From: Evgeniy Blinov Date: Fri, 23 Feb 2024 23:36:33 +0300 Subject: [PATCH 2/8] documentation --- docs/types_of_tokens/ConditionToken.md | 2 +- docs/types_of_tokens/SimpleToken.md | 2 +- docs/what_are_tokens/cancel_and_read_the_status.md | 2 +- docs/what_are_tokens/exceptions.md | 8 ++++---- docs/what_are_tokens/in_general.md | 8 ++++---- docs/what_are_tokens/summation.md | 2 +- docs/what_are_tokens/waiting.md | 2 +- 7 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/types_of_tokens/ConditionToken.md b/docs/types_of_tokens/ConditionToken.md index 2661c2b..e887876 100644 --- a/docs/types_of_tokens/ConditionToken.md +++ b/docs/types_of_tokens/ConditionToken.md @@ -1,4 +1,4 @@ -`ConditionToken` has superpower: it can check arbitrary conditions. In addition to this, it can do all the same things as [`SimpleToken`](/types_of_tokens/SimpleToken/). The condition is a function that returns an answer to the question "has the token been canceled" (`True`/`False`), it is passed to the token as the first required argument during initialization: +`ConditionToken` has superpower: it can check arbitrary conditions. In addition to this, it can do all the same things as [`SimpleToken`](types_of_tokens/SimpleToken.md). The condition is a function that returns an answer to the question "has the token been canceled" (`True`/`False`), it is passed to the token as the first required argument during initialization: ```python from cantok import ConditionToken diff --git a/docs/types_of_tokens/SimpleToken.md b/docs/types_of_tokens/SimpleToken.md index c2db4aa..924a038 100644 --- a/docs/types_of_tokens/SimpleToken.md +++ b/docs/types_of_tokens/SimpleToken.md @@ -18,4 +18,4 @@ print(repr(CounterToken(5) + TimeoutToken(5))) # SimpleToken(CounterToken(5, direct=True), TimeoutToken(5, monotonic=False)) ``` -There is not much more to tell about it if you have read [the story](/what_are_tokens/in_general/) about tokens in general. +There is not much more to tell about it if you have read [the story](what_are_tokens/in_general.md) about tokens in general. diff --git a/docs/what_are_tokens/cancel_and_read_the_status.md b/docs/what_are_tokens/cancel_and_read_the_status.md index cb08d05..4df8c3f 100644 --- a/docs/what_are_tokens/cancel_and_read_the_status.md +++ b/docs/what_are_tokens/cancel_and_read_the_status.md @@ -9,7 +9,7 @@ token.cancel() print(token.cancelled) # True ``` -The cancelled attribute is dynamically calculated and takes into account, among other things, specific conditions that are checked by a specific token. Here is an example with a [token that measures time](/types_of_tokens/TimeoutToken/): +The cancelled attribute is dynamically calculated and takes into account, among other things, specific conditions that are checked by a specific token. Here is an example with a [token that measures time](types_of_tokens/TimeoutToken.md): ```python from time import sleep diff --git a/docs/what_are_tokens/exceptions.md b/docs/what_are_tokens/exceptions.md index a007864..d74195a 100644 --- a/docs/what_are_tokens/exceptions.md +++ b/docs/what_are_tokens/exceptions.md @@ -11,10 +11,10 @@ token.check() Each type of token has a corresponding type of exception that can be raised in this case: -- [`SimpleToken`](/types_of_tokens/SimpleToken/) -> `CancellationError` -- [`ConditionToken`](/types_of_tokens/ConditionToken/) -> `ConditionCancellationError` -- [`TimeoutToken`](/types_of_tokens/TimeoutToken/) -> `TimeoutCancellationError` -- [`CounterToken`](/types_of_tokens/CounterToken/) -> `CounterCancellationError` +- [`SimpleToken`](types_of_tokens/SimpleToken.md) -> `CancellationError` +- [`ConditionToken`](types_of_tokens/ConditionToken.md) -> `ConditionCancellationError` +- [`TimeoutToken`](types_of_tokens/TimeoutToken.md) -> `TimeoutCancellationError` +- [`CounterToken`](types_of_tokens/CounterToken.md) -> `CounterCancellationError` When you call the `check()` method on any token, one of two things will happen. If it (or any of the tokens nested in it) was canceled by calling the `cancel()` method, `CancellationError` will always be raised. But if the cancellation occurred as a result of the unique ability of the token, such as for `TimeoutToken` - timeout expiration, then an exception specific to this type of token will be raised. diff --git a/docs/what_are_tokens/in_general.md b/docs/what_are_tokens/in_general.md index aff2faa..0d2307f 100644 --- a/docs/what_are_tokens/in_general.md +++ b/docs/what_are_tokens/in_general.md @@ -2,10 +2,10 @@ A token is an object that can tell you whether to continue the action you starte There are 4 types of tokens in this library: -- [`SimpleToken`](/types_of_tokens/SimpleToken/) -- [`ConditionToken`](/types_of_tokens/ConditionToken/) -- [`TimeoutToken`](/types_of_tokens/TimeoutToken/) -- [`CounterToken`](/types_of_tokens/CounterToken/) +- [`SimpleToken`](types_of_tokens/SimpleToken.md) +- [`ConditionToken`](types_of_tokens/ConditionToken.md) +- [`TimeoutToken`](types_of_tokens/TimeoutToken.md) +- [`CounterToken`](types_of_tokens/CounterToken.md) Each of them has its own characteristics, but they also have something in common: diff --git a/docs/what_are_tokens/summation.md b/docs/what_are_tokens/summation.md index 0512d93..1e93934 100644 --- a/docs/what_are_tokens/summation.md +++ b/docs/what_are_tokens/summation.md @@ -1,4 +1,4 @@ -Any tokens can be summed up among themselves. The summation operation generates another [`SimpleToken`](/types_of_tokens/SimpleToken/) that includes the previous 2: +Any tokens can be summed up among themselves. The summation operation generates another [`SimpleToken`](types_of_tokens/SimpleToken.md) that includes the previous 2: ```python from cantok import SimpleToken, TimeoutToken diff --git a/docs/what_are_tokens/waiting.md b/docs/what_are_tokens/waiting.md index 456d253..7bd1c93 100644 --- a/docs/what_are_tokens/waiting.md +++ b/docs/what_are_tokens/waiting.md @@ -31,5 +31,5 @@ Yes, it looks like magic, it is magic. The method itself finds out how it was us In addition to the above, the `wait()` method has two optional arguments: -- **`timeout`** (`int` or `float`) - the maximum waiting time in seconds. If this time is exceeded, a [`TimeoutCancellationError` exception](/what_are_tokens/waiting/) will be raised. By default, the `timeout` is not set. +- **`timeout`** (`int` or `float`) - the maximum waiting time in seconds. If this time is exceeded, a [`TimeoutCancellationError` exception](what_are_tokens/waiting.md) will be raised. By default, the `timeout` is not set. - **`step`** (`int` or `float`, by default `0.0001`) - the duration of the iteration, once in which the token state is polled, in seconds. For obvious reasons, you cannot set this value to a number that exceeds the `timeout`. From 7c9f75c067ea742f774d33ebc1ed7ec2924044e6 Mon Sep 17 00:00:00 2001 From: Evgeniy Blinov Date: Fri, 23 Feb 2024 23:39:31 +0300 Subject: [PATCH 3/8] documentation --- docs/types_of_tokens/SimpleToken.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/types_of_tokens/SimpleToken.md b/docs/types_of_tokens/SimpleToken.md index 924a038..46c0f21 100644 --- a/docs/types_of_tokens/SimpleToken.md +++ b/docs/types_of_tokens/SimpleToken.md @@ -18,4 +18,4 @@ print(repr(CounterToken(5) + TimeoutToken(5))) # SimpleToken(CounterToken(5, direct=True), TimeoutToken(5, monotonic=False)) ``` -There is not much more to tell about it if you have read [the story](what_are_tokens/in_general.md) about tokens in general. +There is not much more to tell about it if you have read [the story](/what_are_tokens/in_general.md) about tokens in general. From e366d7144c372354987332d2d1a6e7323291acd9 Mon Sep 17 00:00:00 2001 From: Evgeniy Blinov Date: Fri, 23 Feb 2024 23:42:49 +0300 Subject: [PATCH 4/8] documentation --- docs/types_of_tokens/SimpleToken.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/types_of_tokens/SimpleToken.md b/docs/types_of_tokens/SimpleToken.md index 46c0f21..924a038 100644 --- a/docs/types_of_tokens/SimpleToken.md +++ b/docs/types_of_tokens/SimpleToken.md @@ -18,4 +18,4 @@ print(repr(CounterToken(5) + TimeoutToken(5))) # SimpleToken(CounterToken(5, direct=True), TimeoutToken(5, monotonic=False)) ``` -There is not much more to tell about it if you have read [the story](/what_are_tokens/in_general.md) about tokens in general. +There is not much more to tell about it if you have read [the story](what_are_tokens/in_general.md) about tokens in general. From 5292d085eecf0df0fa416b225254ff6072f7af28 Mon Sep 17 00:00:00 2001 From: Evgeniy Blinov Date: Fri, 23 Feb 2024 23:53:51 +0300 Subject: [PATCH 5/8] documentation --- docs/types_of_tokens/ConditionToken.md | 2 +- docs/types_of_tokens/SimpleToken.md | 2 +- docs/what_are_tokens/cancel_and_read_the_status.md | 2 +- docs/what_are_tokens/exceptions.md | 8 ++++---- docs/what_are_tokens/in_general.md | 8 ++++---- docs/what_are_tokens/summation.md | 2 +- docs/what_are_tokens/waiting.md | 2 +- 7 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/types_of_tokens/ConditionToken.md b/docs/types_of_tokens/ConditionToken.md index e887876..a05a709 100644 --- a/docs/types_of_tokens/ConditionToken.md +++ b/docs/types_of_tokens/ConditionToken.md @@ -1,4 +1,4 @@ -`ConditionToken` has superpower: it can check arbitrary conditions. In addition to this, it can do all the same things as [`SimpleToken`](types_of_tokens/SimpleToken.md). The condition is a function that returns an answer to the question "has the token been canceled" (`True`/`False`), it is passed to the token as the first required argument during initialization: +`ConditionToken` has superpower: it can check arbitrary conditions. In addition to this, it can do all the same things as [`SimpleToken`](../types_of_tokens/SimpleToken.md). The condition is a function that returns an answer to the question "has the token been canceled" (`True`/`False`), it is passed to the token as the first required argument during initialization: ```python from cantok import ConditionToken diff --git a/docs/types_of_tokens/SimpleToken.md b/docs/types_of_tokens/SimpleToken.md index 924a038..c984dbc 100644 --- a/docs/types_of_tokens/SimpleToken.md +++ b/docs/types_of_tokens/SimpleToken.md @@ -18,4 +18,4 @@ print(repr(CounterToken(5) + TimeoutToken(5))) # SimpleToken(CounterToken(5, direct=True), TimeoutToken(5, monotonic=False)) ``` -There is not much more to tell about it if you have read [the story](what_are_tokens/in_general.md) about tokens in general. +There is not much more to tell about it if you have read [the story](../what_are_tokens/in_general.md) about tokens in general. diff --git a/docs/what_are_tokens/cancel_and_read_the_status.md b/docs/what_are_tokens/cancel_and_read_the_status.md index 4df8c3f..fbb2117 100644 --- a/docs/what_are_tokens/cancel_and_read_the_status.md +++ b/docs/what_are_tokens/cancel_and_read_the_status.md @@ -9,7 +9,7 @@ token.cancel() print(token.cancelled) # True ``` -The cancelled attribute is dynamically calculated and takes into account, among other things, specific conditions that are checked by a specific token. Here is an example with a [token that measures time](types_of_tokens/TimeoutToken.md): +The cancelled attribute is dynamically calculated and takes into account, among other things, specific conditions that are checked by a specific token. Here is an example with a [token that measures time](../types_of_tokens/TimeoutToken.md): ```python from time import sleep diff --git a/docs/what_are_tokens/exceptions.md b/docs/what_are_tokens/exceptions.md index d74195a..8fe7c28 100644 --- a/docs/what_are_tokens/exceptions.md +++ b/docs/what_are_tokens/exceptions.md @@ -11,10 +11,10 @@ token.check() Each type of token has a corresponding type of exception that can be raised in this case: -- [`SimpleToken`](types_of_tokens/SimpleToken.md) -> `CancellationError` -- [`ConditionToken`](types_of_tokens/ConditionToken.md) -> `ConditionCancellationError` -- [`TimeoutToken`](types_of_tokens/TimeoutToken.md) -> `TimeoutCancellationError` -- [`CounterToken`](types_of_tokens/CounterToken.md) -> `CounterCancellationError` +- [`SimpleToken`](../types_of_tokens/SimpleToken.md) -> `CancellationError` +- [`ConditionToken`](../types_of_tokens/ConditionToken.md) -> `ConditionCancellationError` +- [`TimeoutToken`](../types_of_tokens/TimeoutToken.md) -> `TimeoutCancellationError` +- [`CounterToken`](../types_of_tokens/CounterToken.md) -> `CounterCancellationError` When you call the `check()` method on any token, one of two things will happen. If it (or any of the tokens nested in it) was canceled by calling the `cancel()` method, `CancellationError` will always be raised. But if the cancellation occurred as a result of the unique ability of the token, such as for `TimeoutToken` - timeout expiration, then an exception specific to this type of token will be raised. diff --git a/docs/what_are_tokens/in_general.md b/docs/what_are_tokens/in_general.md index 0d2307f..25f2779 100644 --- a/docs/what_are_tokens/in_general.md +++ b/docs/what_are_tokens/in_general.md @@ -2,10 +2,10 @@ A token is an object that can tell you whether to continue the action you starte There are 4 types of tokens in this library: -- [`SimpleToken`](types_of_tokens/SimpleToken.md) -- [`ConditionToken`](types_of_tokens/ConditionToken.md) -- [`TimeoutToken`](types_of_tokens/TimeoutToken.md) -- [`CounterToken`](types_of_tokens/CounterToken.md) +- [`SimpleToken`](../types_of_tokens/SimpleToken.md) +- [`ConditionToken`](../types_of_tokens/ConditionToken.md) +- [`TimeoutToken`](../types_of_tokens/TimeoutToken.md) +- [`CounterToken`](../types_of_tokens/CounterToken.md) Each of them has its own characteristics, but they also have something in common: diff --git a/docs/what_are_tokens/summation.md b/docs/what_are_tokens/summation.md index 1e93934..641c17f 100644 --- a/docs/what_are_tokens/summation.md +++ b/docs/what_are_tokens/summation.md @@ -1,4 +1,4 @@ -Any tokens can be summed up among themselves. The summation operation generates another [`SimpleToken`](types_of_tokens/SimpleToken.md) that includes the previous 2: +Any tokens can be summed up among themselves. The summation operation generates another [`SimpleToken`](../types_of_tokens/SimpleToken.md) that includes the previous 2: ```python from cantok import SimpleToken, TimeoutToken diff --git a/docs/what_are_tokens/waiting.md b/docs/what_are_tokens/waiting.md index 7bd1c93..22bcebe 100644 --- a/docs/what_are_tokens/waiting.md +++ b/docs/what_are_tokens/waiting.md @@ -31,5 +31,5 @@ Yes, it looks like magic, it is magic. The method itself finds out how it was us In addition to the above, the `wait()` method has two optional arguments: -- **`timeout`** (`int` or `float`) - the maximum waiting time in seconds. If this time is exceeded, a [`TimeoutCancellationError` exception](what_are_tokens/waiting.md) will be raised. By default, the `timeout` is not set. +- **`timeout`** (`int` or `float`) - the maximum waiting time in seconds. If this time is exceeded, a [`TimeoutCancellationError` exception](../what_are_tokens/waiting.md) will be raised. By default, the `timeout` is not set. - **`step`** (`int` or `float`, by default `0.0001`) - the duration of the iteration, once in which the token state is polled, in seconds. For obvious reasons, you cannot set this value to a number that exceeds the `timeout`. From 9b6445abb263a6a470b7c93e5e3934a13338bee4 Mon Sep 17 00:00:00 2001 From: Evgeniy Blinov Date: Sat, 24 Feb 2024 00:04:13 +0300 Subject: [PATCH 6/8] new version tag --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index f228b15..043421e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "cantok" -version = "0.0.21" +version = "0.0.22" authors = [ { name="Evgeniy Blinov", email="zheni-b@yandex.ru" }, ] From d81db61a54e09d0333660498bc8663a019efbcb9 Mon Sep 17 00:00:00 2001 From: Evgeniy Blinov Date: Sat, 24 Feb 2024 00:08:44 +0300 Subject: [PATCH 7/8] documentation --- docs/ecosystem/subprocess_management.md | 1 + mkdocs.yml | 2 ++ 2 files changed, 3 insertions(+) create mode 100644 docs/ecosystem/subprocess_management.md diff --git a/docs/ecosystem/subprocess_management.md b/docs/ecosystem/subprocess_management.md new file mode 100644 index 0000000..6e3a865 --- /dev/null +++ b/docs/ecosystem/subprocess_management.md @@ -0,0 +1 @@ +Subprocess Management diff --git a/mkdocs.yml b/mkdocs.yml index 25a3a06..d1610af 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -33,6 +33,8 @@ nav: - ConditionToken: types_of_tokens/ConditionToken.md - TimeoutToken: types_of_tokens/TimeoutToken.md - CounterToken: types_of_tokens/CounterToken.md + - Ecosystem: + - Subprocess Management: ecosystem/subprocess_management.md markdown_extensions: - pymdownx.highlight: anchor_linenums: true From f0d73c281906a8a43816e3bafa4a00c039925582 Mon Sep 17 00:00:00 2001 From: Evgeniy Blinov Date: Sat, 24 Feb 2024 00:28:47 +0300 Subject: [PATCH 8/8] documentation --- docs/ecosystem/about_ecosystem.md | 1 + docs/ecosystem/projects/subprocess_management.md | 13 +++++++++++++ docs/ecosystem/subprocess_management.md | 1 - mkdocs.yml | 4 +++- 4 files changed, 17 insertions(+), 2 deletions(-) create mode 100644 docs/ecosystem/about_ecosystem.md create mode 100644 docs/ecosystem/projects/subprocess_management.md delete mode 100644 docs/ecosystem/subprocess_management.md diff --git a/docs/ecosystem/about_ecosystem.md b/docs/ecosystem/about_ecosystem.md new file mode 100644 index 0000000..df9b084 --- /dev/null +++ b/docs/ecosystem/about_ecosystem.md @@ -0,0 +1 @@ +We recommend adding token support to all your libraries where possible. If you have written such a project or added token support to an existing project, please let us know by writing an [issue](https://github.com/pomponchik/cantok/issues/new). If possible, information about the project will be added here. diff --git a/docs/ecosystem/projects/subprocess_management.md b/docs/ecosystem/projects/subprocess_management.md new file mode 100644 index 0000000..172c776 --- /dev/null +++ b/docs/ecosystem/projects/subprocess_management.md @@ -0,0 +1,13 @@ +To work with subprocesses, there is a [`suby`](https://github.com/pomponchik/suby) library with support for cancellation tokens. It has a very simple syntax: + +```python +import suby + +suby('python', '-c', 'print("hello, world!")') +``` + +A token can be passed as an argument: + +```python +suby('python', '-c', 'import time; time.sleep(10_000)', token=TimeoutToken(1), catch_exceptions=True) +``` diff --git a/docs/ecosystem/subprocess_management.md b/docs/ecosystem/subprocess_management.md deleted file mode 100644 index 6e3a865..0000000 --- a/docs/ecosystem/subprocess_management.md +++ /dev/null @@ -1 +0,0 @@ -Subprocess Management diff --git a/mkdocs.yml b/mkdocs.yml index d1610af..47bbbbb 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -34,7 +34,9 @@ nav: - TimeoutToken: types_of_tokens/TimeoutToken.md - CounterToken: types_of_tokens/CounterToken.md - Ecosystem: - - Subprocess Management: ecosystem/subprocess_management.md + - About the ecosystem: ecosystem/about_ecosystem.md + - Projects: + - Subprocess Management: ecosystem/projects/subprocess_management.md markdown_extensions: - pymdownx.highlight: anchor_linenums: true