maint: improves mac_address, slug and uuid

- reformats `mac_address`, `slug` and `uuid` modules
- removes less relevant `truthy` module
- uses type hints, adds doc refs
- updates related tests

**Related items**

*Issues*

- Closes #101
- Closes #109

Author: yozachar

docs/index.md

@@ -1,7 +1,5 @@
 # Reference
 
-::: validators.utils
-
 ::: validators.between
 
 ::: validators.btc_address
@@ -16,4 +14,18 @@
 
 ::: validators.iban
 
+<!-- ::: validators.ip_address -->
+
 ::: validators.length
+
+::: validators.mac_address
+
+::: validators.slug
+
+<!-- ::: validators.url -->
+
+::: validators.uuid
+
+---
+
+::: validators.utils

tests/test_mac_address.py

@@ -1,21 +1,36 @@
+"""MAC Address."""
 # -*- coding: utf-8 -*-
+
+# external
 import pytest
 
+# local
 from validators import mac_address, ValidationFailure
 
 
-@pytest.mark.parametrize(('address',), [
-    ('01:23:45:67:ab:CD',),
-])
-def test_returns_true_on_valid_mac_address(address):
+@pytest.mark.parametrize(
+    ("address",),
+    [
+        ("01:23:45:67:ab:CD",),
+        ("01-23-45-67-ab-CD",),
+        ("01:2F:45:37:ab:CD",),
+        ("A1-2F-4E-68-ab-CD",),
+    ],
+)
+def test_returns_true_on_valid_mac_address(address: str):
+    """Test returns true on valid mac address."""
     assert mac_address(address)
 
 
-@pytest.mark.parametrize(('address',), [
-    ('00:00:00:00:00',),
-    ('01:23:45:67:89:',),
-    ('01:23:45:67:89:gh',),
-    ('123:23:45:67:89:00',),
-])
-def test_returns_failed_validation_on_invalid_mac_address(address):
+@pytest.mark.parametrize(
+    ("address",),
+    [
+        ("00-00:-00-00-00",),
+        ("01:23:45:67:89:",),
+        ("01:23-45:67-89:gh",),
+        ("123:23:45:67:89:00",),
+    ],
+)
+def test_returns_failed_validation_on_invalid_mac_address(address: str):
+    """Test returns failed validation on invalid mac address."""
     assert isinstance(mac_address(address), ValidationFailure)

tests/test_slug.py

@@ -1,23 +1,36 @@
+"""Test Slug."""
 # -*- coding: utf-8 -*-
+
+# external
 import pytest
 
+# local
 from validators import slug, ValidationFailure
 
 
-@pytest.mark.parametrize('value', [
-    '123-12312-asdasda',
-    '123____123',
-    'dsadasd-dsadas',
-])
-def test_returns_true_on_valid_slug(value):
+@pytest.mark.parametrize(
+    "value",
+    [
+        "123-asd-7sda",
+        "123-k-123",
+        "dac-12sa-459",
+        "dac-12sa7-ad31as",
+    ],
+)
+def test_returns_true_on_valid_slug(value: str):
+    """Test returns true on valid slug."""
     assert slug(value)
 
 
-@pytest.mark.parametrize('value', [
-    'some.slug',
-    '1231321%',
-    '   21312',
-    '123asda&',
-])
-def test_returns_failed_validation_on_invalid_slug(value):
+@pytest.mark.parametrize(
+    "value",
+    [
+        "some.slug&",
+        "1231321%",
+        "   21312",
+        "-47q-p--123",
+    ],
+)
+def test_returns_failed_validation_on_invalid_slug(value: str):
+    """Test returns failed validation on invalid slug."""
     assert isinstance(slug(value), ValidationFailure)

tests/test_uuid.py

@@ -1,40 +1,40 @@
+"""Test UUIDs."""
 # -*- coding: utf-8 -*-
-from uuid import UUID
 
+# standard
+from uuid import uuid4, UUID
+from typing import Union
+
+# external
 import pytest
 
+# local
 from validators import uuid, ValidationFailure
 
 
-@pytest.mark.parametrize(('value',), [
-    ('2bc1c94f-0deb-43e9-92a1-4775189ec9f8',),
-])
-def test_returns_true_on_valid_mac_address(value):
-    assert uuid(value)
-
-
-@pytest.mark.parametrize(('value',), [
-    (UUID('2bc1c94f-0deb-43e9-92a1-4775189ec9f8'),),
-])
-def test_returns_true_on_valid_uuid_object(value):
+@pytest.mark.parametrize(
+    ("value",),
+    [
+        (uuid4(),),
+        ("2bc1c94f-0deb-43e9-92a1-4775189ec9f8",),
+        (uuid4(),),
+        ("888256d7c49341f19fa33f29d3f820d7",),
+    ],
+)
+def test_returns_true_on_valid_uuid(value: Union[str, UUID]):
+    """Test returns true on valid uuid."""
     assert uuid(value)
 
 
