From cd01b4b4bc4954dc72ca35c6a8c41010ed9a8638 Mon Sep 17 00:00:00 2001
From: Mehdi Samsami <mehdisamsami@live.com>
Date: Wed, 10 Jul 2024 14:48:00 +0330
Subject: [PATCH] add a new validator for sha384 hash (#387)

---
 CHANGES.md                 | 18 ++++++++++++++++++
 SECURITY.md                |  2 +-
 docs/api/hashes.md         |  1 +
 docs/api/hashes.rst        |  1 +
 src/validators/__init__.py |  5 +++--
 src/validators/hashes.py   | 24 ++++++++++++++++++++++++
 tests/test_hashes.py       | 34 ++++++++++++++++++++++++++++++++--
 7 files changed, 80 insertions(+), 5 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 3e069692..46517366 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -9,6 +9,24 @@ Note to self: Breaking changes must increment either
 
 -->
 
+## 0.32.0 (2024-07-10)
+
+_**Breaking**_
+
+> No breaking changes were introduced in this version.
+
+_**Features**_
+
+- feat: add validator for `sha384` hash by @msamsami in [#387](https://github.com/python-validators/validators/pull/387)
+
+_**Maintenance**_
+
+- maint: bump version by @msamsami in [#387](https://github.com/python-validators/validators/pull/387)
+
+**Full Changelog**: [`0.31.0...0.32.0`](https://github.com/python-validators/validators/compare/0.31.0...0.32.0)
+
+---
+
 ## 0.31.0 (2024-07-08)
 
 _**Breaking**_
diff --git a/SECURITY.md b/SECURITY.md
index dbf9c090..d828d524 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -4,7 +4,7 @@
 
 | Version    | Supported          |
 | ---------- | ------------------ |
-| `>=0.31.0` | :white_check_mark: |
+| `>=0.32.0` | :white_check_mark: |
 
 ## Reporting a Vulnerability
 
diff --git a/docs/api/hashes.md b/docs/api/hashes.md
index 82b11bf0..8daeb033 100644
--- a/docs/api/hashes.md
+++ b/docs/api/hashes.md
@@ -4,4 +4,5 @@
 ::: validators.hashes.sha1
 ::: validators.hashes.sha224
 ::: validators.hashes.sha256
+::: validators.hashes.sha384
 ::: validators.hashes.sha512
diff --git a/docs/api/hashes.rst b/docs/api/hashes.rst
index bc77b7b2..e8c15e5b 100644
--- a/docs/api/hashes.rst
+++ b/docs/api/hashes.rst
@@ -6,4 +6,5 @@ hashes
 .. autofunction:: sha1
 .. autofunction:: sha224
 .. autofunction:: sha256
+.. autofunction:: sha384
 .. autofunction:: sha512
diff --git a/src/validators/__init__.py b/src/validators/__init__.py
index cf11e3a7..3dfe1634 100644
--- a/src/validators/__init__.py
+++ b/src/validators/__init__.py
@@ -10,7 +10,7 @@
 from .email import email
 from .encoding import base16, base32, base58, base64
 from .finance import cusip, isin, sedol
-from .hashes import md5, sha1, sha224, sha256, sha512
+from .hashes import md5, sha1, sha224, sha256, sha384, sha512
 from .hostname import hostname
 from .i18n import (
     es_cif,
@@ -73,6 +73,7 @@
     "sha1",
     "sha224",
     "sha256",
+    "sha384",
     "sha512",
     # ...
     "hostname",
@@ -107,4 +108,4 @@
     "validator",
 )
 
-__version__ = "0.31.0"
+__version__ = "0.32.0"
diff --git a/src/validators/hashes.py b/src/validators/hashes.py
index 6004d30a..e544f7fe 100644
--- a/src/validators/hashes.py
+++ b/src/validators/hashes.py
@@ -94,6 +94,30 @@ def sha256(value: str, /):
     return re.match(r"^[0-9a-f]{64}$", value, re.IGNORECASE) if value else False
 
 
+@validator
+def sha384(value: str, /):
+    """Return whether or not given value is a valid SHA384 hash.
+
+    Examples:
+        >>> sha384(
+        ...     'cb00753f45a35e8bb5a03d699ac65007272c32ab0eded163'
+        ...     '1a8b605a43ff5bed8086072ba1e7cc2358baeca134c825a7'
+        ... )
+        # Output: True
+        >>> sha384('900zz11')
+        # Output: ValidationError(func=sha384, args={'value': '900zz11'})
+
+    Args:
+        value:
+            SHA384 string to validate.
+
+    Returns:
+        (Literal[True]): If `value` is a valid SHA384 hash.
+        (ValidationError): If `value` is an invalid SHA384 hash.
+    """
+    return re.match(r"^[0-9a-f]{96}$", value, re.IGNORECASE) if value else False
+
+
 @validator
 def sha512(value: str, /):
     """Return whether or not given value is a valid SHA512 hash.
diff --git a/tests/test_hashes.py b/tests/test_hashes.py
index 39af2c4d..64f0affc 100644
--- a/tests/test_hashes.py
+++ b/tests/test_hashes.py
@@ -4,7 +4,7 @@
 import pytest
 
 # local
-from validators import ValidationError, base58, base64, md5, sha1, sha224, sha256, sha512
+from validators import ValidationError, base58, base64, md5, sha1, sha224, sha256, sha384, sha512
 
 # ==> base58 <== #
 
@@ -158,7 +158,37 @@ def test_returns_failed_validation_on_invalid_sha256(value: str):
     assert isinstance(sha256(value), ValidationError)
 
 
-# ==> sha256 <== #
+# ==> sha384 <== #
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        "cb00753f45a35e8bb5a03d699ac65007272c32ab0eded1631a8b605a43ff5bed8086072ba1e7cc2358baeca134c825a7",
+        "CB00753F45A35E8BB5A03D699AC65007272C32AB0EDED1631A8B605A43FF5BED8086072BA1E7CC2358BAECA134C825A7",
+        "bfd76c0ebbd006fee583410547c1887b0292be76d582d96c242d2a792723e3fd6fd061f9d5cfd13b8f961358e6adba4a",
+        "F21EF1F8DBF806106813C8504AF864D8D9BFDFA8D67FA9B7DFF1C5B61C2584394A05897C4F157CEEE0E8FBC29205BB8B",
+    ],
+)
+def test_returns_true_on_valid_sha384(value: str):
+    """Test returns true on valid sha384."""
+    assert sha384(value)
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        "zb00753f45a35e8bb5a03d699ac65007272c32ab0eded1631a8b605a43ff5bed8086072ba1e7cc2358baeca134c825a7",
+        "c753f45a35e8bb5a03d699ac65007272c32ab0eded1631a8b605a43ff5bed8086072ba1e7cc2358baeca134c825a7",
+        "cb00aaaa753f45a35e8bb5a03d699ac65007272c32ab0eded1631a8b605a43ff5bed8086072ba1e7cc2358baeca134c825a7",
+    ],
+)
+def test_returns_failed_validation_on_invalid_sha384(value: str):
+    """Test returns failed validation on invalid sha384."""
+    assert isinstance(sha384(value), ValidationError)
+
+
+# ==> sha512 <== #
 
 
 @pytest.mark.parametrize(