demo/pydantic.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5a244171-3219-4bd5-9c97-ae59c7621536",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "!pip install pydantic"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0d596cd1-9e07-4d91-8903-1f28cc011c9f",
   "metadata": {},
   "source": [
    "## Processing data using dicts\n",
    "\n",
    "Dictionaries are the backbone of python data structures, but it is very easy to miss errors with them because they do not enforce what kind of data you put into them."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "690a8ae9-69a8-4fa9-8a5b-7e653e268263",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "def report_pet(pet_dict):\n",
    "    print(f\"My name is {pet_dict['name']} and I need {pet_dict['n_legs'] / 2} pairs of pants\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "38adc86e-7f71-43d2-baa8-1567c339ec4b",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "json_1 = {\"name\": \"Mittens\", \"n_legs\": 4}\n",
    "json_2 = {\"name\": \"Slither\", \"n_legs\": 0}\n",
    "json_3 = {\"name\": \"Skitter\", \"n_legs\": \"8\"}\n",
    "json_4 = {\"n_legs\": 6}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "59e2d709-11fd-4003-b425-5157c8dfa3c1",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "report_pet(json_1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f455fb8e-d89a-4480-b957-c68c1ab2352b",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "report_pet(json_2)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c28bfe76-1e30-4b8f-9c8d-07df4ce36ec4",
   "metadata": {},
   "source": [
    "The first two pets work fine because their dictionaries have data that happens to be valid. But things start to go wrong if we pass the wrong data type"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "01d1833f-9931-4800-b445-bee966e91606",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "report_pet(json_3)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5fc6b993-72b6-4046-8108-0c2bff3c50b0",
   "metadata": {},
   "source": [
    "This error only comes up when we run our function to report on the pet - it doesn't check the data any earlier."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bdf85d03-10ff-4a95-a545-498f59910610",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "report_pet(json_4)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e4075caa-33fc-4139-a710-7683a2aebb7b",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2023-07-27T13:36:02.207076Z",
     "iopub.status.busy": "2023-07-27T13:36:02.206472Z",
     "iopub.status.idle": "2023-07-27T13:36:02.210591Z",
     "shell.execute_reply": "2023-07-27T13:36:02.209948Z",
     "shell.execute_reply.started": "2023-07-27T13:36:02.207056Z"
    },
    "tags": []
   },
   "source": [
    "And when our dictionary is missing an entire field, we need to figure out what the \"key error\" is."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f67db9a6-3861-45c5-917b-468afe93344f",
   "metadata": {},
   "source": [
    "## Processing data with Pydantic"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "47e53073-a6db-4986-a5da-17015803ff83",
   "metadata": {},
   "source": [
    "[Pydantic](https://docs.pydantic.dev/latest/https://docs.pydantic.dev/latest/) uses python type hints to define a class - a way of stating the exact shape of data we expect to receive."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b91eb9a1-37b1-4456-bf76-27939bebde1d",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "from pydantic import BaseModel\n",
    "\n",
    "class PydanticPet(BaseModel):\n",
    "    name: str\n",
    "    n_legs: int\n",
    "\n",
    "def report_pypet(pypet: PydanticPet):\n",
    "    print(f\"My name is {pypet.name} and I need {pypet.n_legs / 2} pairs of pants\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e3d62f5e-8077-4c5f-805d-6987f108e683",
   "metadata": {},
   "source": [
    "Note that we aren't accessing dictionary keys with `[\"strings\"]` that may or may not succeed, but instead using dot notation `pypet.name` because we _know_ that every `PydanticPet` instance has an attribute called `name`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2ce2f8c1-bcac-422c-bfef-74d3aea57489",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "pypet_1 = PydanticPet(**json_1)\n",
    "# Using ** is a python trick that passes a dictionary to a function by \"expanding\" it and putting in the key names as arugments\n",
    "# pypet_1 = PydanticPet(name=\"Mittens\", n_legs=4)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "95382aac-56dd-4997-9e1c-060b585ab8fb",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "pypet_1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2068e358-1139-4174-9571-4e07869b0f58",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "report_pypet(pypet_1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d8755600-1b92-4b9b-ba61-62e7cc5bbff6",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "pypet_2 = PydanticPet(**json_2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "77225e76-eb12-43b2-8941-1936178e2e64",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "pypet_2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "041a1ea7-7c8b-464f-8755-2fd1e1ace059",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "report_pypet(pypet_2)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8fe78f14-d817-4dbf-974a-48b05ae5a0b8",
   "metadata": {},
   "source": [
    "Pydantic can automate certain kinds of data parsing, such as converting the string `\"8\"` to the integer `8`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3a2519f3-ebdf-41d1-bda5-e342a2520a93",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "pypet_3 = PydanticPet(**json_3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e779abfa-9808-47c8-8490-f3883070c14c",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "pypet_3"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ee16367b-4cdf-48cb-8110-2f2d4bf32355",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "report_pypet(pypet_3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1b66ef5f-21f3-4b8d-b43e-12fa05800f12",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "PydanticPet(**json_4)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "da3c71cf-354d-4b22-be22-ba0eaec91afd",
   "metadata": {},
   "source": [
    "Pydantic raises a `ValidationError` that provides a clear reason why the data passed in was invalid."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b0c0aa3e-b907-4317-bb71-3615c15da220",
   "metadata": {},
   "source": [
    "## Nesting and lists\n",
    "\n",
    "Pydantic models can refer to other pydantic models, and can nest lists of data too."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0ab0b456-873c-4a68-882d-e5c1abdcfc03",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "class PetDaycare(BaseModel):\n",
    "    name: str\n",
    "    founding_year: int | None # This indicates that founding_year is an optional attribute\n",
    "    current_pets: list[PydanticPet] = []"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "01ef018e-74d3-4c89-89ad-ebd71205f584",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "local_daycare = PetDaycare(name=\"All Things That Crawl\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "570f829b-1540-40cb-84c3-1a380b63e4b6",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "local_daycare"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6a179a22-3674-4dd9-be92-d624630e482a",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "local_daycare.current_pets.append(pypet_1)\n",
    "local_daycare.current_pets.append(pypet_2)\n",
    "local_daycare.current_pets.append(pypet_3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "07beecd1-2281-4550-af8b-22780f19887c",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "local_daycare"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "68d8f84b-9073-493d-a52f-e6130c28e25f",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "for pet in local_daycare.current_pets:\n",
    "    report_pypet(pet)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1115a0bd-dcf9-4d21-b4c5-0e70d4ad7810",
   "metadata": {},
   "source": [
    "One of the biggest uses of pydantic is serializing data to JSON to be used in API servers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4de9d024-fe4d-41c0-b342-a3eed2218758",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "local_daycare.json()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "60a1fc4c-320f-4254-92a2-5a9dba595f35",
   "metadata": {},
   "source": [
    "Pydantic also can autogenerate a JSONSchema that can power API documentation pages."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7850fda9-051c-4731-904e-0ca62c7c9777",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "PetDaycare.schema()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bfe1f33c-5424-44e3-b783-e636675ddd24",
   "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.10.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}