Merge branch 'release/3.2.0'

wolph · wolph · commit 41449518931f · 2022-05-12T22:14:46.000+02:00
diff --git a/.coveragerc b/.coveragerc
@@ -21,3 +21,4 @@ exclude_lines =
     raise NotImplementedError
     if 0:
     if __name__ == .__main__.:
+    if typing.TYPE_CHECKING:
diff --git a/.travis.yml b/.travis.yml
diff --git a/README.rst b/README.rst
@@ -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
@@ -36,16 +36,22 @@ 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
@@ -226,6 +232,22 @@ 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:
 
diff --git a/_python_utils_tests/test_logger.py b/_python_utils_tests/test_logger.py
@@ -0,0 +1,19 @@
+import pytest
+
+from python_utils.loguru import Logurud
+
+
+loguru = pytest.importorskip('loguru')
+
+
+def test_logurud():
+    class MyClass(Logurud):
+        pass
+
+    my_class = MyClass()
+    my_class.debug('debug')
+    my_class.info('info')
+    my_class.warning('warning')
+    my_class.error('error')
+    my_class.exception('exception')
+    my_class.log(0, 'log')
diff --git a/docs/conf.py b/docs/conf.py
@@ -60,4 +60,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
+
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
+
diff --git a/pytest.ini b/pytest.ini
@@ -17,3 +17,5 @@ flake8-ignore =
 doctest_optionflags = 
     ALLOW_UNICODE
     ALLOW_BYTES
+
+asyncio_mode = strict
diff --git a/python_utils/__about__.py b/python_utils/__about__.py
@@ -6,4 +6,4 @@
     'with the standard Python install')
 __url__: str = 'https://github.com/WoLpH/python-utils'
 # Omit type info due to automatic versioning script
-__version__ = '3.1.0'
+__version__ = '3.2.0'
diff --git a/python_utils/__init__.py b/python_utils/__init__.py
@@ -26,6 +26,7 @@
 from .time import timedelta_to_seconds
 from .time import timeout_generator
 from .time import aio_timeout_generator
+from .logger import Logged, LoggerBase
 
 __all__ = [
     'aio',
@@ -55,4 +56,6 @@
     'timeout_generator',
     'acount',
     'aio_timeout_generator',
+    'Logged',
+    'LoggerBase',
 ]
diff --git a/python_utils/containers.py b/python_utils/containers.py
@@ -1,11 +1,14 @@
 from __future__ import annotations
 
 import abc
-from typing import Any
-from typing import Generator
+import typing
+from typing import Any, Generator
 
 from . import types
 
+if typing.TYPE_CHECKING:
+    import _typeshed  # noqa: F401
+
 KT = types.TypeVar('KT')
 VT = types.TypeVar('VT')
 DT = types.Dict[KT, VT]
@@ -16,6 +19,7 @@
 DictUpdateArgs = types.Union[
     types.Mapping,
     types.Iterable[types.Union[types.Tuple[Any, Any], types.Mapping]],
+    '_typeshed.SupportsKeysAndGetItem[KT, VT]',
 ]
 
 
