From 21d552c600fb132ad3980ca610c9536d6932a3aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sybren=20A=2E=20St=C3=BCvel?= Date: Fri, 11 Mar 2022 16:51:19 +0100 Subject: [PATCH] Addon: add explanation of weird type-checking code --- addon/README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/addon/README.md b/addon/README.md index c5819024..388078f4 100644 --- a/addon/README.md +++ b/addon/README.md @@ -13,3 +13,19 @@ poetry install 1. Make sure Java is installed (so `java --version` shows something sensible). 2. In the root directory of the repository, run `make generate-py` + + +## Type annotations and lazy imports + +This add-on tries to only load Python packages from wheel files when necessary. Loading things from wheels is tricky, as they basically pollute the `sys.modules` dictionary and thus can "leak" to other add-ons. This can cause conflicts when, for example, another add-on is using a different version of the same package. + +The result is that sometimes there are some strange hoops to jump through. The most obvious one is for type annotations. This is why you'll see code like: + +``` +if TYPE_CHECKING: + from .bat_interface import PackThread +else: + PackThread = object +``` + +This makes it possible to declare a function with `def func() -> PackThread`, without having to load `bat_interface` immediately at import time.