docs/tutorials/tutorial.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "fd6e975b-cc16-4e59-a3d3-0ba34d43377f",
   "metadata": {},
   "source": [
    "# Valimp tutorial\n",
    "\n",
    "## Index\n",
    "\n",
    "- [Introduction](#Introduction)\n",
    "- [Type validation](#Type-validation)\n",
    "    - [Built-in and custom types](#Built-in-and-custom-types)\n",
    "    - [Methods](#Methods)\n",
    "    - [Dataclasses](#Dataclasses)\n",
    "    - [Type unions and optional types (the `|` operator)](#Type-unions-and-optional-types-(the-|-operator))\n",
    "    - [Validation of container items](#Validation-of-container-items)\n",
    "        - [`list`](#list-and-collections.abc.Sequence) and [`collections.abc.Sequence`](#list-and-collections.abc.Sequence)\n",
    "        - [`dict`](#dict-and-collections.abc.Mapping) and [`collections.abc.Mapping`](#dict-and-collections.abc.Mapping)\n",
    "        - [`tuple`](#tuple)\n",
    "        - [`set`](#set)\n",
    "        - [`valimp.NO_ITEM_VALIDATION`](#valimp.NO_ITEM_VALIDATION)\n",
    "        - [Nested containers](#Nested-containers)\n",
    "    - [`collections.abc.Callable`](#collections.abc.Callable)\n",
    "    - [`typing.Literal`](#typing.Literal)\n",
    "    - [*args and **kwargs](#*args-and-**kwargs)\n",
    "- [Signature validation](#Signature-validation)\n",
    "- [Coerce](#Coerce)\n",
    "    - [Type checkers](#Type-checkers)\n",
    "- [Parsing](#Parsing)\n",
    "    - [Custom validation](#Custom-validation)\n",
    "    - [Dynamic default values](#Dynamic-default-values)\n",
    "    - [parse_none](#parse_none)\n",
    "- [Coerce and parse](#Coerce-and-parse)\n",
    "\n",
    "## Notes\n",
    "\n",
    "### Error messages\n",
    "Tracebacks have been curtailed in some displayed error messages. To see a full exception as raised just execute the corresponding cells."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "914d73db-7010-4ebc-8632-d2f057af9960",
   "metadata": {},
   "source": [
    "## Introduction\n",
    "\n",
    "Valimp uses type annotations (hints) to easily validate, parse and coerce inputs to public functions, methods and dataclasses.\n",
    "\n",
    "Adding the `valimp.parse` decorator to a 'type-annotated' function or method will:\n",
    "  - validate all inputs against the type annotation, including optional type validation of items in containers.\n",
    "  - validate inputs against the function signature.\n",
    "  - provide for coercing inputs to a specific type.\n",
    "  - provide for user-defined parsing and custom validation.\n",
    "\n",
    "The same functionality is available to a 'type-annotated' `dataclasses.dataclass` by adding the `valimp.parse_cls` decorator above the dataclass decorator."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "00dd4b35-9a2c-4a5f-bfad-1b61d58c290d",
   "metadata": {},
   "source": [
    "## Type validation\n",
    "\n",
    "### Built-in and custom types\n",
    "\n",
    "Just add the `@valimp.parse` decorator to a type-annotated function. That's it!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "560cb1f4-94b8-47c6-85d5-1677ee49a730",
   "metadata": {},
   "outputs": [],
   "source": [
    "from valimp import parse\n",
    "from typing import Any\n",
    "\n",
    "class MyCustomType(int):\n",
    "    \"\"\"I don't add much.\"\"\"\n",
    "\n",
    "@parse\n",
    "def public_function(\n",
    "    a: str,\n",
    "    b: int,\n",
    "    c: list,\n",
    "    *,\n",
    "    kw_a: bool,\n",
    "    kw_b: MyCustomType,\n",
    "):\n",
    "    return"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0f25f449-dcef-424e-8c61-5a4392b0a14e",
   "metadata": {},
   "source": [
    "all the following inputs are valid..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "27271903-7384-48b7-a4e5-eb4d92d4f4dd",
   "metadata": {},
   "outputs": [],
   "source": [
    "rtrn = public_function(\n",
    "    \"a string\",\n",
    "    1,\n",
    "    [2],\n",
    "    kw_a=True,\n",
    "    kw_b=MyCustomType(4)\n",
    ")\n",
    "assert rtrn is None"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a4a31269-56d9-40bf-9b82-c9980e0f99ac",
   "metadata": {},
   "source": [
    "If at least one input is not valid then a `valimp.InputsError` is raised advising of each parameter for which an input does not conform with the corresponding type annotation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "107892a2-34a6-4eb1-800e-ecc314553ee3",
   "metadata": {},
   "outputs": [],
   "source": [
    "public_function(\n",
    "    a=[\"not a string\", \"but a list\"],  # INVALID, not a str\n",
    "    b=\"not an int\",  # INVALID, not a str\n",
    "    c=2,  # INVALID, not a list\n",
    "    kw_a=None,  # INVALID, None not an option\n",
    "    kw_b=True,  # INVALID, not the required custom type\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9aa90dee-1724-4ba5-b771-02523940be93",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "InputsError                               Traceback (most recent call last)\n",
    "Cell In[3], line 1\n",
    "----> 1 public_function(\n",
    "\n",
    "InputsError: The following inputs to 'public_function' do not conform with the corresponding type annotation:\n",
    "\n",
    "a\n",
    "\tTakes type <class 'str'> although received '['not a string', 'but a list']' of type <class 'list'>.\n",
    "\n",
    "b\n",
    "\tTakes type <class 'int'> although received 'not an int' of type <class 'str'>.\n",
    "\n",
    "c\n",
    "\tTakes type <class 'list'> although received '2' of type <class 'int'>.\n",
    "\n",
    "kw_a\n",
    "\tTakes type <class 'bool'> although received 'None' of type <class 'NoneType'>.\n",
    "\n",
    "kw_b\n",
    "\tTakes type <class '__main__.MyCustomType'> although received 'True' of type <class 'bool'>.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dcbd51c6-3d1a-4fbe-969e-f4dc485f9707",
   "metadata": {},
   "source": [
    "### Methods\n",
    "\n",
    "Works just the same for a method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "659899bb-86af-49f3-aa96-182ad63d5418",
   "metadata": {},
   "outputs": [],
   "source": [
    "class SomeClass:\n",
    "    \n",
    "    @parse\n",
    "    def public_method(\n",
    "        self,\n",
    "        a: str,\n",
    "        *,\n",
    "        kw_a: MyCustomType,\n",
    "    ):\n",
    "        return\n",
    "\n",
    "sc = SomeClass()\n",
    "# valid inputs...\n",
    "assert sc.public_method(\"a string\", kw_a=MyCustomType(4)) is None"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5d4a609b-0aa0-46bf-9bee-06a91191830e",
   "metadata": {},
   "outputs": [],
   "source": [
    "# invalid inputs...\n",
    "sc.public_method(0, kw_a=None)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3e134918-c16a-4d41-9a0d-acab1ae091b2",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "InputsError                               Traceback (most recent call last)\n",
    "Cell In[5], line 1\n",
    "----> 1 sc.public_method(0, kw_a=None)\n",
    "\n",
    "InputsError: The following inputs to 'public_method' do not conform with the corresponding type annotation:\n",
    "\n",
    "a\n",
    "\tTakes type <class 'str'> although received '0' of type <class 'int'>.\n",
    "\n",
    "kw_a\n",
    "\tTakes type <class '__main__.MyCustomType'> although received 'None' of type <class 'NoneType'>.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "330c9181-de60-43e2-aebf-3f29550486bb",
   "metadata": {},
   "source": [
    "### Dataclasses\n",
    "\n",
    "And the same functionality is available to dataclasses by using the `@parse_cls` decorator..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "2819abf2-a4a3-4125-8802-5f1f81700ed6",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'a': 'a string', 'b': 4}"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from valimp import parse_cls\n",
    "import dataclasses\n",
    "\n",
    "@parse_cls\n",
    "@dataclasses.dataclass\n",
    "class ADataclass:\n",
    "    \n",
    "    a: str\n",
    "    b: MyCustomType\n",
    "\n",
    "# valid inputs...\n",
    "data = ADataclass(\"a string\", b=MyCustomType(4))\n",
    "dataclasses.asdict(data)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8021e92d-e697-4826-8027-31d0f23a77ff",
   "metadata": {},
   "outputs": [],
   "source": [
    "# invalid inputs...\n",
    "ADataclass([\"I'm\", \"a\", \"list\"], b=4.0)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "df896d3f-bcc2-447a-b5b7-07bc7fa73bef",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "InputsError                               Traceback (most recent call last)\n",
    "Cell In[7], line 2\n",
    "      1 # invalid inputs...\n",
    "----> 2 ADataclass([\"I'm\", \"a\", \"list\"], b=4.0)\n",
    "\n",
    "InputsError: The following inputs to '__init__' do not conform with the corresponding type annotation:\n",
    "\n",
    "a\n",
    "\tTakes type <class 'str'> although received '[\"I'm\", 'a', 'list']' of type <class 'list'>.\n",
    "\n",
    "b\n",
    "\tTakes type <class '__main__.MyCustomType'> although received '4.0' of type <class 'float'>.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0ff51e9d-2fda-4de5-a2d0-2a934ef98045",
   "metadata": {},
   "source": [
    "**NB** Henceforth all examples in this tutorial will be defined as functions, although everything works in the same way for methods and dataclasses."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "85710b04-55bb-41c6-a867-57cd39ee1992",
   "metadata": {},
   "source": [
    "### Type unions and optional types (the `|` operator)\n",
    "\n",
    "Valimp supports annotations for type unions and optional types.\n",
    "\n",
    "From python 3.9 the `typing.Union` and `typing.Optional` annotations can be used to define type hints. From python 3.10 the alternative `|` operator can be used."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "ffbcfe86-686a-4bc4-b285-e57a202b8dd7",
   "metadata": {},
   "outputs": [],
   "source": [
    "# for python >=3.9\n",
    "from typing import Union, Optional\n",
    "\n",
    "@parse\n",
    "def pf(\n",
    "    a: Union[int, float],  \n",
    "    b: Union[int, float, None],  # NB can include None directly within Union\n",
    "    c: Union[int, float, None],\n",
    "    d: Optional[int],\n",
    "    e: Optional[int] = None,\n",
    "):\n",
    "    return"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "367d67e1-f0bc-4576-ad24-62417f6ffecb",
   "metadata": {},
   "outputs": [],
   "source": [
    "# for python >=3.10\n",
    "@parse\n",
    "def pf_310(\n",
    "    a: int | float,  \n",
    "    b: int | float | None,  # NB can include None directly within Union\n",
    "    c: int | float | None,\n",
    "    d: int | None,\n",
    "    e: int | None = None,\n",
    "):\n",
    "    return"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b234634f-f4a9-41ca-9b0d-013374affa72",
   "metadata": {},
   "source": [
    "**NOTE** All other examples in this tutorial that provide for type unions or optional typing use the `typing.Union` and `typing.Optional` classes. If using python >=3.10 then the `|` operator could alternatively be used."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "9ce5f4a7-656e-44ff-9854-38cf687be2fd",
   "metadata": {},
   "outputs": [],
   "source": [
    "assert pf(0, 1.1, None, 3, None) is None # valid inputs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "73951ddd-74e5-434f-afda-ddc0c94d3204",
   "metadata": {},
   "outputs": [],
   "source": [
    "pf(\n",
    "    a=None,  # INVALID as None not an option in the Union\n",
    "    b=\"not valid\",  # INVALID as not an int, float or None\n",
    "    c=None,  # valid\n",
    "    d=\"not_valid\",  # INVALID as not an int or None\n",
    "  )"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "96c06576-dad3-4a83-9e73-9fdbb6677851",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "InputsError                               Traceback (most recent call last)\n",
    "Cell In[11], line 1\n",
    "----> 1 pf(\n",
    "\n",
    "InputsError: The following inputs to 'pf' do not conform with the corresponding type annotation:\n",
    "\n",
    "a\n",
    "\tTakes input that conforms with <(<class 'int'>, <class 'float'>)> although received 'None' of type <class 'NoneType'>.\n",
    "\n",
    "b\n",
    "\tTakes input that conforms with <(<class 'int'>, <class 'float'>, <class 'NoneType'>)> although received 'not valid' of type <class 'str'>.\n",
    "\n",
    "d\n",
    "\tTakes input that conforms with <(<class 'int'>, <class 'NoneType'>)> although received 'not_valid' of type <class 'str'>.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d35242d2-8698-4f4e-a0c6-8a5c85f81541",
   "metadata": {},
   "source": [
    "### Validation of container items\n",
    "\n",
    "By default Valimp will validate that the items of a container conform with any type subscriptions. For example an input to a parameter annotated as `param: list[int]` will be validated as a list and all items containined in that list will be validated as being of type `int`.\n",
    "\n",
    "The [valimp.NO_ITEM_VALIDATION](#valimp.NO_ITEM_VALIDATION) section shows how to **not** validate the type of contained items.\n",
    "\n",
    "#### `list` and `collections.abc.Sequence`\n",
    "`list` and `collections.abc.Sequence` can both be subscripted with a single argument defining the annotation that all contained items should conform to."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "ccc170e7-22fb-4d40-bc04-653848249f69",
   "metadata": {},
   "outputs": [],
   "source": [
    "from collections.abc import Sequence\n",
    "\n",
    "@parse\n",
    "def pf(\n",
    "    a: list[int],\n",
    "    b: Sequence[str],\n",
    "    c: list[Union[int, float]],\n",
    "    d: list[Union[int, float]],\n",
    "    e: Sequence[Optional[int]],\n",
    "):\n",
    "    return"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "22cd31c0-abdf-4051-8914-bd1c1b66ea02",
   "metadata": {},
   "outputs": [],
   "source": [
    "rtrn = pf(  # all valid inputs\n",
    "    a=[0, 1, 2],\n",
    "    b=[\"b\", \"bb\", \"bbb\"],\n",
    "    c=[2, 2.1, 2.2],\n",
    "    d=[3, 3, 3.3],\n",
    "    e=(4, None, 5, None),\n",
    ")\n",
    "assert rtrn is None"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "92cc41cc-501c-44a1-a2d3-378ffb667637",
   "metadata": {},
   "outputs": [],
   "source": [
    "pf(\n",
    "    a=[0, \"1\", 2],  # INVALID, contains a str\n",
    "    b=[\"b\", 0, \"bbb\"],  # INVALID, contains an int\n",
    "    c=[2, \"2.1\", 2.2],  # INVALID, contains a str\n",
    "    d=[3, None, 3.3],  # INVALID, contains None\n",
    "    e=(4, None, 5.0, None),  # INVALID, contains a float\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ead5a8bd-3387-48b7-bf56-c6ee6462c5b9",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "InputsError                               Traceback (most recent call last)\n",
    "Cell In[14], line 1\n",
    "----> 1 pf(\n",
    "\n",
    "InputsError: The following inputs to 'pf' do not conform with the corresponding type annotation:\n",
    "\n",
    "a\n",
    "\tTakes type <class 'list'> containing items that conform with <list[int]>, although the received container contains item '1' of type <class 'str'>.\n",
    "\n",
    "b\n",
    "\tTakes type <class 'collections.abc.Sequence'> containing items that conform with <collections.abc.Sequence[str]>, although the received container contains item '0' of type <class 'int'>.\n",
    "\n",
    "c\n",
    "\tTakes type <class 'list'> containing items that conform with <list[typing.Union[int, float]]>, although the received container contains item '2.1' of type <class 'str'>.\n",
    "\n",
    "d\n",
    "\tTakes type <class 'list'> containing items that conform with <list[typing.Union[int, float]]>, although the received container contains item 'None' of type <class 'NoneType'>.\n",
    "\n",
    "e\n",
    "\tTakes type <class 'collections.abc.Sequence'> containing items that conform with <collections.abc.Sequence[typing.Optional[int]]>, although the received container contains item '5.0' of type <class 'float'>.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d529b5cb-a8e5-49af-acf4-6058a7d16edb",
   "metadata": {},
   "source": [
    "#### `dict` and `collections.abc.Mapping`\n",
    "\n",
    "Valimp will validate both the keys and values of inputs annotated with `dict` or `collections.abc.Mapping`.\n",
    "\n",
    "NB Annotations for these classes take two subscriptions, the first representing the keys and the second representing the values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "3631a73a-0bd5-4780-b0d8-6d6ceab98ac8",
   "metadata": {},
   "outputs": [],
   "source": [
    "from collections.abc import Mapping\n",
    "\n",
    "@parse\n",
    "def pf(\n",
    "    a: dict[str, int],\n",
    "    b: dict[str, int],\n",
    "    c: dict[str, int],\n",
    "    d: Mapping[str, Union[int, float]],\n",
    "    e: dict[str, Optional[str]],\n",
    "):\n",
    "    return"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "f6849283-06e9-41de-830a-93211c58d165",
   "metadata": {},
   "outputs": [],
   "source": [
    "rtrn = pf(  # valid inputs \n",
    "    a={\"a\": 0, \"aa\": 0},\n",
    "    b={\"b\": 1, \"bb\": 1},\n",
    "    c={\"c\": 2, \"cc\": 2},\n",
    "    d={\"d\": 3, \"dd\": 3.3},\n",
    "    e={\"e\": \"four\", \"ee\": None},\n",
    ")\n",
    "assert rtrn is None"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1df868c1-91f3-455c-a15e-6e0c46e427f8",
   "metadata": {},
   "outputs": [],
   "source": [
    "pf(\n",
    "    a={0: 0, \"aa\": 1},  # INVALID, has a key as an int\n",
    "    b={\"b\": 1, \"bb\": \"one\"},  # INVALID, has a value as a str\n",
    "    c={2: \"two\", \"cc\": 2},  # INVALID, has a key as int and value as str\n",
    "    d={\"d\": 3, \"dd\": None},  # INVALID, has a value as None\n",
    "    e={\"e\": 4, \"ee\": None},  # INVALID, has a value as an int\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aca98d58-533c-464d-b2ee-b72c56951243",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "InputsError                               Traceback (most recent call last)\n",
    "Cell In[17], line 1\n",
    "----> 1 pf(\n",
    "\n",
    "InputsError: The following inputs to 'pf' do not conform with the corresponding type annotation:\n",
    "\n",
    "a\n",
    "\tTakes type <class 'dict'> with keys that conform to the first argument of <dict[str, int]>, although the received dictionary contains key '0' of type <class 'int'>.\n",
    "\n",
    "b\n",
    "\tTakes type <class 'dict'> with values that conform to the second argument of <dict[str, int]>, although the received dictionary contains value 'one' of type <class 'str'>.\n",
    "\n",
    "c\n",
    "\tTakes type <class 'dict'> with keys that conform to the first argument and values that conform to the second argument of <dict[str, int]>, although the received dictionary contains an item with key '2' of type <class 'int'> and value 'two' of type <class 'str'>.\n",
    "\n",
    "d\n",
    "\tTakes type <class 'collections.abc.Mapping'> with values that conform to the second argument of <collections.abc.Mapping[str, typing.Union[int, float]]>, although the received mapping contains value 'None' of type <class 'NoneType'>.\n",
    "\n",
    "e\n",
    "\tTakes type <class 'dict'> with values that conform to the second argument of <dict[str, typing.Optional[str]]>, although the received dictionary contains value '4' of type <class 'int'>.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9e630082-a619-45b1-b8e5-8011399e8bc7",
   "metadata": {},
   "source": [
    "#### `tuple`\n",
    "\n",
    "Python provides two ways to annotate a tuple, both of which are supported by Valimp.\n",
    "* To declare that a tuple **behaves like a generic sequence**, of arbitrary length with all items conforming to the same annotation, the tuple annotation takes two arguments. The first argument defines the annotation to which all items should conform. The second takes `Ellipsis`. For example, `tuple[Union[int, float], ...]` declares that an input takes an arbitrary length tuple containing objects of either `int` or `float`.\n",
    "* To declare a tuple of **specific length** the annotation takes the same number of arguments as the tuple's length. Each argument takes the annotation that the item at the corresponding position should conform to. For example, `tuple[int, str, Optional[str]]` declares a 3-tuple which must contain an `int` at index 0, a `str` at index 1, and either a `str` or `None` at index 2.\n",
    "    * For annotations defined in this form Valimp will additionally validate that inputs are of the declared length."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "efc80de9-e69c-4518-a394-c50e84d9ac23",
   "metadata": {},
   "outputs": [],
   "source": [
    "@parse\n",
    "def pf(\n",
    "    a: tuple[int, ...],\n",
    "    b: tuple[Union[int, float], ...],\n",
    "    c: Union[tuple[int, ...], tuple[float, ...]],  # not the same as b!\n",
    "    d: Union[tuple[int, ...], tuple[float, ...]],  # not the same as b!\n",
    "    e: tuple[str, int, Optional[str]],\n",
    "    f: tuple[str, int, Optional[str]],\n",
    "    g: tuple[str, int, float, int],\n",
    "    h: tuple[str, int, float, int],\n",
    "):\n",
    "    return"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "b79ccb44-173c-46ca-ad3b-dc81322637c0",
   "metadata": {},
   "outputs": [],
   "source": [
    "rtrn = pf(  # valid inputs\n",
    "    a=(0, 0, 0),\n",
    "    b=(1.1, 2, 2.2, 3),\n",
    "    c=(2, 3, 4),\n",
    "    d=(3.3, 4.4, 5.5),\n",
    "    e=(\"four\", 4, None),\n",
    "    f=(\"five\", 5, \"opt_five\"),\n",
    "    g=(\"six\", 6, 6.0, 6),\n",
    "    h=(\"seven\", 7, 7.0, 7),\n",
    ")\n",
    "assert rtrn is None"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5b83bc7e-4301-468a-8b98-182a177a0322",
   "metadata": {},
   "outputs": [],
   "source": [
    "pf(\n",
    "    a=(0, \"zero\", 0),  # INVALID as includes str\n",
    "    b=(1.1, \"one\", 2.2, 3),  # INVALID as includes str\n",
    "    c=(2, 3.3, 4),  # INVALID as includes float and int (should be all float or all int)\n",
    "    d=(3.3, 4.4, 5.5),  # valid\n",
    "    e=(4, 4, None),  # INVALID as item at index 0 is not str\n",
    "    f=(\"five\", 5, 3),  # INVALID as item at index 2 is not str or None\n",
    "    g=(\"six\", 6, 6.0),  # INVALID as too short, should have length 4\n",
    "    h=(\"seven\", 7, 7.0, 7, 7.0),  # INVALID as too long, should have length 4\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "62a58459-8875-444c-9f50-13855b929431",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "InputsError                               Traceback (most recent call last)\n",
    "Cell In[20], line 1\n",
    "----> 1 pf(\n",
    "\n",
    "InputsError: The following inputs to 'pf' do not conform with the corresponding type annotation:\n",
    "\n",
    "a\n",
    "\tTakes type <class 'tuple'> containing items that conform with <tuple[int, ...]>, although the received container contains item 'zero' of type <class 'str'>.\n",
    "\n",
    "b\n",
    "\tTakes type <class 'tuple'> containing items that conform with <tuple[typing.Union[int, float], ...]>, although the received container contains item 'one' of type <class 'str'>.\n",
    "\n",
    "c\n",
    "\tTakes input that conforms with <(tuple[int, ...], tuple[float, ...])> although received '(2, 3.3, 4)' of type <class 'tuple'>.\n",
    "\n",
    "e\n",
    "\tTakes type <class 'tuple'> containing items that conform with <tuple[str, int, typing.Optional[str]]>, although the item in position 0 is '4' of type <class 'int'>.\n",
    "\n",
    "f\n",
    "\tTakes type <class 'tuple'> containing items that conform with <tuple[str, int, typing.Optional[str]]>, although the item in position 2 is '3' of type <class 'int'>.\n",
    "\n",
    "g\n",
    "\tTakes type <class 'tuple'> of length 4 although received '('six', 6, 6.0)' of length 3.\n",
    "\n",
    "h\n",
    "\tTakes type <class 'tuple'> of length 4 although received '('seven', 7, 7.0, 7, 7.0)' of length 5.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8da72f79-2af3-4911-9eec-cafa8e3f60df",
   "metadata": {},
   "source": [
    "#### `set`\n",
    "\n",
    "`set` can be subscripted with a single argument that defines the annotation that all contained items should confirm to."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "id": "6433ad69-214b-489c-8dd3-b02c8cf4156f",
   "metadata": {},
   "outputs": [],
   "source": [
    "@parse\n",
    "def pf(\n",
    "    a: set[str],\n",
    "    b: set[Union[int, float]],\n",
    "    c: Union[set[int], set[float]],  # not the same as b!\n",
    "    d: Union[set[int], set[float]],  # not the same as b!\n",
    "):\n",
    "    return\n",
    "\n",
    "rtrn = pf(  # valid inputs\n",
    "    a={\"a\", \"aa\", \"aaa\"},\n",
    "    b={1, 1.1, 1.11},\n",
    "    c={2, 3, 4},\n",
    "    d={3.3, 4.4, 5.5},\n",
    ")\n",
    "assert rtrn is None"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cb3b125c-57de-411a-ba77-99d15d5593d9",
   "metadata": {},
   "outputs": [],
   "source": [
    "pf(\n",
    "    a={\"a\", 2, \"aaa\"},  # INVALID as contains an int\n",
    "    b={1, 1.1, 1.11},  # valid\n",
    "    c={2, 3.3, 4},  # INVALID as contains a float (should be all int or all float)\n",
    "    d={3.3, 4.4, 5.5},  # valid\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e305399e-4d73-4ecc-a4e5-2c536db0eb2b",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "InputsError                               Traceback (most recent call last)\n",
    "Cell In[22], line 1\n",
    "----> 1 pf(\n",
    "\n",
    "InputsError: The following inputs to 'pf' do not conform with the corresponding type annotation:\n",
    "\n",
    "a\n",
    "\tTakes type <class 'set'> containing items that conform with <set[str]>, although the received container contains item '2' of type <class 'int'>.\n",
    "\n",
    "c\n",
    "\tTakes input that conforms with <(set[int], set[float])> although received '{2, 3.3, 4}' of type <class 'set'>.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "04095eb6-dcfc-4c0c-a11b-6a7fb7e75142",
   "metadata": {},
   "source": [
    "#### `valimp.NO_ITEM_VALIDATION`\n",
    "\n",
    "To **not** validate a container's items just include the `valimp.NO_ITEM_VALIDATION` constant in an annotation's metadata.\n",
    "\n",
    "Annotation metadata is defined by simply wrapping the annotation in `typing.Annotated`. The first argument of the `typing.Annotated` subscription takes the wrapped annotation, all further arguments are consumed as annotation metadata.\n",
    "\n",
    "Notice how in the following example the parameters with `valimp.NO_ITEM_VALIDATION` are not included in the error message - they are considered valid as the container type is correct and the contained items are not validated."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "id": "b38c3307-6fbe-4fb8-ba75-16a1955cc2a8",
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import Annotated\n",
    "from valimp import NO_ITEM_VALIDATION\n",
    "\n",
    "@parse\n",
    "def pf(\n",
    "    a: tuple[str, ...],\n",
    "    a1: Annotated[tuple[str, ...], NO_ITEM_VALIDATION],\n",
    "    b: dict[str, int],\n",
    "    b1: Annotated[dict[str, int], NO_ITEM_VALIDATION],\n",
    "    c: set[int],\n",
    "    c1: Annotated[set[int], NO_ITEM_VALIDATION],\n",
    "):\n",
    "    return"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4bd89977-3f22-4208-9d70-22415f8d2bd3",
   "metadata": {},
   "outputs": [],
   "source": [
    "pf(\n",
    "    a=(\"a\", 0),  # INVALID as contains int\n",
    "    a1=(\"a\", 0),  # ...INVALID for same reason but will not raise error\n",
    "    b={\"bkey\": \"bval\"},  # INVALID as has value as str\n",
    "    b1={\"bkey\": \"bval\"},  # ...INVALID for same reason but will not raise error\n",
    "    c={0, 1, 2.2},  # INVALID as contains a float\n",
    "    c1={0, 1, 2.2},  # ...INVALID for same reason but will not raise error\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "80a18cfd-eb49-41f3-b70d-30e5bf4d6178",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "InputsError                               Traceback (most recent call last)\n",
    "Cell In[24], line 1\n",
    "----> 1 pf(\n",
    "\n",
    "InputsError: The following inputs to 'pf' do not conform with the corresponding type annotation:\n",
    "\n",
    "a\n",
    "\tTakes type <class 'tuple'> containing items that conform with <tuple[str, ...]>, although the received container contains item '0' of type <class 'int'>.\n",
    "\n",
    "b\n",
    "\tTakes type <class 'dict'> with values that conform to the second argument of <dict[str, int]>, although the received dictionary contains value 'bval' of type <class 'str'>.\n",
    "\n",
    "c\n",
    "\tTakes type <class 'set'> containing items that conform with <set[int]>, although the received container contains item '2.2' of type <class 'float'>.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b2f6c8e3-26ca-44be-bd65-c8150dcab8a9",
   "metadata": {},
   "source": [
    "#### Nested containers\n",
    "\n",
    "Valimp will by default recursively validate the types of contained items in nested containers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "id": "c5159fb4-bb68-445b-ba45-07509458d305",
   "metadata": {},
   "outputs": [],
   "source": [
    "@parse\n",
    "def pf(\n",
    "    a: tuple[list[set[Union[int, float]]], ...],\n",
    "):\n",
    "    return\n",
    "\n",
    "rtrn = pf(\n",
    "    (\n",
    "        [\n",
    "            {0, 0.1}, {1, 1.1}\n",
    "        ],\n",
    "    ),\n",
    ")\n",
    "assert rtrn is None"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6687cb32-eb6f-4048-aa9d-b7522d9b145d",
   "metadata": {},
   "source": [
    "If the first nested container (the list) contains an invalid item then an error is raised (although the error message could be more insightful)..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0a1a1961-56a0-481a-b49d-d637681a9472",
   "metadata": {},
   "outputs": [],
   "source": [
    "pf(\n",
    "    (\n",
    "        [\n",
    "            {0, 0.1}, {1, 1.1},\n",
    "            \"not a set\",\n",
    "        ],\n",
    "    ),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d988bdb6-653e-4810-a73f-126a30ccfb43",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "InputsError                               Traceback (most recent call last)\n",
    "Cell In[26], line 1\n",
    "----> 1 pf(\n",
    "\n",
    "InputsError: The following inputs to 'pf' do not conform with the corresponding type annotation:\n",
    "\n",
    "a\n",
    "\tTakes type <class 'tuple'> containing items that conform with <tuple[list[set[typing.Union[int, float]]], ...]>, although the received container contains item '[{0, 0.1}, {1, 1.1}, 'not a set']' of type <class 'list'>.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "98bf95e1-7f71-4987-b6d1-bb514ba79f7d",
   "metadata": {},
   "source": [
    "An error is also raised if the list contents are valid although one of the second level of nested containers (the sets) contains an invalid item..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5170a9b6-2791-4586-a142-e61d5f484e1d",
   "metadata": {},
   "outputs": [],
   "source": [
    "pf(\n",
    "    (\n",
    "        [\n",
    "            {0, 0.1}, {1, 1.1, \"one\"},\n",
    "        ],\n",
    "    ),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "27868c1f-ea54-4180-9cc8-57038df44264",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "InputsError                               Traceback (most recent call last)\n",
    "Cell In[27], line 1\n",
    "----> 1 pf(\n",
    "\n",
    "InputsError: The following inputs to 'pf' do not conform with the corresponding type annotation:\n",
    "\n",
    "a\n",
    "\tTakes type <class 'tuple'> containing items that conform with <tuple[list[set[typing.Union[int, float]]], ...]>, although the received container contains item '[{0, 0.1}, {1, 'one', 1.1}]' of type <class 'list'>.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "280d5776-ec00-4d8a-944a-7ab6e2957555",
   "metadata": {},
   "source": [
    "Including `valimp.NO_ITEM_VALIDATION` to an annotation's metadata will result in the contained items not being validated at any level of nesting."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "id": "ed78b4bd-4196-4268-b19f-5afd02b89826",
   "metadata": {},
   "outputs": [],
   "source": [
    "@parse\n",
    "def pf(\n",
    "    a: Annotated[tuple[list[set[Union[int, float]]], ...], NO_ITEM_VALIDATION],\n",
    ") -> tuple[list[set[Union[int, float]]], ...]:\n",
    "    return a"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "id": "6edc0fb2-75b7-4d7d-b7c2-12ff6cada321",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "([{0, 0.1}, {1, 1.1, 'one'}, 'not a set'], 'not a list')"
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pf(\n",
    "    (\n",
    "        [\n",
    "            {0, 0.1}, {1, 1.1, \"one\"},\n",
    "            \"not a set\",\n",
    "        ],\n",
    "        \"not a list\",\n",
    "    ),\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cb1265f0-3a50-4c4d-b474-e858bad53bd8",
   "metadata": {},
   "source": [
    "Indeed, with `valimp.NO_ITEM_VALIDATION` as long as the input's a tuple, it'll validate..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "id": "f09f1647-4059-4e31-8513-3d1aa81892f2",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(\"I'm a tuple\", 1, 2.0)"
      ]
     },
     "execution_count": 30,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pf((\"I'm a tuple\", 1, 2.0))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "af40fc35-dce8-40aa-8fd5-39e9d75bcbfc",
   "metadata": {},
   "source": [
    "NB It isn't currently possible to ignore validation only from a specific level of nesting - PRs welcome!"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fcd08875-402c-4e74-8890-c343b6cd5e0f",
   "metadata": {},
   "source": [
    "### `collections.abc.Callable`\n",
    "\n",
    "Valimp validates that inputs to parameters annotated with `collections.abc.Callable` are indeed callable. However, it will **not** validate any subscriptions.\n",
    "\n",
    "Notice how the inputs in the following example do not conform with the subscriptions although the input is validated regardless. (The first argument to `collections.abc.Callable` takes a sequence of annotations describing the callable's arguments, the second argument takes the callable's return type.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "id": "44232c3f-b399-492b-a66c-1ab4ce983cc2",
   "metadata": {},
   "outputs": [],
   "source": [
    "from collections.abc import Callable\n",
    "\n",
    "@parse\n",
    "def pf(\n",
    "    a: Callable,\n",
    "    b: Callable[[str], str],\n",
    "    c: Callable[[str, int], str],\n",
    "    d: Callable[..., str],\n",
    "):\n",
    "    return\n",
    "\n",
    "def some_func(a: float, b: float) -> float:\n",
    "    return a + b\n",
    "\n",
    "# inputs are validated even though they do not conform with the subscriptions\n",
    "pf(some_func, some_func, some_func, some_func)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f306c6fd-4007-46c9-82c9-19d59e7b053f",
   "metadata": {},
   "source": [
    "Although an error will be raised if the input is not callable..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1b93e18e-7121-4fce-a958-d2048f7c280c",
   "metadata": {},
   "outputs": [],
   "source": [
    "pf(3, \"can't call me\", some_func, some_func)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "81377cab-1d9c-47ce-accb-6e56b4db09ca",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "InputsError                               Traceback (most recent call last)\n",
    "Cell In[32], line 1\n",
    "----> 1 pf(3, \"can't call me\", some_func, some_func)\n",
    "\n",
    "InputsError: The following inputs to 'pf' do not conform with the corresponding type annotation:\n",
    "\n",
    "a\n",
    "\tTakes type <class 'collections.abc.Callable'> although received '3' of type <class 'int'>.\n",
    "\n",
    "b\n",
    "\tTakes type <class 'collections.abc.Callable'> although received 'can't call me' of type <class 'str'>.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6af1bf68-31d9-496a-9233-7e51a1622199",
   "metadata": {},
   "source": [
    "### `typing.Literal`\n",
    "\n",
    "By default inputs to parameters annotated with `typing.Literal` are considered valid if the input *compares as equal* to a value defined within the subscriptions.\n",
    "\n",
    "The `typing.Literal` annotation can be useful to validate that an input is within a set of members of an `Enum`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "id": "f9041474-ec0a-4488-8e80-ddcbbcbe6069",
   "metadata": {},
   "outputs": [],
   "source": [
    "from enum import Enum\n",
    "from typing import Literal\n",
    "\n",
    "Monty = Enum('Monty', 'FOO SPAM BAR')\n",
    "\n",
    "@parse\n",
    "def pf(\n",
    "    a: Literal[\"one\", \"two\"],\n",
    "    b: Literal[1, 2, 3],\n",
    "    c: Literal[Monty.FOO, Monty.SPAM, Monty.BAR],\n",
    "    d: Literal[Monty.FOO, Monty.SPAM, Monty.BAR],\n",
    "    e: Literal[Monty.FOO, Monty.SPAM],\n",
    "):\n",
    "    return\n",
    "\n",
    "rtrn = pf(  # valid inputs\n",
    "    \"one\",\n",
    "    2.0,  # NB not included in annotation, but valid as compares equal to 2\n",
    "    Monty.BAR,\n",
    "    Monty.SPAM,\n",
    "    Monty.FOO,\n",
    ")\n",
    "assert rtrn is None"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ea40fe5e-09db-46ff-8007-818be0262c18",
   "metadata": {},
   "outputs": [],
   "source": [
    "pf(\n",
    "    a=1,  # INVALID as does not compare equal with \"one\" or \"two\"\n",
    "    b=1,  # valid\n",
    "    c=\"BAR\",  # INVALID as does not compare equal with unique enum\n",
    "    d=3,  # INVALID as does not compare equal with unique enum\n",
    "    e=Monty.BAR  # INVALID as member not included to annotation\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "41054103-17c1-4586-ae50-3d7fe9065594",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "InputsError                               Traceback (most recent call last)\n",
    "Cell In[34], line 1\n",
    "----> 1 pf(\n",
    "\n",
    "InputsError: The following inputs to 'pf' do not conform with the corresponding type annotation:\n",
    "\n",
    "a\n",
    "\tTakes a value from <('one', 'two')> although received '1'.\n",
    "\n",
    "c\n",
    "\tTakes a value from <(<Monty.FOO: 1>, <Monty.SPAM: 2>, <Monty.BAR: 3>)> although received 'BAR'.\n",
    "\n",
    "d\n",
    "\tTakes a value from <(<Monty.FOO: 1>, <Monty.SPAM: 2>, <Monty.BAR: 3>)> although received '3'.\n",
    "\n",
    "e\n",
    "\tTakes a value from <(<Monty.FOO: 1>, <Monty.SPAM: 2>)> although received 'Monty.BAR'.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "69ed4275-f766-4160-8d81-32e74c1855c7",
   "metadata": {},
   "source": [
    "The `valimp.STRICT_LITERAL` constant can be included to the annotation metadata to only validate input if it *is* the same object as one of the objects defined within the subscriptions, i.e. it's not enough for the object to merely compare as equal, rather they have to be one and the same. (NB consider using an Enum before resorting to `valimp.STRICT_LITERAL`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "id": "c6162215-5749-4be5-a8d2-683ac53748f0",
   "metadata": {},
   "outputs": [],
   "source": [
    "from valimp import STRICT_LITERAL\n",
    "\n",
    "LIT = \"spam\"\n",
    "\n",
    "@parse\n",
    "def pf(\n",
    "    a: Literal[LIT],\n",
    "    b: Annotated[Literal[LIT], STRICT_LITERAL],\n",
    "):\n",
    "    return\n",
    "\n",
    "pf(LIT, LIT)  # valid as both parameters are receiving the same object"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c5ed91ab-ecf2-4b3b-a1ca-8737660199f2",
   "metadata": {},
   "source": [
    "If we define a different object which compares equal to LIT..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "id": "12a4aca1-005f-469c-b895-e8473ac50e86",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'spam'"
      ]
     },
     "execution_count": 36,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "diff_obj = \"spamx\"[:-1]\n",
    "assert diff_obj == LIT\n",
    "diff_obj"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2ddee1b9-70a1-4433-8005-de72b7a252f6",
   "metadata": {},
   "source": [
    "Then whilst this is valid..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "id": "bb10d385-cf0e-412f-ae74-2a98aa6aea95",
   "metadata": {},
   "outputs": [],
   "source": [
    "pf(diff_obj, LIT)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a026d139-2c50-492e-8e60-6a44dd9e224f",
   "metadata": {},
   "source": [
    "This isn't (at least not for parameter b)..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "635dc9e4-429c-4083-b2ea-dc2928b1bd43",
   "metadata": {},
   "outputs": [],
   "source": [
    "pf(diff_obj, diff_obj)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9b5785a8-4294-4919-9f15-cc51049dc283",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "InputsError                               Traceback (most recent call last)\n",
    "Cell In[38], line 1\n",
    "----> 1 pf(diff_obj, diff_obj)\n",
    "\n",
    "InputsError: The following inputs to 'pf' do not conform with the corresponding type annotation:\n",
    "\n",
    "b\n",
    "\tTakes a literal from <('spam',)> although received 'spam'.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "73da11d1-f9af-43b2-9e82-850b4ee77965",
   "metadata": {},
   "source": [
    "### *args and **kwargs\n",
    "\n",
    "Valimp supports packing arguments to collect excess received positional and keyword arguments."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "id": "50470b59-5421-4036-8c93-d80624bac11d",
   "metadata": {},
   "outputs": [],
   "source": [
    "@parse\n",
    "def pf(\n",
    "    a: int,\n",
    "    *args,\n",
    "    kw_a: bool,\n",
    "    **kwargs\n",
    "):\n",
    "    return a, args, kw_a, kwargs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "id": "a56eb1f1-14d7-41d7-8b40-23c54f73b88a",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(3, (4, 5.0, 'six'), False, {'kw_extra0': 'extra0', 'kw_extra1': [1, 1]})"
      ]
     },
     "execution_count": 40,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pf(3, 4, 5.0, \"six\", kw_a=False, kw_extra0=\"extra0\", kw_extra1=[1, 1])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d95486f8-2f58-4682-9b8a-41f8f2d96cc5",
   "metadata": {},
   "source": [
    "Both *args and **kwargs can be validated against a type annotation. **NB** the type annotation should describe each item contained within the container, not the container object itself."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "id": "e9dead85-ba39-425f-9858-9565230e2a1b",
   "metadata": {},
   "outputs": [],
   "source": [
    "@parse\n",
    "def pf(\n",
    "    a: int,\n",
    "    *args: Union[int, float],\n",
    "    kw_a: bool,\n",
    "    **kwargs: bool,\n",
    "):\n",
    "    return a, args, kw_a, kwargs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "id": "6880feb1-5e76-430a-9bee-24ad32ff85bb",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(3, (4, 5.0), False, {'kw_b': True, 'kw_c': False})"
      ]
     },
     "execution_count": 42,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# valid inputs\n",
    "pf(3, 4, 5.0, kw_a=False, kw_b=True, kw_c=False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1f620337-a8d6-439c-bf23-3e1ccdb72208",
   "metadata": {},
   "outputs": [],
   "source": [
    "# invalid inputs\n",
    "pf(3, 4, 5.0, \"six\", kw_a=False, kw_extra0=True, kw_extra1=2)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ce1d479b-6e89-423b-84ea-29cd5663c9f3",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "InputsError                               Traceback (most recent call last)\n",
    "Cell In[43], line 2\n",
    "      1 # invalid inputs\n",
    "----> 2 pf(3, 4, 5.0, \"six\", kw_a=False, kw_extra0=True, kw_extra1=2)\n",
    "\n",
    "InputsError: The following inputs to 'pf' do not conform with the corresponding type annotation:\n",
    "\n",
    "_args2\n",
    "\tTakes input that conforms with <(<class 'int'>, <class 'float'>)> although received 'six' of type <class 'str'>.\n",
    "\n",
    "kw_extra1\n",
    "\tTakes type <class 'bool'> although received '2' of type <class 'int'>.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fdc8fdd5-d8d4-4cc4-bbad-02fb9b1ee62f",
   "metadata": {},
   "source": [
    "NB that in error message any invalid excess position arguments are named as the packing argument prefixed with a '_' and suffixed with the 0-indexed position of the argument within the container ('_args2' above).\n",
    "\n",
    "The packing arguments can be named unconventionally..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "id": "1eca3fca-eef8-425d-998d-d0deef4fc3ff",
   "metadata": {},
   "outputs": [],
   "source": [
    "@parse\n",
    "def pf(\n",
    "    a: int,\n",
    "    *excess_pos_args: Union[int, float],\n",
    "    kw_a: bool,\n",
    "    **excess_other: bool,\n",
    "):\n",
    "    return a, args, kw_a, kwargs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8a5f7da2-83ee-4a0c-a6b0-b030a7e84ce1",
   "metadata": {},
   "outputs": [],
   "source": [
    "# invalid inputs\n",
    "pf(3, 4, 5.0, \"six\", kw_a=False, kw_extra0=True, kw_extra1=2)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "416367d0-1d58-4b68-938f-4d356a89bac4",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "InputsError                               Traceback (most recent call last)\n",
    "Cell In[45], line 2\n",
    "      1 # invalid inputs\n",
    "----> 2 pf(3, 4, 5.0, \"six\", kw_a=False, kw_extra0=True, kw_extra1=2)\n",
    "\n",
    "InputsError: The following inputs to 'pf' do not conform with the corresponding type annotation:\n",
    "\n",
    "_excess_pos_args2\n",
    "\tTakes input that conforms with <(<class 'int'>, <class 'float'>)> although received 'six' of type <class 'str'>.\n",
    "\n",
    "kw_extra1\n",
    "\tTakes type <class 'bool'> although received '2' of type <class 'int'>.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ef3aaca2-0619-4bf4-a05a-4047b941e373",
   "metadata": {},
   "source": [
    "## Signature validation\n",
    "\n",
    "Valimp also validates that inputs conform with a function's signature.\n",
    "\n",
    "A `valimp.InputsError` will be raised if at least one of the following is true.\n",
    "* A required argument is not passed (missing positional argument).\n",
    "* A required keyword-only argument is not passed (missing keyword-only argument).\n",
    "* A keyword argument is passed that is not represented in the signature (unexpected keyword argument).\n",
    "* More arguments are passed positionally than accommodated for by the signature (excess positional arguments).\n",
    "* A parameter is passed both positionally and as a keyword argument (got multiple values).\n",
    "\n",
    "All signature errors are advised in the error message, together with any errors relating to invalid types."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 46,
   "id": "eff9ce77-2c87-40ca-81c9-4faa54be0997",
   "metadata": {},
   "outputs": [],
   "source": [
    "@parse\n",
    "def pf(\n",
    "    a: int,\n",
    "    b: int,\n",
    "    *,\n",
    "    kw_a: int,\n",
    "):\n",
    "    return"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3e399401-0155-458e-8175-5b2d5d64d2d6",
   "metadata": {},
   "outputs": [],
   "source": [
    "pf(3, \"not an int\", 5, a=3, not_a_kwarg=3)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ba656763-bd27-42fb-a07e-6494402fc5b5",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "InputsError                               Traceback (most recent call last)\n",
    "Cell In[47], line 1\n",
    "----> 1 pf(3, \"not an int\", 5, a=3, not_a_kwarg=3)\n",
    "\n",
    "InputsError: Inputs to 'pf' do not conform with the function signature:\n",
    "\n",
    "Got multiple values for argument: 'a'.\n",
    "\n",
    "Received 1 excess positional argument as:\n",
    "\t'5' of type <class 'int'>.\n",
    "\n",
    "Got unexpected keyword argument: 'not_a_kwarg'.\n",
    "\n",
    "Missing 1 keyword-only argument: 'kw_a'.\n",
    "\n",
    "The following inputs to 'pf' do not conform with the corresponding type annotation:\n",
    "\n",
    "b\n",
    "\tTakes type <class 'int'> although received 'not an int' of type <class 'str'>.\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "197b5f0d-1147-4f99-9b5c-a2af2ff75145",
   "metadata": {},
   "outputs": [],
   "source": [
    "pf(3, kw_a=3)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9dfb0c35-890d-4526-8f79-8ec6e070b6dc",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "InputsError                               Traceback (most recent call last)\n",
    "Cell In[48], line 1\n",
    "----> 1 pf(3, kw_a=3)\n",
    "\n",
    "InputsError: Inputs to 'pf' do not conform with the function signature:\n",
    "\n",
    "Missing 1 positional argument: 'b'.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e6381f38-e647-41d8-9620-e8627dc84b83",
   "metadata": {},
   "source": [
    "## Coerce\n",
    "\n",
    "Valimp provides for coercing a parameter's input to a specific type.\n",
    "\n",
    "This is useful if it's convenient for the user to pass an input as one of various types although you don't want to clutter up your function by then getting the input into the type that you'll be using internally.\n",
    "\n",
    "An input can be coerced simply by including an instance of `valimp.Coerce` to the parameter's annotation metadata. `valimp.Coerce` takes a single argument as the class that the input is to be coerced to (under-the-bonnet the `@parse` decorator simply passes the input to the constructor of the class being coerced to)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 49,
   "id": "aa10cb66-5db5-425a-ba4e-fad8e7e8d3eb",
   "metadata": {},
   "outputs": [],
   "source": [
    "from valimp import Coerce\n",
    "\n",
    "@parse\n",
    "def pf(\n",
    "    a: Annotated[Union[float, int, str], Coerce(float)],\n",
    "    b: Annotated[Union[float, int, str], Coerce(float)],\n",
    "    c: Annotated[Union[float, int, str], Coerce(float)],\n",
    "    d: Annotated[Union[float, int, str], Coerce(float)],\n",
    "    e: Annotated[Union[float, int, str, None], Coerce(float)],\n",
    "    *args: Annotated[Union[float, int, str, None], Coerce(float)],\n",
    ") -> dict[str, Optional[float]]:\n",
    "    return {\"a\":a, \"b\":b, \"c\":c, \"d\":d, \"e\":e, \"args\": args}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 50,
   "id": "8aba30cd-bf06-4b86-b9fd-958bb226d29f",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'a': 0.0,\n",
       " 'b': 1.1,\n",
       " 'c': 2.0,\n",
       " 'd': 3.3,\n",
       " 'e': None,\n",
       " 'args': (1.0, 2.0, 3.3, None)}"
      ]
     },
     "execution_count": 50,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pf(0, 1.1, '2', '3.3', None, 1, 2.0, \"3.3\", None) "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "eda48990-ad81-4cd0-94cf-6ec2d0db6928",
   "metadata": {},
   "source": [
    "Note that Valimp will **not** try to coerce a `None` input.\n",
    "\n",
    "### Type checkers\n",
    "If you're using a type checker it's unlikely that it'll work out that the `@parse` decorator has coerced the input to a specific type. Hence, in the above example the checker will expect that the input could still be a string and will start advising of errors when the received object is treated as a float.\n",
    "\n",
    "In this case to 'right' the type checker it's necessary to narrow the type by including a type guard expression at the start of the function. For example in `mypy`:\n",
    "```python\n",
    "@parse\n",
    "def f(param: typing.Annotated[Union[float, int, str], Coerce(float)):\n",
    "    if typing.TYPE_CHECKING:\n",
    "        assert isinstance(param, float)\n",
    "```\n",
    "\n",
    "PR's very much welcome from anyone who knows how to abstract this requirement away to within Valimp!"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "093dbece-5d81-4760-b248-2c0e68b40417",
   "metadata": {},
   "source": [
    "## Parsing\n",
    "\n",
    "Valimp also provides for abstracting away the parsing and/or custom validation of inputs.\n",
    "\n",
    "This is done by including an instance of `valimp.Parser` to the metadata of a parameter's annotation. The first argument of `Parser` takes a callable which should return the object as to be receieved by the decorated funcion's formal parameter. The callable should have the following signature:\n",
    "\n",
    "```python\n",
    "def parser_func(name: str, obj: Any, params: dict[str, Any]) -> Any:\n",
    "```\n",
    "where:\n",
    "```\n",
    "PARAMETERS\n",
    "\n",
    "name :\n",
    "    Name of the parameter being parsed.\n",
    "\n",
    "obj :\n",
    "    The input as passed by the client.\n",
    "\n",
    "    `obj` will be received as coerced by any `Coerce` instance\n",
    "    only if the Coerce instance is passed to typing.Annotated\n",
    "    ahead of the Parser instance.\n",
    "\n",
    "params :\n",
    "    Shallow copy of earlier inputs that have already been\n",
    "    validated and, if applicable, parsed and/or coerced.\n",
    "\n",
    "RETURNS\n",
    "\n",
    "parsed :\n",
    "    Parsed, validated object.\n",
    "```\n",
    "\n",
    "So, to simply add a suffix to a str input..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 51,
   "id": "872b9027-3aff-4901-859b-f8b1163b5a54",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'a': 'input_a', 'b': 'input_b_suffix'}"
      ]
     },
     "execution_count": 51,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from valimp import Parser\n",
    "\n",
    "def add_suffix(name: str, obj: str, params: dict[str: str]) -> str:\n",
    "    return obj + \"_suffix\"\n",
    "\n",
    "@parse\n",
    "def pf(\n",
    "    a: str,\n",
    "    b: Annotated[str, Parser(add_suffix)],\n",
    ") -> dict[str, str]:\n",
    "    return {\"a\":a, \"b\":b}\n",
    "\n",
    "pf(\"input_a\", \"input_b\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "df93fcff-691b-4cb1-bf74-635faea3a2f5",
   "metadata": {},
   "source": [
    "The following offers a trivial example of how the parameter name and previous inputs are available to the parser."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 52,
   "id": "3639b3c6-eb1f-493c-a62c-47b36e460fcb",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'a': 'input_a',\n",
       " 'b': 'input_b_b',\n",
       " 'c': 'input_c_input_a',\n",
       " 'kw_a': \"I'm a kwarg_kw_a\",\n",
       " 'kwargs': {'kw_xtra': \"I'm kw_xtra_kw_xtra\"}}"
      ]
     },
     "execution_count": 52,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from valimp import Parser\n",
    "\n",
    "def concat_param_name(name: str, obj: str, params: dict[str: str]) -> str:\n",
    "    return obj + f\"_{name}\"\n",
    "\n",
    "my_parser = Parser(concat_param_name)\n",
    "\n",
    "def concat_earlier_input(name: str, obj: str, params: dict[str: str]) -> str:\n",
    "    return obj + f\"_{params['a']}\"\n",
    "\n",
    "@parse\n",
    "def pf(\n",
    "    a: str,\n",
    "    b: Annotated[str, my_parser],  # passes a reusable Parser\n",
    "    c: Annotated[str, Parser(concat_earlier_input)],\n",
    "    *,\n",
    "    kw_a: Annotated[str, my_parser],\n",
    "    **kwargs: Annotated[str, my_parser],\n",
    ") -> dict[str, str]:\n",
    "    return {\"a\":a, \"b\":b, \"c\":c, \"kw_a\":kw_a, \"kwargs\":kwargs}\n",
    "\n",
    "pf(\"input_a\", \"input_b\", \"input_c\", kw_a=\"I'm a kwarg\", kw_xtra=\"I'm kw_xtra\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6ffe459b-91df-408d-a582-2e0ab8ef4862",
   "metadata": {},
   "source": [
    "Note that the input is only passed to the parser if it's type is valid. Accordingly the type of the parser's `obj` parameter can be narrowed in the knowledge that to have got this far the input type will be valided. For example, above the `obj` parameter of the parser callables can be annotated as `str` rather than `Any`.\n",
    "\n",
    "And as invalid inputs can't reach the parser function, you won't get an error with an obtuse message raised, such as when in the above example the parser function would otherwise come across `int` + `str`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6da02fc7-293f-4dcd-97f5-b30c58f26017",
   "metadata": {},
   "outputs": [],
   "source": [
    "pf(\"valid\", \"valid\", 3)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9f7ffb36-678c-412a-9a38-36659bd5671f",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "InputsError                               Traceback (most recent call last)\n",
    "Cell In[53], line 1\n",
    "----> 1 pf(\"valid\", \"valid\", 3)\n",
    "\n",
    "InputsError: The following inputs to 'pf' do not conform with the corresponding type annotation:\n",
    "\n",
    "c\n",
    "\tTakes type <class 'str'> although received '3' of type <class 'int'>.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0d4715be-6d90-4562-8d45-c0eac8b9b000",
   "metadata": {},
   "source": [
    "### Custom validation\n",
    "\n",
    "`Parser` provides for easily abstracting away custom input validations. Just raise an error within the parser function if the input doesn't validate.\n",
    "\n",
    "For example, to ensure that an input is greater that a specific value, or greater than the value passed for a prior parameter..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 54,
   "id": "aa1c9d23-908c-4b07-a5b1-59bc043c6d7c",
   "metadata": {},
   "outputs": [],
   "source": [
    "def simple_validator(name: str, obj: int, params: dict[str, int]) -> int:\n",
    "    if obj < 10:\n",
    "        raise ValueError(\n",
    "           f\"The value of parameter {name} cannot be less than 10.\"\n",
    "        )\n",
    "    return obj\n",
    "\n",
    "def validator(name: str, obj: int, params: dict[str, int]) -> int:\n",
    "    if obj <= params[\"a\"]:\n",
    "        raise ValueError(\n",
    "            f\"The value of parameter '{name}' cannot be less than\"\n",
    "            \" the value of parameter 'a', although received 'a' as\"\n",
    "            f\" {params['a']} and '{name}' as {obj}.\"\n",
    "        )\n",
    "    return obj\n",
    "\n",
    "@parse\n",
    "def pf(\n",
    "    a: Annotated[int, Parser(simple_validator)],\n",
    "    b: Annotated[int, Parser(validator)],\n",
    "):\n",
    "    return\n",
    "\n",
    "assert pf(10, 15) is None"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "559c2c1c-d665-4689-a08f-0fe6c44e04ea",
   "metadata": {},
   "outputs": [],
   "source": [
    "pf(5, 4)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3b50c9a3-7870-43c5-82b6-f41e1817bd10",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "ValueError                                Traceback (most recent call last)\n",
    "Cell In[45], line 1\n",
    "----> 1 pf(5, 4)\n",
    "\n",
    "ValueError: The value of parameter a cannot be less than 10.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d38325df-ac78-4bd8-b098-6b278eb22ab5",
   "metadata": {},
   "source": [
    "Note that in the case of custom validation the user-defined error is raised directly for the first input that fails validation, i.e. although the second input here would also fail the validation no such advices are offered to the user, to whom it probably won't become apparent until they then try..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6fb363a9-7671-4dd9-a315-fb00de28efbb",
   "metadata": {},
   "outputs": [],
   "source": [
    "pf(10, 4)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d289ac44-75f3-4089-a42a-6e88c3587b76",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "ValueError                                Traceback (most recent call last)\n",
    "Cell In[56], line 1\n",
    "----> 1 pf(10, 4)\n",
    "\n",
    "ValueError: The value of parameter 'b' cannot be less than the value of parameter 'a', although received 'a' as 10 and 'b' as 4.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "30e2d8a1-75da-43f2-a556-a49e9967c78a",
   "metadata": {},
   "source": [
    "### Dynamic default values\n",
    "\n",
    "Default values can be defined dynamcially with reference to earlier inputs.\n",
    "\n",
    "For example, to simply set a parameter's default to the value of an earlier required input..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 57,
   "id": "bf0921b4-a961-450e-b719-f7bdea866c66",
   "metadata": {},
   "outputs": [],
   "source": [
    "@parse\n",
    "def pf(\n",
    "    a: int,\n",
    "    b: Annotated[\n",
    "        Optional[int],\n",
    "        Parser(lambda _, obj, params: obj if obj is not None else params[\"a\"]),\n",
    "    ] = None,\n",
    ") -> tuple[int, int]:\n",
    "    return a, b"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 58,
   "id": "2e85bfd6-05c9-48c1-ada4-82f684476311",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(10, 10)"
      ]
     },
     "execution_count": 58,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pf(10)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "ca4c6551-e3cc-4c2b-89ae-23a51b394f75",
   "metadata": {},
   "source": [
    "### parse_none\n",
    "\n",
    "Passing the `None` value to the parser function is what provides for setting a default value. But what if `None` is a valid value in itself which you don't want to send to the parser function? This is what the `Parser` `parse_none` keyword argument is for. It's `True` by default, although if passed as `False` then a `None` input will be passed straight through to the formal parameter rather than to the parser function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 59,
   "id": "5e8d4eba-bcf8-4c11-978a-49dcba926250",
   "metadata": {},
   "outputs": [],
   "source": [
    "@parse\n",
    "def pf(\n",
    "    a: Annotated[\n",
    "        Optional[int],\n",
    "        Parser(lambda _, obj, params: obj + 5, parse_none=False),\n",
    "    ] = None,\n",
    "):\n",
    "    return a"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 60,
   "id": "4c50f083-b166-4a62-bb13-5ceec8ddca81",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "8"
      ]
     },
     "execution_count": 60,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pf(3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 61,
   "id": "05f9433c-64af-48b3-bb70-80cbcec9c03d",
   "metadata": {},
   "outputs": [],
   "source": [
    "assert pf(None) is None"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e2cd63d6-a46c-4b45-bf47-f5bc9b308fd3",
   "metadata": {},
   "source": [
    "Note what would happen if `parse_none` had not been passed to `Parser` as `False`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 62,
   "id": "7f00520f-0c4f-48e1-8f65-fd4cde8c2202",
   "metadata": {},
   "outputs": [],
   "source": [
    "@parse\n",
    "def pf(\n",
    "    a: Annotated[\n",
    "        Optional[int],\n",
    "        Parser(lambda _, obj, params: obj + 5),\n",
    "    ] = None,\n",
    "):\n",
    "    return a"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "61e1bccb-3f99-4eca-ba60-5e2e7616ac89",
   "metadata": {},
   "outputs": [],
   "source": [
    "pf(None)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "89a80d95-2422-4438-afae-b8b3774a59ed",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "TypeError                                 Traceback (most recent call last)\n",
    "Cell In[63], line 1\n",
    "----> 1 pf(None)\n",
    "\n",
    "File ~\\valimp\\src\\valimp\\valimp.py:931, in parse.<locals>.wrapped_f(*args, **kwargs)\n",
    "    929                 if obj is None and not data.parse_none:\n",
    "    930                     continue\n",
    "--> 931                 obj = data.function(name, obj, new_as_kwargs.copy())\n",
    "    933     new_as_kwargs[name] = obj\n",
    "    935 return f(**new_as_kwargs)\n",
    "\n",
    "Cell In[52], line 5, in <lambda>(_, obj, params)\n",
    "      1 @parse\n",
    "      2 def pf(\n",
    "      3     a: Annotated[\n",
    "      4         Optional[int],\n",
    "----> 5         Parser(lambda _, obj, params: obj + 5),\n",
    "      6     ] = None,\n",
    "      7 ):\n",
    "      8     return a\n",
    "\n",
    "TypeError: unsupported operand type(s) for +: 'NoneType' and 'int'\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "766af490-58f5-4708-a49e-f967850a2f1a",
   "metadata": {},
   "source": [
    "## Coerce and parse"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a26a7ab4-212d-4415-bc30-bb69f9d52d5d",
   "metadata": {},
   "source": [
    "Instances of `valimp.Coerce` and `valimp.Parser` can both be passed to the same type annotation.\n",
    "\n",
    "In this case, order matters. If the `Coerce` instance is passed ahead of the `Parser` instance then the parser function will receive the input post-coercion. If however the `Parser` instance is passed ahead of the `Coerce` instance then the parser function will receive the user's input directly and the parser's output will be subsequently coerced.\n",
    "\n",
    "The following offers an example of the more common case of coercing then validating an input."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 64,
   "id": "0171f026-b3d0-434c-bd19-118a829c07a3",
   "metadata": {},
   "outputs": [],
   "source": [
    "def _validate(name: str, obj: float, params: dict[str: Any]) -> float:\n",
    "    if obj < params[\"a\"]:\n",
    "        raise ValueError(\n",
    "            f\"If passed then the value of parameter '{name}' cannot be less\"\n",
    "            f\" than the value of parameter 'a', although received 'a' as\"\n",
    "            f\" {params['a']} and '{name}' as {obj}.\"\n",
    "        )\n",
    "    return obj    \n",
    "\n",
    "validate = Parser(_validate, parse_none=False)\n",
    "\n",
    "@parse\n",
    "def pf(\n",
    "    a: Annotated[Union[float, int, str], Coerce(float)],\n",
    "    b: Annotated[\n",
    "        Union[float, int, str, None],\n",
    "        Coerce(float),\n",
    "        validate,\n",
    "    ] = None,\n",
    ") -> tuple[float, Optional[float]]:\n",
    "    return a, b"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 65,
   "id": "b5fc576a-1c65-467c-bbb2-a67b412d3297",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(2.2, None)"
      ]
     },
     "execution_count": 65,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pf(\"2.2\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 66,
   "id": "e05c6d24-60a5-4ec1-9e1b-b98f9f8ee094",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(2.2, 3.3)"
      ]
     },
     "execution_count": 66,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pf(\"2.2\", \"3.3\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 67,
   "id": "78cc5f4e-ac44-42bb-ada0-106dd023803f",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(2.2, 3.0)"
      ]
     },
     "execution_count": 67,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pf(\"2.2\", 3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d9eb64e3-eb85-4006-8f02-b8a945d9be21",
   "metadata": {},
   "outputs": [],
   "source": [
    "pf(\"2.2\", \"1.8\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f0c695a1-612c-497a-ab61-bf5daf3d16dc",
   "metadata": {},
   "source": [
    "```\n",
    "---------------------------------------------------------------------------\n",
    "ValueError                                Traceback (most recent call last)\n",
    "Cell In[68], line 1\n",
    "----> 1 pf(\"2.2\", \"1.8\")\n",
    "\n",
    "File ~\\valimp\\src\\valimp\\valimp.py:931, in parse.<locals>.wrapped_f(*args, **kwargs)\n",
    "    929                 if obj is None and not data.parse_none:\n",
    "    930                     continue\n",
    "--> 931                 obj = data.function(name, obj, new_as_kwargs.copy())\n",
    "    933     new_as_kwargs[name] = obj\n",
    "    935 return f(**new_as_kwargs)\n",
    "\n",
    "Cell In[64], line 3, in _validate(name, obj, params)\n",
    "      1 def _validate(name: str, obj: float, params: dict[str: Any]) -> float:\n",
    "      2     if obj < params[\"a\"]:\n",
    "----> 3         raise ValueError(\n",
    "      4             f\"If passed then the value of parameter '{name}' cannot be less\"\n",
    "      5             f\" than the value of parameter 'a', although received 'a' as\"\n",
    "      6             f\" {params['a']} and '{name}' as {obj}.\"\n",
    "      7         )\n",
    "      8     return obj\n",
    "\n",
    "ValueError: If passed then the value of parameter 'b' cannot be less than the value of parameter 'a', although received 'a' as 2.2 and 'b' as 1.8.\n",
    "```"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "valimp_39",
   "language": "python",
   "name": "valimp_39"
  },
  "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.9.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}