
When programming, you probably often have, like me, those *Aha!* moments: when things that were not really clear or obvious in your mind suddenly start to make sense. This week, I had one of these... Even if it turned out to also be a *Doh!* moment 😰

This time, it was brought to me by [SQLAlchemy](https://www.sqlalchemy.org/). This Python library is the de-facto standard for working with SQL databases. It's *super* powerful... But also hard to tame.

So let's review a code snippet, typical of what I was doing when working with SQLAlchemy. Let's say we have [SQLAlchemy ORM models](https://docs.sqlalchemy.org/en/20/orm/mapping_styles.html#orm-declarative-mapping) called `User` and `Post` and a ready-to-use [engine](https://docs.sqlalchemy.org/en/20/core/connections.html#sqlalchemy.engine.Engine).

```py
def create_user(session):
	user = User(email="king.arthur@camelot.bt")
	session.add(user)
	session.commit()
	return user

def create_post(session, user):
	post = Post(title="SQLAlchemy: stop calling `session.commit()`", user=user)
	session.add(post)
	session.commit()
	return post

def main():
	with Session(engine) as session:
		user = create_user(session)
		post = create_post(session, user)
```

If that looks okay to you, then read this post in full. Because you're doing it **wrong**.

# `session.commit()` is not your friend

The core of SQLAlchemy usage is the [`Session`](https://docs.sqlalchemy.org/en/20/orm/session_api.html#sqlalchemy.orm.Session) object. Under the hood, besides maintaining ORM objects state, it also manages an **SQL transaction**. It means that you can safely perform queries: if something goes wrong along the way, you can always **rollback** to the previous state, leaving the DB untouched...

... unless you call `session.commit()`.

This method does two things:

1. It flushes all the pending changes to the database (objects creation, update, deletion, etc.).
2. It `COMMIT` the SQL transaction, as its name rightfully suggest: the changes are definitely written to the DB and there is no way back.

Meaning that, if you need to `ROLLBACK`, that's too late. **Even if you are in a nested transaction**. What does it mean if we go back to our example?

Let's say something goes wrong during `create_post`: an API call fails, a bug (😱) occurs, the server shuts down abruptly... The result is that you'll have a user in your database, but not the post; meaning your database is an incoherent state. If you want to retry the task, you'll likely have issues since they are already half of the objects there.

So, what should our example look like to avoid this?

```py
def create_user(session):
	user = User(email="king.arthur@camelot.bt")
	session.add(user)
	return user

def create_post(session, user):
	post = Post(title="SQLAlchemy: stop calling `session.commit()`", user=user)
	session.add(post)
	return post

def main():
	with Session(engine) as session:
		user = create_user(session)
		post = create_post(session, user)
        session.commit()
```

That's the key takeaway of this post. Write it on a post-it. Stick it on your screen:

<p style="text-align:center;font-size: 1.5em;font-weight:bold;color:red">Call session.commit() only once at the end</p>

Said another way, if you have `session.commit()` calls in your business logic, it's a **code smell**.

Generally speaking, `session.commit()` should only appear in "lifecycle" logic, which is managed by your framework or global application scope: a FastAPI dependency, a middleware, a context manager, etc.

# `session.flush()` is probably what you want

At this point, you probably want to ask: *"Ok, but what if I need to execute queries along the way? Or if I want to trigger the database integrity checks or defaults?"* That's indeed a perfectly legitimate concern.

In a complex program, we might create dozens of object in one operation and perform a `SELECT` query, expecting our new data to be available. That's probably why you called `session.commit()` at first.

What you want is actually `session.flush()`. Basically, it's only the first step of the `session.commit()` operation: it sends pending operation to the database, but the transaction is **not** committed. So, it allows us to do this kind of things:

```py
def handle_payment(session, account, amount, fees):
    payment_transaction = Transaction(amount=amount, account=account)
    fees_transaction = Transaction(amount=-fees, account=account)

    session.add(payment_transaction)
    session.add(fees_transaction)

    session.flush()
    # payment_transaction and fees_transaction are flushed to the DB
    #but we're still in the transaction

    account_balance_statement = select(sum(Transaction.amount)).where(
        Transaction.account == account
    )
    account_balance = session.execute(account_balance_statement).scalar()

    account.balance = account_balance
    session.add(account)
```

Here, we are able to update the account balance knowing that the new transactions will be available to the `SELECT SUM...` statement; since we flushed right before. But we'll still have the chance to **rollback** if something goes wrong.

## Autoflush has your back

Actually, in our example above, calling `session.flush()` is not even needed. By default, whenever you `execute` a query, SQLAlchemy will automatically flush pending changes. That's `autoflush`. Most of the time, you probably don't need to worry about it. Don't disable it.

# Conclusion

As I mentioned in introduction, it truly was an *Aha!* moment for me, and now that I re-read this post, it feels so obvious.

And it's also a *Doh!* moment for two reasons:

1. I have to revisit lot of things on the codebases I work on (including Polar).
2. This is actually very well explained in SQLAlchemy documentation, but I missed it: https://docs.sqlalchemy.org/en/20/orm/session_basics.html#when-do-i-construct-a-session-when-do-i-commit-it-and-when-do-i-close-it

Therefore, I hope you'll find this post before it's too late so you can use SQLAlchemy sessions *the right way*. Cheers 😉


SQLAlchemy: stop calling `session.commit()`


If, like me, you're a huge fan of what [Pydantic](https://docs.pydantic.dev/latest/) and [FastAPI](https://fastapi.tiangolo.com/) folks are doing, you can't have missed the new [`Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated) construct, which was introduced in Python 3.9. In a few months, we've seen lot of code examples changed from this:

```python
from uuid import uuid4

from pydantic import BaseModel, Field


class User(BaseModel):
    id: str = Field(default_factory=lambda: uuid4().hex)
```

to this:

```python
from uuid import uuid4

from typing_extensions import Annotated

from pydantic import BaseModel, Field


class User(BaseModel):
    id: Annotated[str, Field(default_factory=lambda: uuid4().hex)]
```

*This is taken directly from [Pydantic documentation](https://docs.pydantic.dev/latest/concepts/fields/#using-annotated).*

At first glance, it doesn't seem really useful or practical. But trust me, `Annotated` can grant *super-powers*. Pydantic and friends quickly understood that and they're already rely on it a lot. By the end of this post, you'll probably understand why 😉

> 👋 If you don't really know about type hints in Python, be sure to [check my previous post](/blog/write-better-python-code-faster-with-type-hints) before!

# Motivation 🥱

So, as you know, type hints gives us direct feedback about the validity of our types while coding. It also helps IDE give us smart auto-completions, which is very handy to list methods and their arguments. So, if we consider again the Pydantic's `User` class:

```py
class User(BaseModel):
    id: str = Field(default_factory=lambda: uuid4().hex)

u = User()
print(u.id)
```

`mypy` and friends know that `u.id` exists *and* that it's a string.

Great! But as you noticed, type annotations are not always enough on their own. It's frequent that we need **runtime information** to finely tune the behavior of the library we're using. Here, we used the `Field` class to tell Pydantic that, by default, we want it to generate an UUID4 for this `id`.

Can you see the problem it causes? We tell the type checker `id` is a string, but we actually assign it to a `Field` object 😱 *We're such scoundrels!*

That's because we use this attribute for two different things actually: tell the type it'll have on an **instance** and tell how we want the **class** to behave for this field. To make the type checker happy, Pydantic sets the `Field` return type to `Any`.

That's actually a very common pattern in Python libraries dealing with data modeling.  For example, this is how [SQLAlchemy ORM](https://docs.sqlalchemy.org/en/20/index.html) solves this problem:

```py
from sqlalchemy.orm import Mapped, mapped_column

class User(Base):
    __tablename__ = "users"

    id: Mapped[str] = mapped_column(String, primary_key=True)
```

They define a special type construct, `Mapped` which expects a generic type and plays well with the `mapped_column` return type. It's more correct semantically, but also a bit more involved for the user. Besides, SQLAlchemy team implemented a complete `mypy` plugin to handle this properly.

Another example of this problem is the dependency injection mechanism of FastAPI:

```py
from fastapi import Depends, FastAPI

app = FastAPI()


async def common_parameters(q: str | None = None, skip: int = 0, limit: int = 100):
    return {"q": q, "skip": skip, "limit": limit}


@app.get("/items/")
async def read_items(commons: dict = Depends(common_parameters)):
    return commons
```

*This is taken directly from [FastAPI documentation](https://fastapi.tiangolo.com/tutorial/dependencies/#__tabbed_1_4).*

The function `common_parameters` is responsible for retrieving pagination parameters in the URL parameters, and return them as a dictionary. To use it in our API endpoint, we use the `Depends` construct of FastAPI, so it knows it'll have to call this function when we receive a request.

Again, you see here the inconsistency between `commons` being a `dict`, while we're assigning it to a `Depends` object.

# `Annotated` to the rescue 🛟

`Annotated` was purposefully implemented to solve those problems: keep consistent and smart type checking *while* being able to add contextual information for the runtime.

Basically, it works like this:

```py
from typing import Annotated, get_type_hints

class User:
    id: Annotated[str, "This is a metadata"]
```

It's a generic type: the first argument should be the **type** you expect for your argument (here, an `int`). Then, you can have **any number of arguments** of whatever nature; here, the string `"This is a metadata"`.

Type checkers, like `mypy`, will only consider the first argument: the type. The rest can be used (or not) by the actual Python program's logic.

How? Well, like any other type annotations, it can be retrieved using the `get_type_hints` function:

```py
type_hints = get_type_hints(func, include_extras=True)
print(type_hints)  # {'id': typing.Annotated[str, 'This is a metadata']}
print(type_hints["id"].__metadata__)  # ('This is a metadata',)
```

Note that we need to set the `include_extras` argument to `True` to get metadata associated with `Annotated`. Then, once we have an `Annotated` object, we can retrieve this metadata as a tuple through the `__metadata__` attribute.

Now, things can go really wild!

# Working example ⚙️

Let's see how we can implement a class to define a data model with default values for attributes, using `Annotated`. The result we want to achieve will look like this:

```py
class User(DefaultModel):
    id: Annotated[str, Default(factory=lambda: uuid4().hex)]
    name: Annotated[str, Default(value="Anonymous")]
```

We'll be able to create data models and declare attributes with their types and default values if they're not provided by the user.

Since `Annotated` metadata can be anything, a clever and convenient way is to define specific classes that'll allow us to attach some data and behavior. Let's first define a `Default` class:

```py
class Default:
    """
    Class defining a behavior for default value,
    either with a static value or a function factory.
    """

    def __init__(
        self, *, value: Any | None = None, factory: Callable[[], Any] | None = None
    ) -> None:
        self.value = value
        self.factory = factory

    def get_default(self) -> Any:
        if self.value is not None:
            return self.value

        if self.factory is not None:
            return self.factory()

        raise RuntimeError()
```

It's a simple class that accepts either a static value or a factory function, allowing us to generate default values dynamically, like UUID or timestamps.

Now, we'll define a base class for our models, `DefaultModel`, that will define the logic to handle those annotations and fill the defaults.

```py
class DefaultModel:
    """
    Class able to parse type annotations using the `Default` class
    and fill the attributes accordingly if not provided.
    """

    def __init__(self, **kwargs) -> None:
        type_hints = get_type_hints(self, include_extras=True)
        # Iterate through each type-hinted attributes
        for attribute, type_hint in type_hints.items():
            try:
                # The value has been provided by the user
                value = kwargs[attribute]
            except KeyError:
                # Otherwise, look for `Annotated` type hint
                if hasattr(type_hint, "__metadata__"):
                    # Look for the `Default` class in metadata
                    for metadata in type_hint.__metadata__:
                        if isinstance(metadata, Default):
                            # Generate the default value
                            value = metadata.get_default()
            finally:
                # Assign the value!
                setattr(self, attribute, value)
```

The logic is quite straightforward: we iterate through each type-hinted attributes and check if the user has provided a value for it in `kwargs`. If not, we'll explore the `Annotated` type hint and look for `Default` classes. It's important to check the nature of the type hint and metadata, because you can't be sure how the user will actually annotate the final class.

Aaaand... That's about it 🙃 We now have reusable logic to assign default values to class attributes. We can check it works:

```py
class User(DefaultModel):
    id: Annotated[str, Default(factory=lambda: uuid4().hex)]
    name: Annotated[str, Default(value="Anonymous")]


u = User(id="1", name="Arthur")
print(u.id)  # 1
print(u.name)  # Arthur

u_default = User()
print(u_default.id)  # 2d10cd0e9a574ecf817ee02e20a0cf45
print(u_default.name)  # Anonymous
```

Neat, isn't it?

Admittedly, unless you're building Python libraries which requires such nice DX, you'll probably rarely have to implement interpretation logic for `Annotated`. But it's more or less how it works under the hood in Pydantic and FastAPI!

# Usage in the wild 🌍

As we said, this pattern has already made its way into major Python libraries.

## In Pydantic

If we take again our Pydantic example, the `Field` construct can now be added as a metadata in `Annotated`:

```py
class User(BaseModel):
    id: Annotated[str, Field(default_factory=lambda: uuid4().hex)]
```

Another advantage of this technique is that we can assign it to a type and reuse it; which was not possible before:

```py
HexUUID = Annotated[str, Field(default_factory=lambda: uuid4().hex)]

class User(BaseModel):
    id: HexUUID

class Post(BaseModel):
    id: HexUUID
```

The type checker still knows it should type it as a string, but from our point-of-view, it's like using a class type!

And it can go even further: Pydantic allows us to [define completely custom types](https://docs.pydantic.dev/latest/concepts/types/#custom-types) with various constraints and behavior:

```py
TruncatedFloat = Annotated[
    float,
    AfterValidator(lambda x: round(x, 1)),
    PlainSerializer(lambda x: f'{x:.1e}', return_type=str),
    WithJsonSchema({'type': 'string'}, mode='serialization'),
]
```

*This is taken directly from [Pydantic documentation](https://docs.pydantic.dev/latest/concepts/types/#adding-validation-and-serialization).*

## In FastAPI

Looking again at the `common_parameters` dependency example, `Annotated` will turn it into this:

```py
@app.get("/items/")
async def read_items(commons: Annotated[dict, Depends(common_parameters)]):
    return commons
```

`Depends` is now used as an `Annotated` metadata. Of course, the strength of this approach is that we can assign this to a type and reuse it. Much shorter than before!

```py
CommonParameters = Annotated[dict, Depends(common_parameters)]

@app.get("/items/")
async def read_items(commons: CommonParameters):
    return commons

@app.get("/orders/")
async def read_orders(commons: CommonParameters):
    return commons
```

## In SQLAlchemy

Did you ever repeated a column definition; like a datetime column or a primary key, with all its constraints and stuff, in SQLAlchemy? I'm sure you did! No more with `Annotated`:

```py
intpk = Annotated[int, mapped_column(primary_key=True)]
timestamp = Annotated[
    datetime.datetime,
    mapped_column(nullable=False, server_default=func.CURRENT_TIMESTAMP()),
]
required_name = Annotated[str, mapped_column(String(30), nullable=False)]
```

```py
class Base(DeclarativeBase):
    pass


class SomeClass(Base):
    __tablename__ = "some_table"

    id: Mapped[intpk]
    name: Mapped[required_name]
    created_at: Mapped[timestamp]
```

*This is taken directly from [SQLAlchemy documentation](https://docs.sqlalchemy.org/en/20/orm/declarative_tables.html#mapping-whole-column-declarations-to-python-types).*

Awesome! We have a short, easy-to-use and type-checking compliant way to declare column definitions and reuse it in dozens of models.

---

That's a wrap! I hope this article helped to demystify `Annotated`, which can be surprising at first glance. This new construct opens a whole new world of possibilities in Python, rooted in the type-annotated era. We're only at the beginning: I bet lot of [new libraries will emerge](https://twitter.com/fvoron/status/1751535653274173715) with those ideas in mind.


typing.Annotated, the new Python cool



If you've followed the Python evolutions for the last few years, you probably know that **type hints** are a thing. Since its introduction in Python 3.5, the [`typing` module](https://docs.python.org/3/library/typing.html) has quickly grow and lot of Python codebases nowadays are using type hints.

If you're not using them already, I can guarantee that you will by the end of this post 😉

# The problem 😩

So, as you know, Python is a **dynamically-typed language**. It means that, contrary to compiled languages like C or Rust, variables types are guessed at runtime instead of being validated during a compilation step. Therefore, you can very well write something like this:

```python
a = 42
assert isinstance(a, int)  # `a` is an integer

a = "Polar is so cool"
assert isinstance(a, str)  # `a` is now a string
```

That's convenient because you don't need to explicitly declare the type of the variable. Thank you Python, you're so nice 🥰 Now, let's take a more concrete example:

```python
def sum(a, b):
	return a + b

sum(42, "I'm a string, lol ( ͡° ͜ʖ ͡°)")
```

We define a simple function that should return the sum of two numbers. Then, we call it with an integer and... a string 🤦‍♂️ From Python's point-of-view, this is perfectly valid code. However, it miserably fails at runtime:

```
TypeError: unsupported operand type(s) for +: 'int' and 'str'
```

Of course, we can't add an integer and a string. Obvious, but we had to run it to spot the mistake. Another one? Imagine we have the following class:

```python
class TripToFarFarAway:
    def __init__(self, distance):
        self.distance = distance
        self.progress = 0

    def are_we_there_yet(self):
        return self.progress < self.distance

    def move_forward(self, distance):
        self.progress += distance
```

Let's use it:

```python
trip = TripToFarFarAway(1_000_000)
if not trip.are_we_there():
	print("NOOOO!")
```

Do you see it? No? Python neither... Until we run it:

```
    if not trip.are_we_there():
           ^^^^^^^^^^^^^^^^^
AttributeError: 'TripToFarFarAway' object has no attribute 'are_we_there'. Did you mean: 'are_we_there_yet'?
```

Damned! We misspelled the method's name!

Those are pretty basics examples, but I'm sure you were already confronted to this kind of mistakes; especially in much bigger codebases with dozens of classes, functions, each one with their massive set of arguments. *"Huh, what's the method's name already?"*, *"Oh right, the fourth argument is a string, not an int...*". We all lost *hours* (and our sanity) in those kind of pointless problems. Couldn't we do better? Actually, **we can**.

# Introducing type hints ✍️

The idea is quite simple: add, directly in the code, information about the type we expect on our variables, arguments, properties, etc... A bit similar to what we would do in a compiled language. That's **type hints** (or **type annotations**) .

If we consider our `sum` function again, it would look like this with annotations:

```python
def sum(a: int, b: int) -> int:
	return a + b
```

It looks quite natural: after each argument, we specify the type we expect after a colon `a: int`. The return type is set using an arrow: `-> int`. Cool! So what happens if we run `sum(42, "I'm a string, lol ( ͡° ͜ʖ ͡°)")` again?

```
TypeError: unsupported operand type(s) for +: 'int' and 'str'
```

Oh... It didn't change anything ☹️ That's perfectly normal: Python **is** and **will remain** a **dynamically-typed** language. It means the Python interpreter will simply **ignore the annotations** and do nothing with it. So, how can we use them?

# Introducing static type checkers 🔬

A static type checker is a program able to **parse and analyze your source code** to tell you if your code is consistent regarding typing. For Python, the reference type checker is [`mypy`](https://github.com/python/mypy). Give it a script as input, and it'll check that your type annotations are respected. Let's see this with our `sum` example:

```bash
$ mypy sum.py
sum.py:4: error: Argument 2 to "sum" has incompatible type "str"; expected "int"  [arg-type]
Found 1 error in 1 file (checked 1 source file)
```

Wow, that's interesting! `mypy` tells us that the second argument is a string, while we expect an integer. It's worth to note that `mypy` doesn't even need to actually run your program: it infers everything from the type hints 🧠

With this tool, we have a way to know quickly if we're making a mistake. Of course, it integrates very well with IDE like Visual Studio Code, so the feedback directly shows up while you're coding!

![Typing error in EDE](/posts/images/write-better-python-code-faster-with-type-hints/typing_error.png)

Talking about IDE, some also ship with their own static type checkers so they can offer smart autocompletions or imports. Visual Studio Code (again), uses Pyright to show you things like this:

![Autocompletion in IDE](/posts/images/write-better-python-code-faster-with-type-hints/autocompletion.png)

See? VS Code automatically suggests methods and properties from the `TripToFarFarAway` class. No more back and forth with the class definition or the library' docs!

Needless to say those tools will help you to:

* Save time
* *Dramatically* reduce errors

# More complex type hints 📈

The example we've seen so far was pretty simple, but in the real world, we use much more than just scalar types like `int` or `str`. What about data structures? Callables? Generators? Don't worry, they are supported to!

Let's see how we can define a **list of integers** and a **dictionary mapping strings to integers**.

```python
l: list[int] = [1, 2, 3, 4, 5]
d: dict[str, int] = {"a": 1, "b": 2, "c": 3}
```

Again, we define the type after a colon. Here we use the builtin types `list` and `dict` to which we add a type variable between square brackets. That's quite close to the concept of [Generics](https://en.wikipedia.org/wiki/Generic_programming). Now, type checkers will now that `l` contains only integers and `d` should only map strings to integers. So the following code:

```python
# Try to append a string to `l`
l.append("I'm a string, lol ( ͡° ͜ʖ ͡°)")
# Try to sum an item of `d` with a string
d["a"] + "I'm a string, lol ( ͡° ͜ʖ ͡°)"
```

...will produce the following errors with `mypy`:

```
type_hints.py:5: error: Argument 1 to "append" of "list" has incompatible type "str"; expected "int"  [arg-type]
type_hints.py:7: error: Unsupported operand types for + ("int" and "str")  [operator]
```

As we said, Python will remain a dynamically-typed language. So we can very well have a list with elements of different types, like a list with both `int` and `float`. This can be expressed like this in annotations:

```py
l: list[int | float] = [42, 3.14, 1337]
```

With the pipe `|`, we specify an **union** of possible types. That one is also very useful for **optional arguments** in functions:

```py
def greeting(name: str | None = None) -> str:
        return f"Hello, {name if name else 'Anonymous'}"
```

Note how the type annotation for `None` is just... `None`!

> **Type annotations were different before Python 3.9**
>
> Before Python 3.9, it wasn’t possible to annotate lists, tuples, sets, and dictionaries using the builtin type. Special construct from `typing` module were needed: `l: typing.List[int] = [1, 2, 3, 4, 5]`.
>
> Likewise, the `|` wasn't available: `typing.Union[int, float]`.
>
> This way of annotating is now deprecated, but you may still find it in backwards-compatible code.

Of course, we can go way further than that, but we'll stop here for this introduction. If you want to go further, `mypy` documentation is a must-read: [https://mypy.readthedocs.io/en/stable/index.html](https://mypy.readthedocs.io/en/stable/index.html)

# Introspection 😌

In programming, introspection is the ability for a program to get information about an object **at runtime**. As you may know, Python is *very* good at this. It even has a [whole module in the standard library](https://docs.python.org/3/library/inspect.html) dedicated to this. A small example:

```py
import inspect

def sum(a, b):
    """Returns the sum of two integers."""
    return a + b

sum_signature = inspect.signature(sum)
print(sum_signature.parameters)
print(inspect.getdoc(sum))
```

The output of this program is the following:

```
OrderedDict({'a': <Parameter "a">, 'b': <Parameter "b">})
Returns the sum of two integers.
```

Impressive! Python is able to give us the signature of the function, and even the attached docstring! Do you guess why I'm talking about this? Because we can **introspect type hints** too 🤯

Let's try again with the type annotated version of `sum`:

```py
def sum(a: int, b: int) -> int:
    """
    Returns the sum of two integers.
    """
    return a + b

sum_signature = inspect.signature(sum)
print(sum_signature.parameters)
```

```
OrderedDict({'a': <Parameter "a: int">, 'b': <Parameter "b: int">})
```

The signature is able to give us an ordered dictionary of all the arguments expected by the function. Each one is a [`Parameter`](https://docs.python.org/3/library/inspect.html#inspect.Parameter) object and **it does retain the type annotation**:

```py
print(sum_signature.parameters["a"].annotation)
```

```
<class 'int'>
```

Boom! `a` should be an `int`. That's a **game changer**: it means that we can actually use this information at runtime to change the behavior of our program.

A quite natural example could be to implement a decorator to checks the validity of a function arguments:

```py
import functools
import inspect

def check_arguments_type(f):
    parameters = inspect.signature(f).parameters
    @functools.wraps(f)
    def wrapper(*args, **kwargs):
        # Check args
        for arg, (parameter_name, parameter) in zip(args, parameters.items()):
            assert isinstance(arg, parameter.annotation), f"{parameter_name} should be {parameter.annotation}"

        # Check kwargs
        for key, value in kwargs.items():
            parameter = parameters[key]
            assert isinstance(value, parameter.annotation), f"{key} should be {parameter.annotation}"

        return f(*args, **kwargs)
    return wrapper

@check_arguments_type
def sum(a: int, b: int) -> int:
    """
    Returns the sum of two integers.
    """
    return a + b

sum(42, "I'm a string, lol ( ͡° ͜ʖ ͡°)")
```

> ⚠️ This is a very naive approach with lot of edge cases — don't use it like this in your projects!

Now, we have a type check at runtime!

```
Traceback (most recent call last):
  File "sum.py", line 29, in <module>
    sum(42, "I'm a string, lol ( ͡° ͜ʖ ͡°)")
  File "sum.py", line 11, in wrapper
    assert isinstance(arg, parameter.annotation), f"{parameter_name} should be {parameter.annotation}"
AssertionError: b should be <class 'int'>
```

This example was focused on functions, but it works with any Python objects accepting type hints. In general, we can use the function [`typing.get_type_hints()`](https://docs.python.org/3/library/typing.html#typing.get_type_hints) to get annotations for any arbitrary object:

```py
class Movie:
    title: str
    duration_minutes: int

print(typing.get_type_hints(Movie))
```

```
{'title': <class 'str'>, 'duration_minutes': <class 'int'>}
```

## How it's used in the real-world?

This technique is really clever and powerful, and it actually made its way into major Python libraries and frameworks. In particular, this is at the heart of [Pydantic](https://docs.pydantic.dev/latest/), the data validation library. With it, you define models using type annotations:

```py
class Delivery(BaseModel):
    timestamp: datetime
    dimensions: tuple[int, int]
```

And it'll use them at runtime to perform complex data validation and conversion!

Another great example is [FastAPI](https://fastapi.tiangolo.com/), which automatically determines the input data expected by an API endpoint using type hints (and Pydantic models 😉):

```py
@app.post("/items/")
async def create_item(item: Item):
    return item
```

In this example, FastAPI will:

* Generate an API schema
* Validate the JSON input so it conforms to the `Item` model
* Give you a ready-to-use instance of `Item`.

The cherry-on-the-cake of those approaches is that it gives us good type checking out of the box!

---

That's all I wanted to share with you about Python type hints! If you didn't know it, I hope it'll give you good reasons to start using them.

In my next post, we'll focus on a recent and *really powerful* typing construct: `Annotated`! See you soon 👋