@@ -37,7 +41,7 @@ def __init__(
     def update(
             self,
             *args: DictUpdateArgs,
-            **kwargs
+            **kwargs: VT
     ) -> None:
         if args:
             kwargs.update(*args)
diff --git a/python_utils/converters.py b/python_utils/converters.py
@@ -181,7 +181,7 @@ def to_unicode(
     '''Convert objects to unicode, if needed decodes string with the given
     encoding and errors settings.
 
-    :rtype: unicode
+    :rtype: str
 
     >>> to_unicode(b'a')
     'a'
diff --git a/python_utils/formatters.py b/python_utils/formatters.py
@@ -1,9 +1,10 @@
 import datetime
-from typing import Union
+
+from python_utils import types
 
 
 def camel_to_underscore(name: str) -> str:
-    '''Convert camel case style naming to underscore style naming
+    '''Convert camel case style naming to underscore/snake case style naming
 
     If there are existing underscores they will be collapsed with the
     to-be-added underscores. Multiple consecutive capital letters will not be
@@ -40,8 +41,44 @@ def camel_to_underscore(name: str) -> str:
     return ''.join(output)
 
 
-def timesince(dt: Union[datetime.datetime, datetime.timedelta],
-              default: str = 'just now') -> str:
+def apply_recursive(
+    function: types.Callable[[str], str],
+    data: types.OptionalScope = None,
+    **kwargs
+) -> types.OptionalScope:
+    '''
+    Apply a function to all keys in a scope recursively
+
+    >>> apply_recursive(camel_to_underscore, {'SpamEggsAndBacon': 'spam'})
+    {'spam_eggs_and_bacon': 'spam'}
+    >>> apply_recursive(camel_to_underscore, {'SpamEggsAndBacon': {
+    ...     'SpamEggsAndBacon': 'spam',
+    ... }})
+    {'spam_eggs_and_bacon': {'spam_eggs_and_bacon': 'spam'}}
+
+    >>> a = {'a_b_c': 123, 'def': {'DeF': 456}}
+    >>> b = apply_recursive(camel_to_underscore, a)
+    >>> b
+    {'a_b_c': 123, 'def': {'de_f': 456}}
+
+    >>> apply_recursive(camel_to_underscore, None)
+    '''
+    if data is None:
+        return None
+
+    elif isinstance(data, dict):
+        return {
+            function(key): apply_recursive(function, value, **kwargs)
+            for key, value in data.items()
+        }
+    else:
+        return data
+
+
+def timesince(
+    dt: types.Union[datetime.datetime, datetime.timedelta],
+    default: str = 'just now'
+) -> str:
     '''
     Returns string representing 'time since' e.g.
     3 days ago, 5 hours ago etc.
diff --git a/python_utils/logger.py b/python_utils/logger.py
@@ -1,3 +1,4 @@
+import abc
 import functools
 import logging
 
@@ -6,15 +7,18 @@
 import typing
 
 
-class Logged(object):
-    '''Class which automatically adds a named logger to your class when
-    interiting
+class LoggerBase(abc.ABC):
+    '''Class which automatically adds logging utilities to your class when
+    interiting. Expects `logger` to be a logging.Logger or compatible instance.
 
     Adds easy access to debug, info, warning, error, exception and log methods
 
-    >>> class MyClass(Logged):
+    >>> class MyClass(LoggerBase):
+    ...     logger = logging.getLogger(__name__)
+    ...
     ...     def __init__(self):
     ...         Logged.__init__(self)
+
     >>> my_class = MyClass()
     >>> my_class.debug('debug')
     >>> my_class.info('info')
@@ -23,13 +27,9 @@ class Logged(object):
     >>> my_class.exception('exception')
     >>> my_class.log(0, 'log')
     '''
-
-    logger: logging.Logger
-
-    def __new__(cls, *args, **kwargs):
-        cls.logger = logging.getLogger(
-            cls.__get_name(cls.__module__, cls.__name__))
-        return super(Logged, cls).__new__(cls)
+    # Being a tad lazy here and not creating a Protocol.
+    # The actual classes define the correct type anyway
+    logger: typing.Any
 
     @classmethod
     def __get_name(cls, *name_parts: str) -> str:
@@ -64,3 +64,30 @@ def exception(cls, msg: str, *args: typing.Any, **kwargs: typing.Any):
     @functools.wraps(logging.log)
     def log(cls, lvl: int, msg: str, *args: typing.Any, **kwargs: typing.Any):
         cls.logger.log(lvl, msg, *args, **kwargs)
+
+
+class Logged(LoggerBase):
+    '''Class which automatically adds a named logger to your class when
+    interiting
+
+    Adds easy access to debug, info, warning, error, exception and log methods
+
+    >>> class MyClass(Logged):
+    ...     def __init__(self):
+    ...         Logged.__init__(self)
+    >>> my_class = MyClass()
+    >>> my_class.debug('debug')
+    >>> my_class.info('info')
+    >>> my_class.warning('warning')
+    >>> my_class.error('error')
+    >>> my_class.exception('exception')
+    >>> my_class.log(0, 'log')
+    '''
+
+    logger: logging.Logger
+
+    def __new__(cls, *args, **kwargs):
+        cls.logger = logging.getLogger(
+            cls._LoggerBase__get_name(cls.__module__, cls.__name__)
+        )
+        return super(Logged, cls).__new__(cls)
diff --git a/python_utils/loguru.py b/python_utils/loguru.py
@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from . import logger
+
+import loguru
+
+__all__ = ['Logurud']
+
+
+class Logurud(logger.LoggerBase):
+    logger: loguru.Logger
+
+    def __new__(cls, *args, **kwargs):
+        # Import at runtime to make loguru an optional dependency
+        import loguru
+        cls.logger: loguru.Loguru = loguru.logger
+        return super().__new__(cls)
diff --git a/setup.py b/setup.py
diff --git a/tox.ini b/tox.ini
