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/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. diff --git a/docs/types_of_tokens/ConditionToken.md b/docs/types_of_tokens/ConditionToken.md index 2661c2b..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/). 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..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/) 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..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/): +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..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/) -> `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..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/) -- [`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..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/) 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..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/) 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`. diff --git a/mkdocs.yml b/mkdocs.yml index 25a3a06..47bbbbb 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -33,6 +33,10 @@ nav: - ConditionToken: types_of_tokens/ConditionToken.md - TimeoutToken: types_of_tokens/TimeoutToken.md - CounterToken: types_of_tokens/CounterToken.md + - Ecosystem: + - About the ecosystem: ecosystem/about_ecosystem.md + - Projects: + - Subprocess Management: ecosystem/projects/subprocess_management.md markdown_extensions: - pymdownx.highlight: anchor_linenums: true 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" }, ]