-@pytest.mark.parametrize(('value',), [
-    ('2bc1c94f-deb-43e9-92a1-4775189ec9f8',),
-    ('2bc1c94f-0deb-43e9-92a1-4775189ec9f',),
-    ('gbc1c94f-0deb-43e9-92a1-4775189ec9f8',),
-    ('2bc1c94f 0deb-43e9-92a1-4775189ec9f8',),
-])
-def test_returns_failed_validation_on_invalid_mac_address(value):
-    assert isinstance(uuid(value), ValidationFailure)
-
-
-@pytest.mark.parametrize(('value',), [
-    (1,),
-    (1.0,),
-    (True,),
-    (None,),
-])
-def test_returns_failed_validation_on_invalid_types(value):
+@pytest.mark.parametrize(
+    ("value",),
+    [
+        ("2bc1c94f-deb-43e9-92a1-4775189ec9f8",),
+        ("2bc1c94f-0deb-43e9-92a1-4775189ec9f",),
+        ("gbc1c94f-0deb-43e9-92a1-4775189ec9f8",),
+        ("2bc1c94f 0deb-43e9-92a1-4775189ec9f8",),
+    ],
+)
+def test_returns_failed_validation_on_invalid_uuid(value: Union[str, UUID]):
+    """Test returns failed validation on invalid uuid."""
     assert isinstance(uuid(value), ValidationFailure)

validators/__init__.py

@@ -13,7 +13,6 @@
 from .length import length
 from .mac_address import mac_address
 from .slug import slug
-from .truthy import truthy
 from .url import url
 from .utils import ValidationFailure, validator
 from .uuid import uuid
@@ -44,7 +43,6 @@
     "sha256",
     "sha512",
     "slug",
-    "truthy",
     "unionpay",
     "url",
     "uuid",

validators/mac_address.py

@@ -1,33 +1,37 @@
+"""MAC Address."""
+# -*- coding: utf-8 -*-
+
+# standard
 import re
 
+# local
 from .utils import validator
 
-pattern = re.compile(r'^(?:[0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}$')
-
 
 @validator
-def mac_address(value):
-    """
-    Return whether or not given value is a valid MAC address.
-
-    If the value is valid MAC address this function returns ``True``,
-    otherwise :class:`~validators.utils.ValidationFailure`.
+def mac_address(value: str):
+    """Return whether or not given value is a valid MAC address.
 
-    This validator is based on `WTForms MacAddress validator`_.
+    This validator is based on [WTForms MacAddress validator][1].
 
-    .. _WTForms MacAddress validator:
-       https://github.com/wtforms/wtforms/blob/master/wtforms/validators.py
-
-    Examples::
+    [1]: https://github.com/wtforms/wtforms/blob/master/src/wtforms/validators.py#L482
 
+    Examples:
         >>> mac_address('01:23:45:67:ab:CD')
-        True
-
+        # Output: True
         >>> mac_address('00:00:00:00:00')
-        ValidationFailure(func=mac_address, args={'value': '00:00:00:00:00'})
+        # Output: ValidationFailure(func=mac_address, args={'value': '00:00:00:00:00'})
+
+    Args:
+        value:
+            A string to validate.
 
-    .. versionadded:: 0.2
+    Returns:
+        (Literal[True]):
+            If `value` is a valid MAC address.
+        (ValidationFailure):
+            If `value` is an invalid MAC address.
 
-    :param value: Mac address string to validate
+    > *New in version 0.2.0*.
     """
-    return pattern.match(value)
+    return re.match(r"^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$", value)

validators/slug.py

@@ -1,28 +1,36 @@
+"""Slug."""
+# -*- coding: utf-8 -*-
+
+# standard
 import re
 
+# local
 from .utils import validator
 
-slug_regex = re.compile(r'^[-a-zA-Z0-9_]+$')
-
 
 @validator
-def slug(value):
-    """
-    Validate whether or not given value is valid slug.
+def slug(value: str):
+    """Validate whether or not given value is valid slug.
 
-    Valid slug can contain only alphanumeric characters, hyphens and
-    underscores.
-
-    Examples::
+    Valid slug can contain only lowercase alphanumeric characters and hyphens.
+    It starts and ends with these lowercase alphanumeric characters.
 
+    Examples:
+        >>> slug('my-slug-2134')
+        # Output: True
         >>> slug('my.slug')
-        ValidationFailure(func=slug, args={'value': 'my.slug'})
+        # Output: ValidationFailure(func=slug, args={'value': 'my.slug'})
 
-        >>> slug('my-slug-2134')
-        True
+    Args:
+        value:
+            A string to validate.
 
-    .. versionadded:: 0.6
+    Returns:
+        (Literal[True]):
+            If `value` is a valid slug.
+        (ValidationFailure):
+            If `value` is an invalid slug.
 
-    :param value: value to validate
+    > *New in version 0.6.0*.
     """
-    return slug_regex.match(value)
+    return re.match(r"^[a-z0-9]+(?:-[a-z0-9]+)*$", value)