Merge pull request #224 from joe733/workshop

maint: follows google's python style guide for docstrings

Author: yozachar

README.md

@@ -20,8 +20,8 @@ True
 - [Issue Tracker](http://github.com/kvesteri/validators/issues)
 - [Code](http://github.com/kvesteri/validators/)
 
-[bs-badge]: https://github.com/kvesteri/validators/workflows/GH/badge.svg
-[bs-link]: https://github.com/kvesteri/validators/actions/workflows/main.yml
+[bs-badge]: https://github.com/python-validators/validators/actions/workflows/main.yml/badge.svg
+[bs-link]: https://github.com/python-validators/validators/actions/workflows/main.yml
 [vs-badge]: https://img.shields.io/pypi/v/validators.svg
 [vs-link]: https://pypi.python.org/pypi/validators/
 [dw-badge]: https://img.shields.io/pypi/dm/validators.svg

README.rst

@@ -26,8 +26,8 @@ Resources
 - `Code <http://github.com/kvesteri/validators/>`_
 
 
-.. |Build Status| image:: https://github.com/kvesteri/validators/workflows/GH/badge.svg
-   :target: https://github.com/kvesteri/validators/actions/workflows/main.yml
+.. |Build Status| image:: https://github.com/python-validators/validators/actions/workflows/main.yml/badge.svg
+   :target: https://github.com/python-validators/validators/actions/workflows/main.yml
 .. |Version Status| image:: https://img.shields.io/pypi/v/validators.svg
    :target: https://pypi.python.org/pypi/validators/
 .. |Downloads| image:: https://img.shields.io/pypi/dm/validators.svg

poetry.lock

@@ -31,6 +31,7 @@ python = "^3.9"
 bandit = "^1.7.4"
 black = "^23.1.0"
 flake8 = "^6.0.0"
+flake8-docstrings = "^1.7.0"
 pyright = "^1.1.293"
 pytest = "^7.2.1"
 setuptools = "^67.2.0"

pyproject.toml

@@ -3,6 +3,7 @@
 
 [flake8]
 max-line-length = 100
+docstring-convention = google
 
 # [isort]
 # known_first_party = sqlalchemy_utils,tests

setup.cfg

@@ -1,7 +1,4 @@
-"""
-Utils.py
---------
-"""
+"""Utils."""
 # -*- coding: utf-8 -*-
 
 # standard
@@ -11,37 +8,31 @@
 
 
 class ValidationFailure(Exception):
-    """
-    Exception class when validation failure occurs
-    """
+    """Exception class when validation failure occurs."""
 
     def __init__(self, function: Callable[..., Any], arg_dict: Dict[str, Any]):
+        """Initialize Validation Failure."""
         self.func = function
         self.__dict__.update(arg_dict)
 
     def __repr__(self) -> str:
+        """Repr Validation Failure."""
         return (
             f"ValidationFailure(func={self.func.__name__}, "
             + f"args={({k: v for (k, v) in self.__dict__.items() if k != 'func'})})"
         )
 
     def __str__(self) -> str:
+        """Str Validation Failure."""
         return repr(self)
 
     def __bool__(self) -> Literal[False]:
+        """Bool Validation Failure."""
         return False
 
 
 def _func_args_as_dict(func: Callable[..., Any], *args: Any, **kwargs: Any) -> Dict[str, Any]:
-    """
-    Return given function's positional and key value arguments as an ordered
-    dictionary.
-
-    :param func: function to decorate
-    :param args: positional function arguments
-    :param kwargs: key value function arguments
-    """
-
+    """Return function's positional and key value arguments as an ordered dictionary."""
     # TODO: find more efficient way to do it
     return dict(
         list(zip(dict.fromkeys(chain(getfullargspec(func)[0], kwargs.keys())), args))
@@ -50,8 +41,7 @@ def _func_args_as_dict(func: Callable[..., Any], *args: Any, **kwargs: Any) -> D
 
 
 def validator(func: Callable[..., Any]) -> Callable[..., Union[Literal[True], ValidationFailure]]:
-    """
-    A decorator that makes given function validator.
+    """A decorator that makes given function validator.
 
     Whenever the given function is called and returns ``False`` value
     this decorator returns :class:`ValidationFailure` object.
@@ -63,14 +53,16 @@ def validator(func: Callable[..., Any]) -> Callable[..., Union[Literal[True], Va
         ...     return not (value % 2)
 
         >>> even(4)
-        True
+        # Output: True
 
         >>> even(5)
-        ValidationFailure(func=even, args={'value': 5})
+        # Output: ValidationFailure(func=even, args={'value': 5})
+
+    Args:
+        `func`: function which is to be decorated.
 
-    :param func: function to decorate
-    :param args: positional function arguments
-    :param kwargs: key value function arguments
+    Returns:
+        Wrapper function as a decorator.
     """
 
     def wrapper(*args: Any, **kwargs: Any) -> Union[Literal[True], ValidationFailure]:
@@ -79,5 +71,15 @@ def wrapper(*args: Any, **kwargs: Any) -> Union[Literal[True], ValidationFailure
             if func(*args, **kwargs)
             else ValidationFailure(func, _func_args_as_dict(func, *args, **kwargs))
         )
+        # try:
+        #     return (
+        #         True
+        #         if func(*args, **kwargs)
+        #         else ValidationFailure(func, _func_args_as_dict(func, *args, **kwargs))
+        #     )
+        # except (AssertionError, TypeError) as err:
+        #     print(err)
+        # finally:
+        #     return ValidationFailure(func, _func_args_as_dict(func, *args, **kwargs))
 
     return wrapper