feat: add validator for bsc addresses (#389)

- add a new validator for bsc addresses
- minor fix in test cases
- chore: updates CHANGES.md

---------

Co-authored-by: Yozachar <[email protected]>

Author: msamsami

CHANGES.md

@@ -9,6 +9,24 @@ Note to self: Breaking changes must increment either
 
 -->
 
+## 0.33.0 (2024-07-15)
+
+_**Breaking**_
+
+> No breaking changes were introduced in this version.
+
+_**Features**_
+
+- feat: adds validator for `bsc` addresses by @msamsami in [#389](https://github.com/python-validators/validators/pull/389)
+
+_**Maintenance**_
+
+- chore: bump version by @msamsami in [#389](https://github.com/python-validators/validators/pull/389)
+
+**Full Changelog**: [`0.32.0...0.33.0`](https://github.com/python-validators/validators/compare/0.32.0...0.33.0)
+
+---
+
 ## 0.32.0 (2024-07-10)
 
 _**Breaking**_

SECURITY.md

@@ -4,7 +4,7 @@
 
 | Version    | Supported          |
 | ---------- | ------------------ |
-| `>=0.32.0` | :white_check_mark: |
+| `>=0.33.0` | :white_check_mark: |
 
 ## Reporting a Vulnerability
 

docs/api/crypto_addresses.md

@@ -1,5 +1,6 @@
 # crypto_addresses
 
+::: validators.crypto_addresses.bsc_address
 ::: validators.crypto_addresses.btc_address
 ::: validators.crypto_addresses.eth_address
 ::: validators.crypto_addresses.trx_address

docs/api/crypto_addresses.rst

@@ -2,6 +2,7 @@ crypto_addresses
 ----------------
 
 .. module:: validators.crypto_addresses
+.. autofunction:: bsc_address
 .. autofunction:: btc_address
 .. autofunction:: eth_address
 .. autofunction:: trx_address

src/validators/__init__.py

@@ -5,7 +5,7 @@
 from .card import amex, card_number, diners, discover, jcb, mastercard, unionpay, visa
 from .country import calling_code, country_code, currency
 from .cron import cron
-from .crypto_addresses import btc_address, eth_address, trx_address
+from .crypto_addresses import bsc_address, btc_address, eth_address, trx_address
 from .domain import domain
 from .email import email
 from .encoding import base16, base32, base58, base64
@@ -37,6 +37,7 @@
     # ...
     "between",
     # crypto_addresses
+    "bsc_address",
     "btc_address",
     "eth_address",
     "trx_address",
@@ -108,4 +109,4 @@
     "validator",
 )
 
-__version__ = "0.32.0"
+__version__ = "0.33.0"

src/validators/crypto_addresses/__init__.py

@@ -1,8 +1,9 @@
 """Crypto addresses."""
 
 # local
+from .bsc_address import bsc_address
 from .btc_address import btc_address
 from .eth_address import eth_address
 from .trx_address import trx_address
 
-__all__ = ("btc_address", "eth_address", "trx_address")
+__all__ = ("bsc_address", "btc_address", "eth_address", "trx_address")

src/validators/crypto_addresses/bsc_address.py

@@ -0,0 +1,36 @@
+"""BSC Address."""
+
+# standard
+import re
+
+# local
+from validators.utils import validator
+
+
+@validator
+def bsc_address(value: str, /):
+    """Return whether or not given value is a valid binance smart chain address.
+
+    Full validation is implemented for BSC addresses.
+
+    Examples:
+        >>> bsc_address('0x4e5acf9684652BEa56F2f01b7101a225Ee33d23f')
+        # Output: True
+        >>> bsc_address('0x4g5acf9684652BEa56F2f01b7101a225Eh33d23z')
+        # Output: ValidationError(func=bsc_address, args=...)
+
+    Args:
+        value:
+            BSC address string to validate.
+
+    Returns:
+        (Literal[True]): If `value` is a valid bsc address.
+        (ValidationError): If `value` is an invalid bsc address.
+    """
+    if not value:
+        return False
+
+    if not re.fullmatch(r"0x[a-fA-F0-9]{40}", value):
+        return False
+
+    return True

tests/crypto_addresses/test_bsc_address.py

@@ -0,0 +1,52 @@
+"""Test BSC address."""
+
+# external
+import pytest
+
+# local
+from validators import ValidationError, bsc_address
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        "0x4e5acf9684652BEa56F2f01b7101a225Ee33d23f",
+        "0x22B0f92af10FdC25659e4C3A590c2F0D0c809c27",
+        "0xb61724F993E7942ef2d8e4A94fF7c9e1cc26995F",
+        "0x9c3dF8a511Fec8076D4B8EFb4d5E733B9F953dD7",
+        "0x4536337B91c0623a4FD098023E6065e4773117c5",
+        "0xAC484e1CE274eD1d40A7C2AeAb0bEA863634286F",
+        "0x1FDE521fBe3483Cbb5957E6275028225a74387e4",
+        "0x1693c3D1bA787Ba2bf81ac8897614AAaee5cb800",
+        "0xf4C3Fd476A40658aEd9e595DA49c37d8965D2fFE",
+        "0xc053E3D4932640787D6Cf67FcA36021E7BE62653",
+        "0xaFd563A5aED0bC363e802842aD93Af46c1168b8a",
+    ],
+)
+def test_returns_true_on_valid_bsc_address(value: str):
+    """Test returns true on valid bsc address."""
+    assert bsc_address(value)
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        "1x32Be343B94f860124dC4fEe278FDCBD38C102D88",
+        "0x32Be343B94f860124dC4fEe278FDCBD38C102D",
+        "0x32Be343B94f860124dC4fEe278FDCBD38C102D88aabbcc",
+        "0x4g5acf9684652BEa56F2f01b7101a225Eh33d23z",
+        "0x",
+        "[email protected]",
+        "0x32Be343B94f860124dC4fEe278FDCBD38C102D__",
+        "0x32Be343B94f860124dC4fEe278FDCBD38C102D88G",
+        "0X32Be343B94f860124dC4fEe278FDCBD38C102D88",
+        "0X32BE343B94F860124DCFEE278FDCBD38C102D88",
+        "0x32Be 343B94f860124dC4fEe278FDCBD38C102D88",
+        "0x32Be343B94f860124dC4fEe278FDCBD38C102D88!",
+        "ox32Be343B94f860124dC4fEe278FDCBD38C102D88",
+        "0x32Be343B94f860124dC4fEe278FDCBD38C102D88XYZ",
+    ],
+)
+def test_returns_failed_validation_on_invalid_bsc_address(value: str):
+    """Test returns failed validation on invalid bsc address."""
+    assert isinstance(bsc_address(value), ValidationError)