Merge branch 'develop' into unit_conversion

# Conflicts:
#	docs/conf.py
#	python_utils/time.py
#	setup.py

Author: wolph

.coveragerc

@@ -21,3 +21,4 @@ exclude_lines =
     raise NotImplementedError
     if 0:
     if __name__ == .__main__.:
+    if typing.TYPE_CHECKING:

.github/workflows/main.yml

@@ -0,0 +1,50 @@
+name: pytest
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    strategy:
+      matrix:
+        python-version: ['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
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.10'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip setuptools
+        pip install -e '.[docs]'
+    - name: build docs
+      run: make html
+      working-directory: docs/

.travis.yml

@@ -1,8 +1,8 @@
 Useful Python Utils
 ==============================================================================
 
-.. image:: https://travis-ci.org/WoLpH/python-utils.svg?branch=master
-  :target: https://travis-ci.org/WoLpH/python-utils
+.. image:: https://github.com/WoLpH/python-utils/actions/workflows/main.yml/badge.svg?branch=master
+  :target: https://github.com/WoLpH/python-utils/actions/workflows/main.yml
 
 .. image:: https://coveralls.io/repos/WoLpH/python-utils/badge.svg?branch=master
   :target: https://coveralls.io/r/WoLpH/python-utils?branch=master
@@ -28,23 +28,30 @@ Links
 Requirements for installing:
 ------------------------------------------------------------------------------
 
- - `six` any recent version
+For the Python 3+ release (i.e. v3.0.0 or higher) there are no requirements.
+For the Python 2 compatible version (v2.x.x) the `six` package is needed.
 
 Installation:
 ------------------------------------------------------------------------------
 
 The package can be installed through `pip` (this is the recommended method):
 
+.. code-block:: bash
+
     pip install python-utils
     
 Or if `pip` is not available, `easy_install` should work as well:
 
+.. code-block:: bash
+
     easy_install python-utils
     
 Or download the latest release from Pypi (https://pypi.python.org/pypi/python-utils) or Github.
 
 Note that the releases on Pypi are signed with my GPG key (https://pgp.mit.edu/pks/lookup?op=vindex&search=0xE81444E9CE1F695D) and can be checked using GPG:
 
+.. code-block:: bash
+
      gpg --verify python-utils-<version>.tar.gz.asc python-utils-<version>.tar.gz
 
 Quickstart
@@ -57,22 +64,138 @@ format.
 Examples
 ------------------------------------------------------------------------------
 
-To extract a number from nearly every string:
+Automatically converting a generator to a list, dict or other collections
+using a decorator:
 
-.. code-block:: python
+.. 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`:
+
+.. code-block:: pycon
+
+    >>> for i in time.timeout_generator(10):
+    ...     try:
+    ...         # Run your code here
+    ...     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
+
+    >>> time.format_time('1')
+    '0:00:01'
+    >>> time.format_time(1.234)
+    '0:00:01'
+    >>> time.format_time(1)
+    '0:00:01'
+    >>> time.format_time(datetime.datetime(2000, 1, 2, 3, 4, 5, 6))
+    '2000-01-02 03:04:05'
+    >>> time.format_time(datetime.date(2000, 1, 2))
+    '2000-01-02'
+    >>> time.format_time(datetime.timedelta(seconds=3661))
+    '1:01:01'
+    >>> time.format_time(None)
+    '--:--:--'
+
+    >>> formatters.timesince(now)
+    'just now'
+    >>> formatters.timesince(now - datetime.timedelta(seconds=1))
+    '1 second ago'
+    >>> formatters.timesince(now - datetime.timedelta(seconds=2))
+    '2 seconds ago'
+    >>> formatters.timesince(now - datetime.timedelta(seconds=60))
+    '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
+
+    You can use:
+    >>> @decorators.set_attributes(short_description='Name')
+    ... def upper_case_name(self, obj):
+    ...     return ("%s %s" % (obj.first_name, obj.last_name)).upper()
+
+    Instead of:
+    >>> def upper_case_name(obj):
+    ...     return ("%s %s" % (obj.first_name, obj.last_name)).upper()
+
+    >>> upper_case_name.short_description = 'Name'
 
-    from python_utils import converters
+This can be very useful for the Django admin as it allows you to have all
+metadata in one place.
 
-    number = converters.to_int('spam15eggs')
-    assert number == 15
+Scaling numbers between ranges
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    number = converters.to_int('spam')
-    assert number == 0
+.. code-block:: pycon
 
-    number = converters.to_int('spam', default=1)
-    assert number == 1
+    >>> converters.remap(500, old_min=0, old_max=1000, new_min=0, new_max=100)
+    50
 
-    number = converters.to_float('spam1.234')
+    # Or with decimals:
+    >>> remap(decimal.Decimal('250.0'), 0.0, 1000.0, 0.0, 100.0)
+    Decimal('25.0')
+
+Get the screen/window/terminal size in characters:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: pycon
+
+    >>> terminal.get_terminal_size()
+    (80, 24)
+
+That method supports IPython and Jupyter as well as regular shells, using
+`blessings` and other modules depending on what is available.
+
+Extracting numbers from nearly every string:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: pycon
+
+    >>> converters.to_int('spam15eggs')
+    15
+    >>> converters.to_int('spam')
+    0
+    >>> 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 *`
@@ -84,6 +207,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
@@ -106,3 +232,39 @@ Or add a correclty named logger to your classes which can be easily accessed:
     import logging
     my_class.log(logging.ERROR, 'log')
 
+Alternatively loguru is also supported. It is largely a drop-in replacement for the logging module which is a bit more convenient to configure:
+
+First install the extra loguru package:
+
+.. code-block:: bash
+
+    pip install 'python-utils[loguru]'
+
+.. code-block:: python
+
+    class MyClass(Logurud):
+        ...
+
+Now you can use the `Logurud` class to make functions such as `self.info()`
+available. The benefit of this approach is that you can add extra context or
+options to you specific loguru instance (i.e. `self.logger`):
+
+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]