Version 1.0.0 (#1)

Fresh out of the oven.

.gitignore

@@ -0,0 +1,9 @@
+.idea
+.coverage
+.mypy_cache
+.pyc
+.pytest_cache
+__pycache__
+/build/
+/dist/
+/w8ing.egg-info/

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019 Imran M
+Copyright (c) 2019 Imran Mumtaz
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Pipfile

@@ -0,0 +1,17 @@
+[[source]]
+url = "https://pypi.python.org/simple"
+verify_ssl = true
+name = "pypi"
+
+[packages]
+
+[dev-packages]
+black = "*"
+mypy = "*"
+pytest = "*"
+pytest-cov = "*"
+pytest-repeat = "*"
+codecov = "*"
+
+[requires]
+python_version = "3.7"

README.md

@@ -1,2 +1,110 @@
-# w8ing
-Waiting for humans.
+```
+██╗    ██╗ █████╗ ██╗███╗   ██╗ ██████╗ 
+██║    ██║██╔══██╗██║████╗  ██║██╔════╝ 
+██║ █╗ ██║╚█████╔╝██║██╔██╗ ██║██║  ███╗
+██║███╗██║██╔══██╗██║██║╚██╗██║██║   ██║
+╚███╔███╔╝╚█████╔╝██║██║ ╚████║╚██████╔╝
+ ╚══╝╚══╝  ╚════╝ ╚═╝╚═╝  ╚═══╝ ╚═════╝ 
+```
+
+[![Build Status](https://travis-ci.com/ImXron/w8ing.svg?branch=master)](https://travis-ci.com/ImXron/w8ing)
+[![codecov](https://codecov.io/gh/ImXron/w8ing/branch/master/graph/badge.svg)](https://codecov.io/gh/ImXron/w8ing)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
+[![image](https://img.shields.io/pypi/v/w8ing.svg)](https://python.org/pypi/w8ing)
+[![image](https://img.shields.io/pypi/pyversions/w8ing.svg)](https://python.org/pypi/w8ing)
+___
+
+**_W8ing_** is (as the great Kenneth Reitz would say) waiting and or polling **_for humans_**.
+
+Get it? The **_8_** replaces the **_a_** in **_waiting_** :wink: :woman_shrugging:.
+
+Let **_W8ing_** help you nuke all your hard calls to `time.sleep()` and make your tests less flakey :metal:.
+___
+
+## Install
+Install via pip (highly recommend installing within a [Pipenv](https://github.com/pypa/pipenv)):
+```
+pip3 install w8ing
+```
+
+## Usages
+
+Wait **_until_** some condition is true:
+```python
+from w8ing import wait
+
+# This example uses an imaginary function that doesn't immediately give us the value we want.
+result = wait.until(condition=lambda: get_cat_treats(8) == 8)
+
+# By default, this wait will return whether or not the condition was true or not.
+result
+True
+```
+
+Wait **_until_** an http request is valid:
+```python
+import requests
+from w8ing import wait
+
+# You can even specify the timeout and retry delay.
+response = wait.until(lambda: requests.get("http://www.google.com"), retry_time=1, timeout=15)
+
+# By default a successful response (codes 2XX) object is truthy.
+response
+<Response [200]>
+```
+
+Wait **_until_** a serial device becomes available and catch any associated exceptions (for you hardware people):
+
+```python
+import serial
+from w8ing import wait
+
+# If successful, you'll get a pyserial object back, otherwise you'll get None!
+serial_port = wait.until(
+    lambda: serial.Serial('/dev/ttyUSB0'), catch_exceptions=(SerialException,), retry_time=1, timeout=30
+)
+
+# If it doesn't open you can make a nice assert so your co-workers love you.
+assert serial_port, "Unable to open serial port! Did you even plug it in??"
+
+# Otherwise, continue!
+serial_port.read(10).decode()
+"boots and cats"
+```
+
+You can also call another function each loop!
+```python
+from w8ing import wait
+
+cat_treats = []
+
+# The call_each_try function gets called each time the condition gets evaluated, 
+result = wait.until(lambda: len(cat_treats) > 8, call_each_try=lambda: cat_treats.append("treat"), retry_time=0.5)
+result
+True
+
+# The cat will be pleased.
+```
+
+### But wait, there's more!
+
+What if you need to **_ensure_** that some condition remains true?? Got you covered fam:
+
+```python
+from w8ing import wait
+
+cat_nip = ["cat nip"] * 10
+result = wait.ensure(lambda: len(cat_nip) > 5, call_each_try=lambda: cat_nip.pop(), retry_time=1, timeout=2)
+
+result
+True
+
+# The cat will extra intoxicated by this high quality cat nip, good job.
+```
+
+## Contribute
+Feel free to open an issue and once you get a green light, submit a PR!
+
+All PRs will receive respectful and constructive feedback.

pyproject.toml

@@ -0,0 +1,2 @@
+[tool.black]
+line-length = 120

setup.cfg

@@ -0,0 +1,44 @@
+# Please respect the alphabetical ordering!!!
+[metadata]
+author = Imran Mumtaz
+author_email = [email protected]
+classifiers =
+    Development Status :: 4 - Beta
+    License :: OSI Approved :: MIT License
+    Natural Language :: English
+    Operating System :: OS Independent
+    Programming Language :: Python
+    Programming Language :: Python :: 3
+    Programming Language :: Python :: 3.6
+    Programming Language :: Python :: 3.7
+    Programming Language :: Python :: 3.8
+    Topic :: Utilities
+description = Waiting, for humans.
+keywords = waiting, polling, synchronization, wait until, test tools
+license = MIT License
+license_file = LICENSE
+long_description = file: README.md
+long_description_content_type = text/markdown
+name = w8ing
+project_urls =
+    Homepage=https://github.com/ImXron/w8ing
+    Source=https://github.com/ImXron/w8ing
+    Tracker=https://github.com/ImXron/w8ing/issues
+python_requires = >=3.6
+url = http://pypi.python.org/pypi/w8ing
+
+[options]
+packages = find:
+
+[tool:pytest]
+addopts =
+    --cov=w8ing
+    --cov-fail-under 95
+    --cov-report term-missing
+    --strict-markers
+    --verbose
+markers =
+    ensure: All tests that relate to the "ensure" method.
+    unit: All tests that are considered unit tests.
+    until: All tests that relate to the "until" method.
+testpaths = tests

setup.py

@@ -0,0 +1,38 @@
+"""
+MIT License
+
+Copyright (c) 2019 Imran Mumtaz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+██╗    ██╗ █████╗ ██╗███╗   ██╗ ██████╗
+██║    ██║██╔══██╗██║████╗  ██║██╔════╝
+██║ █╗ ██║╚█████╔╝██║██╔██╗ ██║██║  ███╗
+██║███╗██║██╔══██╗██║██║╚██╗██║██║   ██║
+╚███╔███╔╝╚█████╔╝██║██║ ╚████║╚██████╔╝
+ ╚══╝╚══╝  ╚════╝ ╚═╝╚═╝  ╚═══╝ ╚═════╝
+"""
+
+import setuptools
+
+from w8ing.__version__ import __version__
+
+if __name__ == "__main__":
+    # Refer to setup.cfg for all the good stuff.
+    setuptools.setup(version=__version__)

tests/unit/conftest.py

@@ -0,0 +1,36 @@
+"""
+MIT License
+
+Copyright (c) 2019 Imran Mumtaz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+import time
+
+
+def raise_value_error() -> None:
+    raise ValueError
+
+
+def get_delta_time(start_time: float, end_time: float) -> float:
+    return end_time - start_time
+
+
+def get_time() -> float:
+    return time.time()

tests/unit/test_imports.py

@@ -0,0 +1,36 @@
+"""
+MIT License
+
+Copyright (c) 2019 Imran Mumtaz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+import pytest
+
+
+@pytest.mark.unit
+def test_imports():
+    # Auto formatter will remove these import because they are not used. Putting these in a try/except block fixes that.
+    try:
+        import w8ing
+        from w8ing import wait
+        from w8ing.wait import ensure
+        from w8ing.wait import until
+    except ImportError:
+        raise

tests/unit/test_utils.py

@@ -0,0 +1,59 @@
+"""
+MIT License
+
+Copyright (c) 2019 Imran Mumtaz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+import pytest
+
+from w8ing import utils
+from w8ing.utils import call_if_callable
+
+
+@pytest.mark.unit
+def test_is_callable_true_case():
+    utils.is_callable(lambda: True)
+
+
+@pytest.mark.unit
+def test_is_callable_false_case():
+    with pytest.raises(AssertionError):
+        utils.is_callable("meow")
+
+
+@pytest.mark.unit
+def test_can_get_time_and_type_is_float():
+    time = utils.get_time()
+    assert time
+    assert isinstance(time, float)
+
+
+def test_call_if_callable():
+    string = "cat nip"
+
+    def make_string(string):
+        return string
+
+    assert call_if_callable(lambda: make_string("cat nip")) == string
+
+
+def test_call_if_callable_gets_a_non_callable():
+    with pytest.raises(TypeError):
+        call_if_callable("boots and cat")