<table border="1" cellspacing="0" cellpadding="8">
    <tr>
        <th>Issue</th>
        <td>
            <a href=https://github.com/llvm/llvm-project/issues/76664>76664</a>
        </td>
    </tr>

    <tr>
        <th>Summary</th>
        <td>
            [clang/python] Add type annotation to libclang Python binding
        </td>
    </tr>

    <tr>
      <th>Labels</th>
      <td>
            clang
      </td>
    </tr>

    <tr>
      <th>Assignees</th>
      <td>
      </td>
    </tr>

    <tr>
      <th>Reporter</th>
      <td>
          linux4life798
      </td>
    </tr>
</table>

<pre>
    The libclang Python binding needs type annotations. Type annotations are important for libraries because they enable the IDE to help users learn the API and steer them in the correct direction through code completions. Furthermore, they allow the IDEs + static checkers to identify a large range of misuse errors.

This topic has been discussed a bit in [DeinAlptraum's conversation on Discourse](https://discourse.llvm.org/t/type-annotations-for-libclang-python-bindings/70644).

---

There are a few issues that would need to be addressed before we can simply merge type annotations into the python files.
1. The straightforward way to implement type annotations requires Python 3, but the main [cindex.py still makes mention of Python 2](https://github.com/llvm/llvm-project/blob/90c397fc56b7a04dd53cdad8103de1ead9686104/clang/bindings/python/clang/cindex.py#L113-L124). We should be dropping Python 2 support.
2. Type annotations have evolved a bit throughout Python 3 (ex. shift from using `List[str]` to `list[str]` OR `Optional[str]` to `str | None`). Using the newer syntax/style may make the library incompatible with earlier versions of Python 3. So, we need to figure out a reasonable Python 3 version cutoff and implement CI checks to ensure compatibility with the earliest version we want to support.

   Python 3.7 might be a good cutoff. This aligns with [Debian buster](https://wiki.debian.org/Python#Supported_Python_Versions).

Helpful Resources:
* https://discourse.llvm.org/t/type-annotations-for-libclang-python-bindings/70644/9
* https://typing.readthedocs.io/en/latest/source/best_practices.html
</pre>
<img width="1px" height="1px" alt="" src="http://email.email.llvm.org/o/eJy0VsFy2zYQ_RrosiMOBYqUeNDBjqppZjJNJknbYwYEliRqEGCxoGX-fQegJCeqc-ihMzZpA8Tu2337HimIdGcRD6x8ZOVxJabQO38w2k4vW6Nb3NX7VePUfPjaIxjdSCNsB5_m0DsLjbZK2w4soiII84ggrHVBBO0sZfD1bgWER9DD6HwQNkDrfAzphddI0KAUEyGEHmdAKxqT_ob3x18gOOjRjDARegKDwtu09_DpPQirgAKijysD6GVHOu9RBlA63rSLq95NXQ_Sqbg9jAYvME-TDz36wXlk_N0CQBjjztf8BIw_AsUqJMge5VOEERxohTbodgYBRvgOwQvbIbgWBk2xGPTeecpYfmT5w3L92ut4dtQSehHLRgtKk5yIUIGARodYBCsfj6jtgxmDF9PA-I5AOvuMnlIzwVk4apJu8oSsPDK-70MYiRUPjJ8YP6nrZmbM85A53zF-CvF3HnH9HSvr1vn1ldr1mKhdX6glxk-7vNpuGa9_qGK9Xv9YFHpM9Apo8QyaaEKC0IsAZzcZlWYktqxBEEp5TNU22DqPcEaQwgLpYTQzDBg7eT9NoG1wiZAFIbTa4LWzmwzifFLwQnd9aJ0_C6_gLObEUuR6QBv-HdTj35P2SNeJLuIANFNIiQax8CC1VfiSjTNQ0MbAIJ6QIAZMPLTXw_wtGjod-qnJpBsYP0UmLrf16N1fKCMhjXEN46c6l0W9a2VZNTuRb5UqC6mE2m_yQuEGhaqrfbXJt4yfElXx5CtLS1e-27uhZrz4sNkU6w8bnmiEPxGoT6Q0CMq7cdSvmuZA0xgVemktf0PGvXhGwGdnnm8Te1GXm8KtlcD4Hl8yoF63AVrvBpgoZmJV_kFTYOUjBR97VuWRJlbl5n754-e4_HGMeYV54wQFD2z3Dn5zFlmVp_p-T1kigxbP6IFmG8QL4ycKs4m0zonC9MTiPzNoGy1BBB1t56xDDyi80eghKi5V_Up0kcEXFyfljLe5bnU3eYTYAAEeBbnFwm7duMQBOQXXtsm2Xgfz3fvFV5KroKUY6gpIGx3mBVNEvOCicAt4RjhHOw3ujrrlCvAKewdD1EcSIXTOqQuaKB9NIIzuLC2pkv80WlhoJgro35rts37SmUpPXfzl02UKiy8LElTflqVvf1zaeG8kv6IZ28nAZyQ3eYkp-rLPH-D_tbRT_bNMYY6ayDwKFXpUTlKmHeMnjAozIiDFtAviqEOk8G30QgYtkbI-DGalDoWqi1qs8LDZ5du8rIq6WPWHulG7Vm73bSnytuZN_Efke6HaVpbtfrfSB57zYhN_8rIueVZsGt7kVcU3RdvWcse2OQ5Cm1sXVsluD7uqqrYrIxo0lF7onF_MIDrTyh-S7zRTR2ybpEavEYIOJn0FXO3j4iflER6UujfOOGs_-RhYTd4c_rMFLu-LyEys4Z8AAAD__4rl6xE">