source-code/pydantic.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "1815b3b2-da56-41f3-8b45-eb35797959ce",
   "metadata": {},
   "source": [
    "## Requirments"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "id": "b2ba87d0-2447-4a4d-9bae-eb0e86d39ce1",
   "metadata": {},
   "outputs": [],
   "source": [
    "from dataclasses import dataclass\n",
    "from pydantic import BaseModel, Field, ValidationError, field_validator\n",
    "import sys"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e3bc816e-fe2a-4597-81ab-a83ae04407f6",
   "metadata": {},
   "source": [
    "## Introduction"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b5cea6f9-af02-4803-8e97-975006d52918",
   "metadata": {},
   "source": [
    "`pydantic` is a Python library to represent data.  It is similar to Python's `dataclass`, but with more features, especially for data validation. `pydantic` relies heavily on type annotations."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f81b5b6f-8a74-4a1d-bc87-eff52b38daf2",
   "metadata": {},
   "source": [
    "## Simple example"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "54753352-22c5-46fc-8e9f-36b72ba306f1",
   "metadata": {},
   "source": [
    "Defining a class is as simple as listing the object's attributes, similar to Python's own `dataclass`.  However, rather than using a decorator, a `pydantic` class is derived from `BaseModel`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "5dae15fd-1651-40bf-9118-53a79b2584be",
   "metadata": {},
   "outputs": [],
   "source": [
    "class Person(BaseModel):\n",
    "    id: int\n",
    "    age: int\n",
    "    name: str"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f6292052-b2e1-4853-8f82-69aec2b6b3d1",
   "metadata": {},
   "source": [
    "Creating objects of type `Person` is done the usual way."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "92961e53-af98-4d88-88c3-90e97f21c4cb",
   "metadata": {},
   "outputs": [],
   "source": [
    "p1 = Person(id=1, age=72, name='Maria')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "24c5769e-70c8-41d7-b619-32bb78adf5f2",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Person(id=1, age=72, name='Maria')"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "p1"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a13d1936-2030-4fd1-9b7a-3481d7071041",
   "metadata": {},
   "source": [
    "However, when you try do do so using values of an inapropriate type, a `ValidationError` will be raised."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "5f37d3e0-8255-4a61-920c-904f17c6ab78",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "1 validation error for Person\n",
      "age\n",
      "  Input should be a valid integer, unable to parse string as an integer [type=int_parsing, input_value='old', input_type=str]\n",
      "    For further information visit https://errors.pydantic.dev/2.9/v/int_parsing\n"
     ]
    }
   ],
   "source": [
    "try:\n",
    "    _ = Person(id=1, age='old', name='Maria')\n",
    "except ValidationError as e:\n",
    "    print(e, file=sys.stderr)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c2f0f7bd-80ce-4a43-9ea6-a7af5870dd20",
   "metadata": {},
   "source": [
    "In the example above, the string `'old'` can not be converted to an integer.  The example below is more interesting, since the integer `12` could be converted to a string for the `name` attribute."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "96390816-716c-43f8-92eb-dd437e8fc6fd",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "1 validation error for Person\n",
      "name\n",
      "  Input should be a valid string [type=string_type, input_value=12, input_type=int]\n",
      "    For further information visit https://errors.pydantic.dev/2.9/v/string_type\n"
     ]
    }
   ],
   "source": [
    "try:\n",
    "    _ = Person(id=1, age=72, name=12)\n",
    "except ValidationError as e:\n",
    "    print(e, file=sys.stderr)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d1ecd1ae-f656-4c75-934a-ccc6dd7a74e8",
   "metadata": {},
   "source": [
    "It is interesing to compare this with Python's `dataclass`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "947e17e9-6f29-4055-9967-8cfe534ea859",
   "metadata": {},
   "outputs": [],
   "source": [
    "@dataclass\n",
    "class PersonDC:\n",
    "    id: int\n",
    "    age: int\n",
    "    name: str"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "025510ae-4e50-4f22-8e1a-640f8720f844",
   "metadata": {},
   "outputs": [],
   "source": [
    "p1_dc = PersonDC(id=3, age=49, name='Betty')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "80bc56e3-7a58-43a6-834e-2570b8a776d3",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "PersonDC(id=3, age=49, name='Betty')"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "p1_dc"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "f6ae77f8-4d81-4b1f-8333-eaa2eb30197a",
   "metadata": {},
   "outputs": [],
   "source": [
    "p2_dc = PersonDC(id=4, age='old', name='Jonas') "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8203efba-05d7-4195-96a0-6969788ad2ea",
   "metadata": {},
   "source": [
    "As you can see, a Python `dataclass` will not perform validation out-of-the-box."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c31de1d8-2744-48b7-9914-bfeb90cfdac0",
   "metadata": {},
   "source": [
    "## Serialization/deserialization"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "383c3859-80cd-45e6-97e9-a8320b64ad7c",
   "metadata": {},
   "source": [
    "`pydantic` objects can be easily serialized to JSON."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "3ebb2a0a-b60b-43c1-a88c-fc970d654dd9",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'{\"id\":1,\"age\":72,\"name\":\"Maria\"}'"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "p1.json()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "db16bf30-2d00-4fd4-9107-20b9c89709de",
   "metadata": {},
   "source": [
    "The inverse, deserialization from JSON is trivial as well."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "98dfe2f1-789e-4cd5-99bb-e2ec4ef48142",
   "metadata": {},
   "outputs": [],
   "source": [
    "json_str = '''\n",
    "    {\n",
    "        \"id\": 2,\n",
    "        \"age\": 15,\n",
    "        \"name\": \"Berthe\"\n",
    "    }\n",
    "'''"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "b3c5bcb1-de73-4de2-9a9e-88d4e876d7d6",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Person(id=2, age=15, name='Berthe')"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Person.model_validate_json(json_str)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d49ae9d5-d6c0-4772-946b-a8adcebac485",
   "metadata": {},
   "source": [
    "When the JSON representation doesn't represent a valid `Person`, a `ValidationError` is raised."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "e4f98cae-58b0-4b5e-ac77-85f8e57f800e",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "1 validation error for Person\n",
      "  Invalid JSON: expected `:` at line 1 column 31 [type=json_invalid, input_value='{\"id\": 5, \"age\": \"old\", \"name\"=\"Johnny\"}', input_type=str]\n",
      "    For further information visit https://errors.pydantic.dev/2.9/v/json_invalid\n"
     ]
    }
   ],
   "source": [
    "json_str = '{\"id\": 5, \"age\": \"old\", \"name\"=\"Johnny\"}'\n",
    "try:\n",
    "    _ = Person.model_validate_json(json_str)\n",
    "except ValidationError as e:\n",
    "    print(e, file=sys.stderr)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "db1078b8-07c5-4bd0-8362-71fd9acbd0b7",
   "metadata": {},
   "source": [
    "## Inheritance"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "83cd4a01-b8fa-4565-9a2c-b1939dca5a40",
   "metadata": {},
   "source": [
    "A child is of course a person, but aged younger than 18.  The `Child` class can be derived from the `Person` class, but with a restriction on its age.  In order to enforce this, the attribute should be a `pydantic` `Field` object.  The latter has a `lt` attribute, which stand for 'less than'."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "2af3c27c-7358-4180-a929-0f2e0116074a",
   "metadata": {},
   "outputs": [],
   "source": [
    "class Child(Person):\n",
    "    age: int = Field(ge=0, lt=18)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b205fbbb-0de2-46ed-ab97-d9338481386c",
   "metadata": {},
   "source": [
    "Note that also the niminum age was specified.  Of course, it would have made more sense to define that for `Child`'s parent class, `Person`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "e1477db3-ee12-4ce4-9f4f-6eb636a6494c",
   "metadata": {},
   "outputs": [],
   "source": [
    "p2 = Child(id=3, age=5, name='Bert')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2c71bc79-aa6e-4ba7-b758-aee6499d6a23",
   "metadata": {},
   "source": [
    "When you try to create a `Child` object with an inappropriate age, a `ValidationError` is raised."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "876b79ae-ef8d-4c3b-990c-289b434b5ff7",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "1 validation error for Child\n",
      "age\n",
      "  Input should be less than 18 [type=less_than, input_value=20, input_type=int]\n",
      "    For further information visit https://errors.pydantic.dev/2.9/v/less_than\n"
     ]
    }
   ],
   "source": [
    "try:\n",
    "    _ = Child(id=4, age=20, name='Annie')\n",
    "except ValidationError as e:\n",
    "    print(e, file=sys.stderr)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f931372f-aaf2-45fe-aa10-c44986898066",
   "metadata": {},
   "source": [
    "## Schema"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "7d14fd4c-b640-44a9-a268-c0ce6bb204d5",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'properties': {'id': {'title': 'Id', 'type': 'integer'},\n",
       "  'age': {'title': 'Age', 'type': 'integer'},\n",
       "  'name': {'title': 'Name', 'type': 'string'}},\n",
       " 'required': ['id', 'age', 'name'],\n",
       " 'title': 'Person',\n",
       " 'type': 'object'}"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Person.model_json_schema()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "4f752bbc-357d-4cea-9c80-67cdbd7e162f",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'properties': {'id': {'title': 'Id', 'type': 'integer'},\n",
       "  'age': {'exclusiveMaximum': 18,\n",
       "   'minimum': 0,\n",
       "   'title': 'Age',\n",
       "   'type': 'integer'},\n",
       "  'name': {'title': 'Name', 'type': 'string'}},\n",
       " 'required': ['id', 'age', 'name'],\n",
       " 'title': 'Child',\n",
       " 'type': 'object'}"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Child.model_json_schema()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 52,
   "id": "e258a4a6-57a7-4d97-8e43-de758a0bfdfb",
   "metadata": {},
   "outputs": [],
   "source": [
    "class BetterPerson(BaseModel):\n",
    "    id: int = Field(ge=0)\n",
    "    first_name: str = Field(pattern=r'^[A-Za-z- ]+$')\n",
    "    last_name: str = Field(pattern=r'^[A-Za-z- ]+$')\n",
    "    age: int\n",
    "\n",
    "    @field_validator('age')\n",
    "    @classmethod\n",
    "    def validate_age(cls, age: int):\n",
    "        if age < 0 or age > 120:\n",
    "            raise ValueError('age should be between 0 and 120')\n",
    "        return age"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 53,
   "id": "bf502769-46df-444b-b1be-111d7cd3bf48",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "1 validation error for BetterPerson\n",
      "last_name\n",
      "  String should match pattern '^[A-Za-z- ]+$' [type=string_pattern_mismatch, input_value='Knuth45', input_type=str]\n",
      "    For further information visit https://errors.pydantic.dev/2.9/v/string_pattern_mismatch\n"
     ]
    }
   ],
   "source": [
    "try:\n",
    "    _ = BetterPerson(id=0, first_name='A', last_name='Knuth45', age=68)\n",
    "except ValidationError as e:\n",
    "    print(e, file=sys.stderr)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 54,
   "id": "5aa72e5f-5171-4e0e-82ff-d62c228b911c",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "BetterPerson(id=0, first_name='Geert Jan', last_name='Bex', age=68)"
      ]
     },
     "execution_count": 54,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "BetterPerson(id=0, first_name='Geert Jan', last_name='Bex', age=68)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 55,
   "id": "85159c48-bdac-4148-9c6c-09de689f5635",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "1 validation error for BetterPerson\n",
      "age\n",
      "  Value error, age should be between 0 and 120 [type=value_error, input_value=150, input_type=int]\n",
      "    For further information visit https://errors.pydantic.dev/2.9/v/value_error\n"
     ]
    }
   ],
   "source": [
    "try:\n",
    "    _ = BetterPerson(id=7, first_name='Jack', last_name='Ripper', age=150)\n",
    "except ValidationError as e:\n",
    "    print(e, file=sys.stderr)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bd6e1e95-5843-4586-883f-838bc3d45160",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}