Why do the docs often have types using strings and if TYPE_CHECKING?

[ceigey]

Hi all, apologies if this question is veering a bit out of scope.

I noticed some examples in the documentation (I'm using the v2 docs) use an if TYPE_CHECKING: for conditional imports and use string types instead of the actual classes and aliases.

I was wondering what the use case for this was, and why the classes/aliases weren't just used in the annotations directly, and if it was due to something about Litestar that I skipped over in the docs by accident?

Or is this just so that the code can be easily copied and pasted into projects using specific versions of Python?

Thank you for any assistance!

---

An example:
https://docs.litestar.dev/2/usage/middleware/creating-middleware.html#inheriting-abstractmiddleware
(I believe these are the v2 beta 4 docs)

from typing import TYPE_CHECKING
from time import time

from litestar.enums import ScopeType
from litestar.middleware import AbstractMiddleware
from litestar.datastructures import MutableScopeHeaders


if TYPE_CHECKING:
    from litestar.types import Message, Receive, Scope, Send


class MyMiddleware(AbstractMiddleware):
    scopes = {ScopeType.HTTP}
    exclude = ["first_path", "second_path"]
    exclude_opt_key = "exclude_from_middleware"

    async def __call__(self, scope: "Scope", receive: "Receive", send: "Send") -> None:
        start_time = time()

        async def send_wrapper(message: "Message") -> None:
            if message["type"] == "http.response.start":
                process_time = time() - start_time
                headers = MutableScopeHeaders.from_message(message=message)
                headers["X-Process-Time"] = str(process_time)
                await send(message)

        await self.app(scope, receive, send_wrapper)

(or: https://docs.litestar.dev/2/usage/security/abstract-authentication-middleware.html, here using sqlalchemy)

I assume I can write the following ok, though:

from litestar.types import Message, Receive, Scope, Send
from litestar.enums import ScopeType
from litestar.middleware import AbstractMiddleware
from litestar.datastructures import MutableScopeHeaders

class MyMiddleware(AbstractMiddleware):
    # ...

    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
         ...

I think the main thing I want to know is if I'm doing something bad when write it as the above 😅

[JacobCoffee]

The use of if TYPE_CHECKING: along with stringized annotations is a common pattern in Python type hinting to avoid circular dependencies and to reduce the runtime overhead associated with importing large modules.

Sometimes, type annotations can create circular import dependencies, where module A imports module B and module B imports module A. Using if TYPE_CHECKING: with stringized annotations ensures that the import is only considered by type checkers like mypy and not at runtime. This breaks the circular dependency. You can see an example of this in the Python docs on if TYPE_CHECKING

aslo.. if a module is heavy and only needed for type checking, using if TYPE_CHECKING: makes sure it is not imported during runtime, reducing the overhead. There are many cases however where Litestar uses types at runtime, so it varies.

Your example by directly importing types and using them in annotations, is fine if you dont face any of the above issues.. If it works for your specific use case, youre not doing anything necessarily bad by writing it that way.

Some other helpful things, maybe..

• On PEP563 and PEP649

[JacobCoffee]

It is also possible I am horribly wrong about all of this and one of the other @litestar-org/members can chime in 🙃

[Goldziher]

We should remove these from the examples - since it's confusing

[ceigey]

Thank you @JacobCoffee for the explanation! I'll keep an eye out for that, the runtime cost of importing the module is something I didn't consider!