Syntax error when using Mypy and python 3.11

[n4nn31355]

System Information

• OS: Windows
• Blender version: 4.4

Description about the bug

Mypy exits with syntax error when using python 3.11 starting from fake-bpy-module-4.2.

> mypy .
***\blender_ext\Lib\site-packages\bpy\types\__init__.pyi:111576: error: invalid syntax  [syntax]
    class bpy_prop_collection[_GenericType1]:

***\blender_ext\Lib\site-packages\bpy\stub_internal\rna_enums\__init__.pyi:6: error: invalid syntax  [syntax]
    type AssetLibraryTypeItems = typing.Literal[

According to the Discord discussion, this repo uses 3.12 syntax, and while it should work fine with Pyright, mypy has an issue.

Additional comments [Optional]

[paulgolter]

Hey I get the same error using python 3.10 installing fake-bpy-module-4.3 version from pip.

When i try to run mypy:

.venv\lib\site-packages\bpy\types\__init__.pyi:101531: error: invalid syntax  [syntax]
Found 1 error in 1 file (errors prevented further checking)

Is there a workaround for this?

[Andrej730]

Hey I get the same error using python 3.10 installing fake-bpy-module-4.3 version from pip.

When i try to run mypy:

.venv\lib\site-packages\bpy\types\__init__.pyi:101531: error: invalid syntax  [syntax]
Found 1 error in 1 file (errors prevented further checking)

Is there a workaround for this?

There currently isn't, only by manually patching the file.
Btw not sure if there are any particular caveats to this, but Blender itself is using 3.11 and using stubs on Python 3.10 could lead to other issues.

[paulgolter]

Hey @Andrej730, thanks for response :)

As I understand @n4nn31355 is having the same issue with python 3.11 right?

So is the only python version that works with the fake-bpy-module package python 3.12?
We can't do that big of a jump as we need to juggle other packages as well.

Sorry for the question, I am not so familiar with stub files in python.

How would one manually patch the file? As this is a "syntax" error is it a matter of search and replacing something or is this process more involved?

[Andrej730]

@paulgolter

is having the same issue with python 3.11 right?

Yes, Python 3.12 introduced new syntax that's not parsable by ast from Python <3.12 and mypy is relying on ast, so it breaks.

Unfortunately we're currently stuck with Python 3.11, but Blender is following VFX platform (https://vfxplatform.com/) and they're heading for Python 3.13 in 2026, so in theory in Blender 5.1 (March 2026, https://projects.blender.org/blender/blender/milestone/32) they'll switch to 3.13.

S for now indeed it would be nice to solve it to support mypy, but it's been awhile since we introduced Python 3.12 syntax in stubs (don't remember exactly but it's around 6-12 months) and there were very little reports about it (only this issue).

Sorry for the question, I am not so familiar with stub files in python.

How would one manually patch the file? As this is a "syntax" error is it a matter of search and replacing something or is this process more involved?

Stub files are no different from any other Python files - you can patch them as usual text files, as ast, opening and fixing them from text editor, whatever you find reliable enough for this.

As far as I know there are two main things to patch:

• use of generics in classes (not sure if any function in fake-bpy use them at the moment). It means removing something like [T] from class definition and replacing it with (Generic[T]), but need to make sure T is defined before.

See example here - https://typing.python.org/en/latest/spec/generics.html#introduction

• type keyword for type aliases - not sure if mypy adds any special meaning to it, but in Pyright you can just remove it and it will work the same. E.g. type xxx = Literal[...] -> xxx = Literal[...]
  https://typing.python.org/en/latest/spec/aliases.html#type-statement

If you can create a generic script for this kind of patching, you can share it here to help other users.

[n4nn31355]

S for now indeed it would be nice to solve it to support mypy, but it's been awhile since we introduced Python 3.12 syntax in stubs (don't remember exactly but it's around 6-12 months) and there were very little reports about it (only this issue).

There may be few reports because you need to run mypy in CI or terminal to get an error, and it doesn't seem to be popular with addon devs.
For example, there are an issue in vscode where it silently fails without notification about error in mypy execution.

It took me a while to realize that something was wrong when I came back to the project with a new Blender version and clean virtualenv, and for a few months I just thought "well, type hints for Blender aren't good, nothing new".
I'm not sure about using Pyright/Pylance, but it's enabled by default in vscode, and it was no use for me, because after rolling back to working fake-bpy-module release, I went from zero to dozens errors, including critical ones.

[paulgolter]

Hey @Andrej730 thanks for the answer and the infos. I might look into it if it is patcheable.

@n4nn31355 Yes we run the mypy command as part of our integration tests and the blender one instantly fails because of the syntax error in python 3.10.