chore(feat): Support OTP as a type

pydantic_extra_types/__init__.py

@@ -8,6 +8,7 @@
     CountryNumericCode,
     CountryOfficialName,
     CountryShortName,
+    OTPToken,
     PaymentCardBrand,
     PaymentCardNumber,
     PhoneNumber,
@@ -25,4 +26,5 @@
     'CountryNumericCode',
     'CountryOfficialName',
     'PhoneNumber',
+    'OTPToken',
 )

pydantic_extra_types/types/__init__.py

@@ -6,6 +6,7 @@
     CountryOfficialName,
     CountryShortName,
 )
+from pydantic_extra_types.types.otp import OTPToken
 from pydantic_extra_types.types.payment import PaymentCardBrand, PaymentCardNumber
 from pydantic_extra_types.types.phone_numbers import PhoneNumber
 from pydantic_extra_types.types.routing_number import ABARoutingNumber
@@ -21,4 +22,5 @@
     'CountryNumericCode',
     'CountryOfficialName',
     'PhoneNumber',
+    'OTPToken',
 )

pydantic_extra_types/types/otp.py

@@ -0,0 +1,29 @@
+from typing import Any
+
+import pyotp
+from pydantic_core import PydanticCustomError
+
+
+class OTPToken(str):
+    """A one-time password token.
+
+    This is a custom type that can be used to validate a one-time password token
+    against a secret key. The secret key is passed in the context argument of
+    the model_validate method.
+
+    The type also has a custom JSON encoder that returns the current one-time
+    password token for the secret key.
+    """
+
+    @staticmethod
+    def model_validate(value: Any, *, context: Any) -> Any:
+        if not pyotp.TOTP(context['otp_secret']).verify(value):
+            raise PydanticCustomError('Invalid one-time password', value)
+        return value
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls) -> Any:
+        yield cls.model_validate
+
+    class Config:
+        json_encoders = {pyotp.TOTP: lambda v: v.now()}

pyproject.toml

@@ -39,7 +39,8 @@ classifiers = [
 requires-python = '>=3.7'
 dependencies = [
     'pydantic@git+https://github.com/pydantic/pydantic.git@main',
-    'phonenumbers'
+    'phonenumbers',
+    'pyotp >=2.0.0,<2.8.0',
 ]
 dynamic = ['version']
 

requirements/pyproject.txt

@@ -12,5 +12,7 @@ pydantic @ git+https://github.com/pydantic/pydantic.git@main
     # via pydantic-extra-types (pyproject.toml)
 pydantic-core==0.38.0
     # via pydantic
+pyotp==2.7.0
+    # via pydantic-extra-types (pyproject.toml)
 typing-extensions==4.6.3
     # via pydantic

tests/test_types_otp.py

@@ -0,0 +1,35 @@
+import pyotp
+import pytest
+from pydantic_core import PydanticCustomError
+
+from pydantic_extra_types import OTPToken
+
+
+def test_model_validate():
+    secret = 'JBSWY3DPEHPK3PXP'
+    totp = pyotp.TOTP(secret)
+    value = totp.now()
+    context = {'otp_secret': secret}
+    # Test a valid OTP token
+    result = OTPToken.model_validate(value, context=context)
+    assert result == value
+
+    # Test an invalid OTP token
+    with pytest.raises(PydanticCustomError, match='Invalid one-time password'):
+        OTPToken.model_validate('Invalid one-time password', context=context)
+
+
+def test_json_encoder():
+    secret = 'JBSWY3DPEHPK3PXP'
+    totp = pyotp.TOTP(secret)
+    value = totp.now()
+
+    # Test the custom JSON encoder
+    json_encoded_value = OTPToken.Config.json_encoders[pyotp.TOTP](totp)
+    assert json_encoded_value == value
+
+
+def test___get_pydantic_core_schema__():
+    # Test the get_validators method
+    validators = list(OTPToken.__get_pydantic_core_schema__())
+    assert validators == [OTPToken.model_validate]