| Name | contextualwaiting JSON |
| Version |
1.0.2
JSON |
| download |
| home_page | |
| Summary | Contextual Waiting |
| upload_time | 2023-03-13 22:06:23 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8,<4.0 |
| license | LICENSE.txt |
| keywords |
python
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Contextual Waiting Module - contextualwaiting
This package provides support for enhanced context based waiting. The waiting code
patterns used are designed to present the best results in test stacktraces presented
when a wait fails. This makes the `contextualwaiting` module perfect for use with
test frameworks such as `pytest` and `testplus` that show code context in the error
report stack traces.
Another important aspect of the `contextualwaiting` module is that it uses `datetime`
timestamps and `timespan` for lengths of time so timeouts in error reporting are easier
to interpret.
```
Traceback (most recent call last):
File "/home/myron/repos/contextualwaiting/source/tests/test_wait_for_it.py", line 97, in test_basic_wait_for_it_timeout
future.result()
File "/usr/lib/python3.10/concurrent/futures/_base.py", line 451, in result
return self.__get_result()
File "/usr/lib/python3.10/concurrent/futures/_base.py", line 403, in __get_result
raise self._exception
File "/usr/lib/python3.10/concurrent/futures/thread.py", line 58, in run
result = self.fn(*self.args, **self.kwargs)
File "/home/myron/repos/contextualwaiting/source/tests/test_wait_for_it.py", line 88, in wait_task
ctxwait.wait_for_it(wait_helper, interval=.5, timeout=2)
File "/home/myron/repos/contextualwaiting/source/packages/ctxwait/waiting.py", line 103, in wait_for_it
raise toerr
TimeoutError: Timeout waiting for 'wait_helper':
timeout=2 start_time=2023-03-13 14:57:29.860302, end_time=2023-03-13 14:57:31.860302 now_time=2023-03-13 14:57:31.863681 time_diff=0:00:02.003379
```
The following is an example of how the `contextualwaiting` module is used.
```{python}
from ctxwait import WaitContext, wait_for_it
def some_wait_helper(wctx: WaitContext):
finished = False
// TODO: Check if something is finished, the code and variables used
// here will show up in any tracebacks from pytest or testplus
// because the timeout is being raised in the appropriate scope.
if not finished and wctx.final_attempt:
whatfor = "Test timeout"
toerr = wctx.create_timeout(whatfor)
raise toerr
return finished
wait_for_it(some_wait_helper)
```
The `wait_for_it` method has many different parameters that can be used to override the
behavior of the wait loop.
```{python}
def wait_for_it(looper: WaitCallback, *largs, what_for: Optional[str]=None, delay: float=DEFAULT_WAIT_DELAY,
interval: float=DEFAULT_WAIT_INTERVAL, timeout: float=DEFAULT_WAIT_TIMEOUT,
lkwargs: Dict[Any, Any]={}, wctx: Optional[WaitContext]=None):
"""
Provides for convenient mechanism to wait for criteria to be met before proceeding.
:param looper: A callback method that is repeatedly called while it returns `False` up-to
the end of a timeout period, and that will return `True` if a waited on
condition is met prior to a timeout condition being met.
:param largs: Arguements to pass to the looper callback function.
:param what_for: A breif description of what is being waited for.
:param delay: An initial time delay to consume before beginning the waiting process.
:param interval: A period of time to delay between rechecks of the wait conditon
:param timeout: The maximum period of time in seconds that should be waited before timing out.
:param lkwargs: Additional keyword arguments to pass to the looper function
:raises TimeoutError: A timeout error with details around the wait condition.
..note: The 'delay', 'interval' and 'timeout' parameters will be ignored if the 'wctx' parameter
is passed as the wctx (WaitContext) parameter includes these values with it.
"""
...
```
The `wait_for_it` function must be passed a method that follows the `WaitCallback` protocol. The function
can have variable arguments and keyword arguements but the first parameter to the `WaitCallback` method
must be a `WaitContext` object.
Raw data
{
"_id": null,
"home_page": "",
"name": "contextualwaiting",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "python",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/66/bf/b9e7e6bed368347721158fdf37a52f394d89e17322fe9306fc0db1a2f4cd/contextualwaiting-1.0.2.tar.gz",
"platform": null,
"description": "# Contextual Waiting Module - contextualwaiting\n\nThis package provides support for enhanced context based waiting. The waiting code\npatterns used are designed to present the best results in test stacktraces presented\nwhen a wait fails. This makes the `contextualwaiting` module perfect for use with\ntest frameworks such as `pytest` and `testplus` that show code context in the error\nreport stack traces.\n\nAnother important aspect of the `contextualwaiting` module is that it uses `datetime`\ntimestamps and `timespan` for lengths of time so timeouts in error reporting are easier\nto interpret.\n\n```\n Traceback (most recent call last):\n File \"/home/myron/repos/contextualwaiting/source/tests/test_wait_for_it.py\", line 97, in test_basic_wait_for_it_timeout\n future.result()\n File \"/usr/lib/python3.10/concurrent/futures/_base.py\", line 451, in result\n return self.__get_result()\n File \"/usr/lib/python3.10/concurrent/futures/_base.py\", line 403, in __get_result\n raise self._exception\n File \"/usr/lib/python3.10/concurrent/futures/thread.py\", line 58, in run\n result = self.fn(*self.args, **self.kwargs)\n File \"/home/myron/repos/contextualwaiting/source/tests/test_wait_for_it.py\", line 88, in wait_task\n ctxwait.wait_for_it(wait_helper, interval=.5, timeout=2)\n File \"/home/myron/repos/contextualwaiting/source/packages/ctxwait/waiting.py\", line 103, in wait_for_it\n raise toerr\n TimeoutError: Timeout waiting for 'wait_helper':\n timeout=2 start_time=2023-03-13 14:57:29.860302, end_time=2023-03-13 14:57:31.860302 now_time=2023-03-13 14:57:31.863681 time_diff=0:00:02.003379\n```\n\nThe following is an example of how the `contextualwaiting` module is used.\n\n```{python}\n\n from ctxwait import WaitContext, wait_for_it\n\n def some_wait_helper(wctx: WaitContext):\n finished = False\n\n // TODO: Check if something is finished, the code and variables used\n // here will show up in any tracebacks from pytest or testplus\n // because the timeout is being raised in the appropriate scope.\n\n if not finished and wctx.final_attempt:\n whatfor = \"Test timeout\"\n toerr = wctx.create_timeout(whatfor)\n raise toerr\n\n return finished\n\n wait_for_it(some_wait_helper)\n```\n\nThe `wait_for_it` method has many different parameters that can be used to override the\nbehavior of the wait loop.\n\n```{python}\n\n def wait_for_it(looper: WaitCallback, *largs, what_for: Optional[str]=None, delay: float=DEFAULT_WAIT_DELAY,\n interval: float=DEFAULT_WAIT_INTERVAL, timeout: float=DEFAULT_WAIT_TIMEOUT,\n lkwargs: Dict[Any, Any]={}, wctx: Optional[WaitContext]=None):\n \"\"\"\n Provides for convenient mechanism to wait for criteria to be met before proceeding.\n\n :param looper: A callback method that is repeatedly called while it returns `False` up-to\n the end of a timeout period, and that will return `True` if a waited on\n condition is met prior to a timeout condition being met.\n :param largs: Arguements to pass to the looper callback function.\n :param what_for: A breif description of what is being waited for.\n :param delay: An initial time delay to consume before beginning the waiting process.\n :param interval: A period of time to delay between rechecks of the wait conditon\n :param timeout: The maximum period of time in seconds that should be waited before timing out.\n :param lkwargs: Additional keyword arguments to pass to the looper function\n\n :raises TimeoutError: A timeout error with details around the wait condition.\n\n ..note: The 'delay', 'interval' and 'timeout' parameters will be ignored if the 'wctx' parameter\n is passed as the wctx (WaitContext) parameter includes these values with it.\n \"\"\"\n ...\n```\n\nThe `wait_for_it` function must be passed a method that follows the `WaitCallback` protocol. The function\ncan have variable arguments and keyword arguements but the first parameter to the `WaitCallback` method\nmust be a `WaitContext` object.\n\n\n",
"bugtrack_url": null,
"license": "LICENSE.txt",
"summary": "Contextual Waiting",
"version": "1.0.2",
"split_keywords": [
"python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fbe75b1a17a99276f068f2ab6a7dc018b23b09542d3c0d0beb43600f41188161",
"md5": "c7157b280e017bfeab838bddddbac4ce",
"sha256": "9235aa23dc633c57a87577be9a915a9044c9271bcd50c4cee2c0b14cfb274156"
},
"downloads": -1,
"filename": "contextualwaiting-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c7157b280e017bfeab838bddddbac4ce",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 8444,
"upload_time": "2023-03-13T22:06:21",
"upload_time_iso_8601": "2023-03-13T22:06:21.997184Z",
"url": "https://files.pythonhosted.org/packages/fb/e7/5b1a17a99276f068f2ab6a7dc018b23b09542d3c0d0beb43600f41188161/contextualwaiting-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "66bfb9e7e6bed368347721158fdf37a52f394d89e17322fe9306fc0db1a2f4cd",
"md5": "c2c76f72585a38c00e5d3fca80401552",
"sha256": "6bbb1c10acfda9ec692660bb659e72bfe027c04fab615179f8557e29355de757"
},
"downloads": -1,
"filename": "contextualwaiting-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "c2c76f72585a38c00e5d3fca80401552",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 7007,
"upload_time": "2023-03-13T22:06:23",
"upload_time_iso_8601": "2023-03-13T22:06:23.167520Z",
"url": "https://files.pythonhosted.org/packages/66/bf/b9e7e6bed368347721158fdf37a52f394d89e17322fe9306fc0db1a2f4cd/contextualwaiting-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-13 22:06:23",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "contextualwaiting"
}
