Merge branch 'release/3.0.0'

Author: wolph

.github/workflows/main.yml

@@ -1,4 +1,4 @@
-name: tox
+name: pytest
 
 on:
   push:
@@ -11,17 +11,40 @@ jobs:
     timeout-minutes: 2
     strategy:
       matrix:
-        python-version: [2.7, 3.6, 3.7, 3.8, 3.9, '3.10']
+        python-version: ['3.6', '3.7', '3.8', '3.9', '3.10']
 
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip setuptools flake8
+          pip install -e '.[tests]'
+      - name: Get versions
+        run: |
+          python -V
+          pip freeze
+      - name: flake8
+        run: flake8 -v python_utils setup.py
+      - name: pytest
+        run: py.test
+
+  docs:
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
     steps:
     - uses: actions/checkout@v2
-    - name: Set up Python ${{ matrix.python-version }}
+    - name: Set up Python
       uses: actions/setup-python@v2
       with:
-        python-version: ${{ matrix.python-version }}
+        python-version: '3.10'
     - name: Install dependencies
       run: |
-        python -m pip install --upgrade pip
-        pip install tox tox-gh-actions
-    - name: Test with tox
-      run: tox
+        python -m pip install --upgrade pip setuptools
+        pip install -e '.[docs]'
+    - name: build docs
+      run: make html
+      working-directory: docs/

README.rst

@@ -58,6 +58,31 @@ format.
 Examples
 ------------------------------------------------------------------------------
 
+Automatically converting a generator to a list, dict or other collections
+using a decorator:
+
+.. code-block:: pycon
+
+    >>> @decorators.listify()
+    ... def generate_list():
+    ...     yield 1
+    ...     yield 2
+    ...     yield 3
+    ...
+    >>> generate_list()
+    [1, 2, 3]
+
+    >>> @listify(collection=dict)
+    ... def dict_generator():
+    ...     yield 'a', 1
+    ...     yield 'b', 2
+
+    >>> dict_generator()
+    {'a': 1, 'b': 2}
+
+Retrying until timeout
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 To easily retry a block of code with a configurable timeout, you can use the
 `time.timeout_generator`:
 
@@ -69,6 +94,9 @@ To easily retry a block of code with a configurable timeout, you can use the
     ...     except Exception as e:
     ...         # Handle the exception
 
+Formatting of timestamps, dates and times
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Easy formatting of timestamps and calculating the time since:
 
 .. code-block:: pycon
@@ -98,12 +126,15 @@ Easy formatting of timestamps and calculating the time since:
     '1 minute ago'
 
 Converting your test from camel-case to underscores:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: pycon
 
     >>> camel_to_underscore('SpamEggsAndBacon')
     'spam_eggs_and_bacon'
 
+Attribute setting decorator. Very useful for the Django admin
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 A convenient decorator to set function attributes using a decorator:
 
 .. code-block:: pycon
@@ -119,7 +150,11 @@ A convenient decorator to set function attributes using a decorator:
 
     >>> upper_case_name.short_description = 'Name'
 
-Or to scale numbers:
+This can be very useful for the Django admin as it allows you to have all
+metadata in one place.
+
+Scaling numbers between ranges
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: pycon
 
@@ -130,7 +165,8 @@ Or to scale numbers:
     >>> remap(decimal.Decimal('250.0'), 0.0, 1000.0, 0.0, 100.0)
     Decimal('25.0')
 
-To get the screen/window/terminal size in characters:
+Get the screen/window/terminal size in characters:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: pycon
 
@@ -140,7 +176,8 @@ To get the screen/window/terminal size in characters:
 That method supports IPython and Jupyter as well as regular shells, using
 `blessings` and other modules depending on what is available.
 
-To extract a number from nearly every string:
+Extracting numbers from nearly every string:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: pycon
 
@@ -151,6 +188,9 @@ To extract a number from nearly every string:
     >>> number = converters.to_int('spam', default=1)
     1
 
+Doing a global import of all the modules in a package programmatically:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 To do a global import programmatically you can use the `import_global`
 function. This effectively emulates a `from ... import *`
 
@@ -161,6 +201,9 @@ function. This effectively emulates a `from ... import *`
     # The following is  the equivalent of `from some_module import *`
     import_global('some_module')
 
+Automatically named logger for classes:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Or add a correclty named logger to your classes which can be easily accessed:
 
 .. code-block:: python
@@ -183,3 +226,23 @@ Or add a correclty named logger to your classes which can be easily accessed:
     import logging
     my_class.log(logging.ERROR, 'log')
 
+
+Convenient type aliases and some commonly used types:
+
+.. code-block:: python
+
+    # For type hinting scopes such as locals/globals/vars
+    Scope = Dict[str, Any]
+    OptionalScope = O[Scope]
+
+    # Note that Number is only useful for extra clarity since float
+    # will work for both int and float in practice.
+    Number = U[int, float]
+    DecimalNumber = U[Number, decimal.Decimal]
+
+    # To accept an exception or list of exceptions
+    ExceptionType = Type[Exception]
+    ExceptionsType = U[Tuple[ExceptionType, ...], ExceptionType]
+
+    # Matching string/bytes types:
+    StringTypes = U[str, bytes]

_python_utils_tests/test_import.py

@@ -10,8 +10,6 @@ def relative_import(level):
     locals_ = {}
     globals_ = {'__name__': 'python_utils.import_'}
     import_.import_global('.formatters', locals_=locals_, globals_=globals_)
-    import pprint
-    pprint.pprint(globals_)
     assert 'camel_to_underscore' in globals_
 
 

_python_utils_tests/test_time.py

@@ -0,0 +1,53 @@
+import itertools
+from datetime import timedelta
+
+import pytest
+
+from python_utils import aio
+from python_utils import time
+
+
+@pytest.mark.parametrize(
+    'timeout,interval,interval_multiplier,maximum_interval,iterable,result', [
+        (0.1, 0.06, 0.5, 0.1, aio.acount, 2),
+        (0.2, 0.06, 0.5, 0.1, aio.acount(), 4),
+        (0.3, 0.06, 1.0, None, aio.acount, 5),
+        (timedelta(seconds=0.1), timedelta(seconds=0.06),
+         2.0, timedelta(seconds=0.1), aio.acount, 2),
+    ])
+@pytest.mark.asyncio
+async def test_aio_timeout_generator(timeout, interval, interval_multiplier,
+                                     maximum_interval, iterable, result):
+    i = None
+    async for i in time.aio_timeout_generator(
+            timeout, interval, iterable,
+            maximum_interval=maximum_interval):
+        pass
+
+    assert i == result
+
+
+@pytest.mark.parametrize(
+    'timeout,interval,interval_multiplier,maximum_interval,iterable,result', [
+        (0.01, 0.006, 0.5, 0.01, 'abc', 'c'),
+        (0.01, 0.006, 0.5, 0.01, itertools.count, 2),
+        (0.01, 0.006, 0.5, 0.01, itertools.count(), 2),
+        (0.01, 0.006, 1.0, None, 'abc', 'c'),
+        (timedelta(seconds=0.01),
+         timedelta(seconds=0.006),
+         2.0, timedelta(seconds=0.01),
+         itertools.count, 2),
+    ])
+def test_timeout_generator(timeout, interval, interval_multiplier,
+                           maximum_interval, iterable, result):
+    i = None
+    for i in time.timeout_generator(
+            timeout=timeout,
+            interval=interval,
+            interval_multiplier=interval_multiplier,
+            iterable=iterable,
+            maximum_interval=maximum_interval,
+    ):
+        pass
+
+    assert i == result