Add IP address field type.

AUTHORS.rst

@@ -142,3 +142,4 @@ Contributors (chronological)
 - Nikolay Shebanov `@killthekitten <https://github.com/killthekitten>`_
 - Taneli Hukkinen `@hukkinj1 <https://github.com/hukkinj1>`_
 - `@Reskov <https://github.com/Reskov>`_
+- Michał Getka `@mgetka <https://github.com/mgetka>`_

src/marshmallow/fields.py

@@ -5,6 +5,7 @@
 import datetime as dt
 import numbers
 import uuid
+import ipaddress
 import decimal
 import math
 import typing
@@ -50,6 +51,9 @@
     "Url",
     "URL",
     "Email",
+    "IP",
+    "IPv4",
+    "IPv6",
     "Method",
     "Function",
     "Str",
@@ -1634,6 +1638,91 @@ def __init__(self, *args, **kwargs):
         self.validators = [validator] + original_validators
 
 
+class IP(String):
+    """A IP address field.
+
+    :param bool exploded: If `True`, serialize ipv6 address in long form, ie. with groups
+        consisting entirely of zeros included."""
+
+    default_error_messages = {"invalid_ip": "Not a valid IP address."}
+
+    def __init__(self, *args, exploded=False, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.exploded = exploded
+
+    def _validated(
+        self, value
+    ) -> typing.Optional[typing.Union[ipaddress.IPv4Address, ipaddress.IPv6Address]]:
+        """Format the value or raise a :exc:`ValidationError` if an error occurs."""
+        if value is None:
+            return None
+        try:
+            if isinstance(value, (int, bytes)):
+                # ip_address function is flexible in the terms of input value. In the case of
+                # marshalling, integer and binary address representation parsing may lead to
+                # confusion.
+                raise TypeError(
+                    "Only dot-decimal and hexadecimal groups notations are supported."
+                )
+            return ipaddress.ip_address(value)
+        except (ValueError, TypeError) as error:
+            raise self.make_error("invalid_ip") from error
+
+    def _serialize(self, value, attr, obj, **kwargs) -> typing.Optional[str]:
+        if value is not None and self.exploded:
+            value = value.exploded
+        return super()._serialize(value, attr, obj, **kwargs)
+
+    def _deserialize(
+        self, value, attr, data, **kwargs
+    ) -> typing.Optional[typing.Union[ipaddress.IPv4Address, ipaddress.IPv6Address]]:
+        return self._validated(value)
+
+
+class IPv4(IP):
+    """A IPv4 address field."""
+
+    default_error_messages = {"invalid_ip": "Not a valid IPv4 address."}
+
+    def _validated(self, value) -> typing.Optional[ipaddress.IPv4Address]:
+        """Format the value or raise a :exc:`ValidationError` if an error occurs."""
+        if value is None:
+            return None
+        try:
+            if isinstance(value, (int, bytes)):
+                raise TypeError("Only dot-decimal notation is supported.")
+            return ipaddress.IPv4Address(value)
+        except (ValueError, TypeError) as error:
+            raise self.make_error("invalid_ip") from error
+
+    def _deserialize(
+        self, value, attr, data, **kwargs
+    ) -> typing.Optional[ipaddress.IPv4Address]:
+        return self._validated(value)
+
+
+class IPv6(IP):
+    """A IPv6 address field."""
+
+    default_error_messages = {"invalid_ip": "Not a valid IPv6 address."}
+
+    def _validated(self, value) -> typing.Optional[ipaddress.IPv6Address]:
+        """Format the value or raise a :exc:`ValidationError` if an error occurs."""
+        if value is None:
+            return None
+        try:
+            if isinstance(value, (int, bytes)):
+                raise TypeError("Only dot-decimal notation is supported.")
+            return ipaddress.IPv6Address(value)
+        except (ValueError, TypeError) as error:
+            raise self.make_error("invalid_ip") from error
+
+    def _deserialize(
+        self, value, attr, data, **kwargs
+    ) -> typing.Optional[ipaddress.IPv6Address]:
+        return self._validated(value)
+
+
 class Method(Field):
     """A field that takes the value returned by a `Schema` method.
 

tests/test_deserialization.py

@@ -1,5 +1,6 @@
 import datetime as dt
 import uuid
+import ipaddress
 import decimal
 import math
 
@@ -841,6 +842,83 @@ def test_invalid_uuid_deserialization(self, in_value):
 
         assert excinfo.value.args[0] == "Not a valid UUID."
 
+    def test_ip_field_deserialization(self):
+        field = fields.IP()
+        ipv4_str = "140.82.118.3"
+        result = field.deserialize(ipv4_str)
+        assert isinstance(result, ipaddress.IPv4Address)
+        assert str(result) == ipv4_str
+
+        ipv4 = ipaddress.ip_address("172.217.16.206")
+        result = field.deserialize(ipv4)
+        assert isinstance(result, ipaddress.IPv4Address)
+        assert result == ipv4
+
+        ipv6_str = "2a00:1450:4001:824::200e"
+        result = field.deserialize(ipv6_str)
+        assert isinstance(result, ipaddress.IPv6Address)
+        assert str(result) == ipv6_str
+
+        ipv6 = ipaddress.ip_address("2a00:1450:4001:81d::200e")
+        result = field.deserialize(ipv6)
+        assert isinstance(result, ipaddress.IPv6Address)
+        assert result == ipv6
+
+    @pytest.mark.parametrize(
+        "in_value", ["malformed", 123, b"\x01\x02\03", "192.168", "ff::aa:1::2"]
+    )
+    def test_invalid_ip_deserialization(self, in_value):
+        field = fields.IP()
+        with pytest.raises(ValidationError) as excinfo:
+            field.deserialize(in_value)
+
+        assert excinfo.value.args[0] == "Not a valid IP address."
+
+    def test_ipv4_field_deserialization(self):
+        field = fields.IPv4()
+        ipv4_str = "140.82.118.3"
+        result = field.deserialize(ipv4_str)
+        assert isinstance(result, ipaddress.IPv4Address)
+        assert str(result) == ipv4_str
+
+        ipv4 = ipaddress.ip_address("172.217.16.206")
+        result = field.deserialize(ipv4)
+        assert isinstance(result, ipaddress.IPv4Address)
+        assert result == ipv4
+
+    @pytest.mark.parametrize(
+        "in_value",
+        ["malformed", 123, b"\x01\x02\03", "192.168", "2a00:1450:4001:81d::200e"],
+    )
+    def test_invalid_ipv4_deserialization(self, in_value):
+        field = fields.IPv4()
+        with pytest.raises(ValidationError) as excinfo:
+            field.deserialize(in_value)
+
+        assert excinfo.value.args[0] == "Not a valid IPv4 address."
+
+    def test_ipv6_field_deserialization(self):
+        field = fields.IPv6()
+        ipv6_str = "2a00:1450:4001:824::200e"
+        result = field.deserialize(ipv6_str)
+        assert isinstance(result, ipaddress.IPv6Address)
+        assert str(result) == ipv6_str
+
+        ipv6 = ipaddress.ip_address("2a00:1450:4001:81d::200e")
+        result = field.deserialize(ipv6)
+        assert isinstance(result, ipaddress.IPv6Address)
+        assert result == ipv6
+
+    @pytest.mark.parametrize(
+        "in_value", ["malformed", 123, b"\x01\x02\03", "ff::aa:1::2", "192.168.0.1"]
+    )
+    def test_invalid_ipv6_deserialization(self, in_value):
+        field = fields.IPv6()
+        with pytest.raises(ValidationError) as excinfo:
+            field.deserialize(in_value)
+
+        assert excinfo.value.args[0] == "Not a valid IPv6 address."
+
     def test_deserialization_function_must_be_callable(self):
         with pytest.raises(ValueError):
             fields.Function(lambda x: None, deserialize="notvalid")

tests/test_serialization.py

@@ -4,6 +4,7 @@
 import itertools
 import decimal
 import uuid
+import ipaddress
 
 import pytest
 
@@ -143,6 +144,56 @@ def test_uuid_field(self, user):
         assert field.serialize("uuid1", user) == "12345678-1234-5678-1234-567812345678"
         assert field.serialize("uuid2", user) is None
 
+    def test_ip_address_field(self, user):
+
+        ipv4_string = "192.168.0.1"
+        ipv6_string = "ffff::ffff"
+        ipv6_exploded_string = ipaddress.ip_address("ffff::ffff").exploded
+
+        user.ipv4 = ipaddress.ip_address(ipv4_string)
+        user.ipv6 = ipaddress.ip_address(ipv6_string)
+        user.empty_ip = None
+
+        field_compressed = fields.IP()
+        assert isinstance(field_compressed.serialize("ipv4", user), str)
+        assert field_compressed.serialize("ipv4", user) == ipv4_string
+        assert isinstance(field_compressed.serialize("ipv6", user), str)
+        assert field_compressed.serialize("ipv6", user) == ipv6_string
+        assert field_compressed.serialize("empty_ip", user) is None
+
+        field_exploded = fields.IP(exploded=True)
+        assert isinstance(field_exploded.serialize("ipv6", user), str)
+        assert field_exploded.serialize("ipv6", user) == ipv6_exploded_string
+
+    def test_ipv4_address_field(self, user):
+
+        ipv4_string = "192.168.0.1"
+
+        user.ipv4 = ipaddress.ip_address(ipv4_string)
+        user.empty_ip = None
+
+        field = fields.IPv4()
+        assert isinstance(field.serialize("ipv4", user), str)
+        assert field.serialize("ipv4", user) == ipv4_string
+        assert field.serialize("empty_ip", user) is None
+
+    def test_ipv6_address_field(self, user):
+
+        ipv6_string = "ffff::ffff"
+        ipv6_exploded_string = ipaddress.ip_address("ffff::ffff").exploded
+
+        user.ipv6 = ipaddress.ip_address(ipv6_string)
+        user.empty_ip = None
+
+        field_compressed = fields.IPv6()
+        assert isinstance(field_compressed.serialize("ipv6", user), str)
+        assert field_compressed.serialize("ipv6", user) == ipv6_string
+        assert field_compressed.serialize("empty_ip", user) is None
+
+        field_exploded = fields.IPv6(exploded=True)
+        assert isinstance(field_exploded.serialize("ipv6", user), str)
+        assert field_exploded.serialize("ipv6", user) == ipv6_exploded_string
+
     def test_decimal_field(self, user):
         user.m1 = 12
         user.m2 = "12.355"