Proposal for type hint use in Blender's Python scripts #87333

New Issue

Campbell Barton · 2021-04-09T11:31:22+02:00

Campbell Barton commented

2021-04-09 11:31:22 +02:00

This proposal suggests how we could include type hints in Blender's Python code (based on a discussion with @mont29 regarding how & where we might use type hints).

Motivation

Adding type information gives us some of the benefits of a statically typed language:

Guarantees on the types of arguments, return values and class members.
Warnings when changes to code don't meet type requirements.
Serves as a kind of checked documentation.
Improved IDE integration (potentially).

While these can be useful, there are some down sites to type hints too:

Adds noise in situations where there ambiguity regarding type information isn't a significant problem.
Increases the barrier of entry for developers submitting patches.
Adds some overhead to add & maintain,

there are some cases where properly setting types gets quite involved or isn't yet supported in `mypy`.

They make deferring imports impractical in some situations

(as the function signature may require the module to be imported to reference it's type).

Current Status

Type hints aren't used in Blender's core Python scripts.
Type hints are used in some utility scripts (./build_files/, ./release/steam),

although most don't pass `mypy --strict`.

Add-ons are free to use type hints if they wish.

Created #87409 to keep track of scripts that can be used with mypy.

Proposal

Identify areas that make sense to use type hints, and where not to.

//For example, we might want to add type hints to `rna_info` & `bl_i18n_utils` modules,
but not for `./release/scripts/startup/bl_ui` as most of the UI classes are boiler plate UI sub-classes
with common callbacks.//

Move to type hints on a per-module basis.
- Blender modules must go via patch review, so we can ensure this is being applied consistently.
- Stand-alone scripts can be committed directly (such as stand-alone Python scripts in source/tools).
Only add type hints when they can be validated (where mypy can run on the file without problems).

This means before moving any modules that use `bpy`, we will need to find a way to either stub or add type hints
to Blender's C/Python API's.

Be strict (use mypy --strict)

This means a script will either have type information or not,
to avoid the kinds of type information included depending on the personal preference of whoever last edited the file,
also to make it obvious when type information was accidentally left out,
avoiding discussion about when to use type hints in a given area.

Any situations where it's not practical to use type hints (such as recursive types)
must explicitly disable type checking with an explanation for why it was needed.
See: https://github.com/python/mypy/issues/731

Proposed Steps

Add type hint information to scripts that run outside Blender.

This can be done right now.

Any further work requires a way to run mypy with scripts that use bpy and other Blender modules.

This needs some investigation.
Blender modules can then move to using type hints where appropriate.
We can then investigate if it's worth expanding type hint use to other areas areas, or leave as-is.

Notes

Python may be changing how annotations are stored & accessed, see: https://www.python.org/dev/peps/pep-0649/

This could impact how parts of the C/API expose annotations.

If this information is to be extracted from Blender's Python API, we could take a wait and see approach.

Supporting blender modules within mypy is one of the main tasks to support type hints.

This proposal suggests how we could include type hints in Blender's Python code *(based on a discussion with @mont29 regarding how & where we might use type hints)*. ## Motivation Adding type information gives us some of the benefits of a statically typed language: - Guarantees on the types of arguments, return values and class members. - Warnings when changes to code don't meet type requirements. - Serves as a kind of checked documentation. - Improved IDE integration (potentially). While these can be useful, there are some down sites to type hints too: - Adds noise in situations where there ambiguity regarding type information isn't a significant problem. - Increases the barrier of entry for developers submitting patches. - Adds some overhead to add & maintain, ``` there are some cases where properly setting types gets quite involved or isn't yet supported in `mypy`. ``` - They make deferring imports impractical in some situations ``` (as the function signature may require the module to be imported to reference it's type). ``` ## Current Status - Type hints aren't used in Blender's core Python scripts. - Type hints are used in some utility scripts (`./build_files/`, `./release/steam`), ``` although most don't pass `mypy --strict`. ``` - Add-ons are free to use type hints if they wish. Created #87409 to keep track of scripts that can be used with mypy. ## Proposal - Identify areas that make sense to use type hints, and where not to. ``` //For example, we might want to add type hints to `rna_info` & `bl_i18n_utils` modules, but not for `./release/scripts/startup/bl_ui` as most of the UI classes are boiler plate UI sub-classes with common callbacks.// ``` - Move to type hints on a per-module basis. - Blender modules must go via patch review, so we can ensure this is being applied consistently. - Stand-alone scripts can be committed directly (such as stand-alone Python scripts in `source/tools`). - Only add type hints when they can be validated (where `mypy` can run on the file without problems). ``` This means before moving any modules that use `bpy`, we will need to find a way to either stub or add type hints to Blender's C/Python API's. ``` - Be strict (use `mypy --strict`) ``` This means a script will either have type information or not, to avoid the kinds of type information included depending on the personal preference of whoever last edited the file, also to make it obvious when type information was accidentally left out, avoiding discussion about when to use type hints in a given area. ``` ``` Any situations where it's not practical to use type hints (such as recursive types) must explicitly disable type checking with an explanation for why it was needed. See: https://github.com/python/mypy/issues/731 ``` ## Proposed Steps - Add type hint information to scripts that run outside Blender. ``` This can be done right now. ``` - Any further work requires a way to run `mypy` with scripts that use `bpy` and other Blender modules. *This needs some investigation.* - Blender modules can then move to using type hints where appropriate. - We can then investigate if it's worth expanding type hint use to other areas areas, or leave as-is. ## Notes - Python may be changing how annotations are stored & accessed, see: https://www.python.org/dev/peps/pep-0649/ ``` This could impact how parts of the C/API expose annotations. ``` ``` If this information is to be extracted from Blender's Python API, we could take a wait and see approach. ``` - Supporting blender modules within `mypy` is one of the main tasks to support type hints.

Campbell Barton commented

2021-04-09 11:31:22 +02:00

Changed status from 'Needs Triage' to: 'Confirmed'

Campbell Barton commented

2021-04-09 11:31:22 +02:00

Added subscribers: @mont29, @ideasman42

Bastien Montagne commented

2021-04-09 14:35:53 +02:00

For the records, proposal LGTM... Personnaly I would be very conservative about what module we switch to type hinting though.

Campbell Barton commented

2021-04-12 04:30:20 +02:00

In #87333#1143782, @mont29 wrote:
For the records, proposal LGTM... Personnaly I would be very conservative about what module we switch to type hinting though.

No issues with being conservative, especially for startup/core-scripts, although this isn't likely to be an issue until using type hints with Blender's C/API modules are supported.

Created #87409 to keep track of scripts that can be used with mypy.

> In #87333#1143782, @mont29 wrote: > For the records, proposal LGTM... Personnaly I would be very conservative about what module we switch to type hinting though. No issues with being conservative, especially for startup/core-scripts, although this isn't likely to be an issue until using type hints with Blender's C/API modules are supported. Created #87409 to keep track of scripts that can be used with mypy.

Sybren A. Stüvel commented

2021-04-12 13:34:51 +02:00

Added subscriber: @dr.sybren

Sybren A. Stüvel commented

2021-04-12 13:34:51 +02:00

Guarantees on the types of arguments, return values and class members.

This is not strictly true -- there are no hard guarantees, at least not at runtime.

Adds noise in situations where there ambiguity regarding type information isn't a significant problem.

I've hardly run into such situations in practice. There have been cases where I thought things were clear enough without annotations, but often I was later glad that I added them anyway. For example, some operator execute function that ends with return some_other_function() where that other function gets refactored to return something other than {'FINISHED'}. Yes, it is super clear to use that an operator execute function returns Set[str], so it could be argued that adding such an annotation is noise. However, removing that annotation would have made it impossible for mypy to detect the just-decribed problem.

Increases the barrier of entry for developers submitting patches.

I see this as a very minor barrier. More locally-understandable, better described code means that it's easier to contribute to that code. Having more ways to do automated checks on that code also makes it easier to catch problems early. Both contribute to a more pleasant experience submitting patches. Of course these developers need to know how to use type annotations, and that does present a bit of a barrier, but IMO compared to learning how to script for Blender in the first place this is also minor.

In the past years I've used this mypy.ini to check add-on code, and it has served me quite well. It allows us to use mypy without having to wait for complete stubs of bpy, while still staying quite strict in other areas.

[mypy]
python_version = 3.7
ignore_missing_imports = True
strict_optional = True
disallow_any_generics = True
disallow_untyped_calls = True
disallow_incomplete_defs = True
check_untyped_defs = True
disallow_untyped_decorators = True
no_implicit_optional = True
warn_redundant_casts = True
warn_unused_ignores = true
warn_return_any = True

Of course these stubs will be super useful, and will make the automated type checking much stronger. I don't think we have to wait with type annotations until we have those stubs, though.

About being conservative, do we even have timing information about the actual cost of adding type annotations to startup scripts? And is this based on Python 3.9, which is faster to handle such things than 3.7? If not, I strongly object against the "be conservative", as it's not based on actual knowledge, but does stand in the way of more understandable code.

> Guarantees on the types of arguments, return values and class members. This is not strictly true -- there are no hard guarantees, at least not at runtime. > Adds noise in situations where there ambiguity regarding type information isn't a significant problem. I've hardly run into such situations in practice. There have been cases where I thought things were clear enough without annotations, but often I was later glad that I added them anyway. For example, some operator execute function that ends with `return some_other_function()` where that other function gets refactored to return something other than `{'FINISHED'}`. Yes, it is super clear to use that an operator execute function returns `Set[str]`, so it could be argued that adding such an annotation is noise. However, removing that annotation would have made it impossible for mypy to detect the just-decribed problem. > Increases the barrier of entry for developers submitting patches. I see this as a very minor barrier. More locally-understandable, better described code means that it's easier to contribute to that code. Having more ways to do automated checks on that code also makes it easier to catch problems early. Both contribute to a more pleasant experience submitting patches. Of course these developers need to know how to use type annotations, and that does present a bit of a barrier, but IMO compared to learning how to script for Blender in the first place this is also minor. In the past years I've used this `mypy.ini` to check add-on code, and it has served me quite well. It allows us to use mypy without having to wait for complete stubs of `bpy`, while still staying quite strict in other areas. ``` [mypy] python_version = 3.7 ignore_missing_imports = True strict_optional = True disallow_any_generics = True disallow_untyped_calls = True disallow_incomplete_defs = True check_untyped_defs = True disallow_untyped_decorators = True no_implicit_optional = True warn_redundant_casts = True warn_unused_ignores = true warn_return_any = True ``` Of course these stubs will be super useful, and will make the automated type checking much stronger. I don't think we have to wait with type annotations until we have those stubs, though. About being conservative, do we even have timing information about the actual cost of adding type annotations to startup scripts? And is this based on Python 3.9, which is faster to handle such things than 3.7? If not, I strongly object against the "be conservative", as it's not based on actual knowledge, but does stand in the way of more understandable code.

Campbell Barton commented

2021-04-12 14:21:19 +02:00

In #87333#1145038, @dr.sybren wrote:

Adds noise in situations where there ambiguity regarding type information isn't a significant problem.

I've hardly run into such situations in practice. There have been cases where I thought things were clear enough without annotations, but often I was later glad that I added them anyway.

I tend to agree with you here, nevertheless, some scripts are very small, and realistically they aren't going to be a maintenance problem either way AFAICS.

Increases the barrier of entry for developers submitting patches.

I see this as a very minor barrier. More locally-understandable, better described code means that it's easier to contribute to that code. Having more ways to do automated checks on that code also makes it easier to catch problems early. Both contribute to a more pleasant experience submitting patches. Of course these developers need to know how to use type annotations, and that does present a bit of a barrier, but IMO compared to learning how to script for Blender in the first place this is also minor.

The barrier of entry IMHO is more that new developers have to become familier with new tools that have stumbling blocks we can't avoid entirely.

They use an old version of mypy and get errors, it takes them time to figure out this is the problem.
They attempt a typing configuration mypy doesn't support, it takes time for them to research this and discover they can't use type hints in this case.
They run into a problem that turns out to be a bug in mypy (currently there are 1.6k open issues).
They run into a problem which turns out to be an incorrect typing of one of Blender's own functions.

All of these scenarios can be quite demotivating, even if newer developers manage to overcome them, it's just a cost to taking on type hinting, not a reason to reject it. Even so, if there is minimal gain in an area, we could leave it out for now. Areas that have much more to gain can be worked on first & we can re-evaluate once they're done.

In the past years I've used this mypy.ini to check add-on code, and it has served me quite well. It allows us to use mypy without having to wait for complete stubs of bpy, while still staying quite strict in other areas.
[mypy]
python_version = 3.7
ignore_missing_imports = True
strict_optional = True
disallow_any_generics = True
disallow_untyped_calls = True
disallow_incomplete_defs = True
check_untyped_defs = True
disallow_untyped_decorators = True
no_implicit_optional = True
warn_redundant_casts = True
warn_unused_ignores = true
warn_return_any = True
Of course these stubs will be super useful, and will make the automated type checking much stronger. I don't think we have to wait with type annotations until we have those stubs, though.

I'd like to have the stubs before moving bpy and other modules to use typing, it shouldn't be so hard to generate them.

About being conservative, do we even have timing information about the actual cost of adding type annotations to startup scripts? And is this based on Python 3.9, which is faster to handle such things than 3.7? If not, I strongly object against the "be conservative", as it's not based on actual knowledge, but does stand in the way of more understandable code.

Probably the cost isn't prohibitive, although for switching startup modules - it's reasonable the changes are proven not to cause significant issues. I didn't think @mont29's comment about being conservative was with regard to performance though.

> In #87333#1145038, @dr.sybren wrote: >> Adds noise in situations where there ambiguity regarding type information isn't a significant problem. > I've hardly run into such situations in practice. There have been cases where I thought things were clear enough without annotations, but often I was later glad that I added them anyway. I tend to agree with you here, nevertheless, some scripts are very small, and realistically they aren't going to be a maintenance problem either way AFAICS. > >> Increases the barrier of entry for developers submitting patches. > I see this as a very minor barrier. More locally-understandable, better described code means that it's easier to contribute to that code. Having more ways to do automated checks on that code also makes it easier to catch problems early. Both contribute to a more pleasant experience submitting patches. Of course these developers need to know how to use type annotations, and that does present a bit of a barrier, but IMO compared to learning how to script for Blender in the first place this is also minor. The barrier of entry IMHO is more that new developers have to become familier with new tools that have stumbling blocks we can't avoid entirely. - They use an old version of `mypy` and get errors, it takes them time to figure out this is the problem. - They attempt a typing configuration mypy doesn't support, it takes time for them to research this and discover they can't use type hints in this case. - They run into a problem that turns out to be a bug in mypy (currently there are 1.6k open issues). - They run into a problem which turns out to be an incorrect typing of one of Blender's own functions. All of these scenarios can be quite demotivating, even if newer developers manage to overcome them, it's just a cost to taking on type hinting, not a reason to reject it. Even so, if there is minimal gain in an area, we could leave it out for now. Areas that have much more to gain can be worked on first & we can re-evaluate once they're done. > In the past years I've used this `mypy.ini` to check add-on code, and it has served me quite well. It allows us to use mypy without having to wait for complete stubs of `bpy`, while still staying quite strict in other areas. > > ``` > [mypy] > python_version = 3.7 > ignore_missing_imports = True > strict_optional = True > disallow_any_generics = True > disallow_untyped_calls = True > disallow_incomplete_defs = True > check_untyped_defs = True > disallow_untyped_decorators = True > no_implicit_optional = True > warn_redundant_casts = True > warn_unused_ignores = true > warn_return_any = True > ``` > > Of course these stubs will be super useful, and will make the automated type checking much stronger. I don't think we have to wait with type annotations until we have those stubs, though. I'd like to have the stubs before moving bpy and other modules to use typing, it shouldn't be so hard to generate them. > About being conservative, do we even have timing information about the actual cost of adding type annotations to startup scripts? And is this based on Python 3.9, which is faster to handle such things than 3.7? If not, I strongly object against the "be conservative", as it's not based on actual knowledge, but does stand in the way of more understandable code. Probably the cost isn't prohibitive, although for switching startup modules - it's reasonable the changes are proven not to cause significant issues. I didn't think @mont29's comment about being conservative was with regard to performance though.

Mateusz Grzeliński commented

2022-03-07 21:46:27 +01:00

Added subscriber: @grzelins

Mateusz Grzeliński commented

2022-03-07 22:16:49 +01:00

Just wanted to mention that I made a deep dive into this issue in this thread: Proposal: Generate stub files for blender back in 2020. There are many attempts by community to generate stub files, there are links in this thread including:

generating stub files from documentation
generating stub files from runtime data
but it can not be simply done with addon, an ingeration to source code is required and it is quite hard to get it through.

When writting this post I am experimenting with LSP and mypy plugin + VS code extension.
Writing stub generator proved to be

really hard to implement,
it requires ingeration in C code (see argument clinic in the devtalk thread) to do it right,
strict syntax in docstring :type param: annotation to enable parsing (and parsing doc strings in often not supported in type checkers)
results in huge bpy.types file - this is slow
I wrote one, so I know. LSP might be the way to go, we will see.
BTW. writing stub generator is very similar to writing API documentation generator (currently we use sphinx), so there is that.

Just wanted to mention that I made a deep dive into this issue in this thread: [Proposal: Generate stub files for blender ](https://devtalk.blender.org/t/proposal-generate-stub-files-for-blender/15819) back in 2020. There are many attempts by community to generate stub files, there are links in this thread including: - generating stub files from documentation - generating stub files from runtime data but it can not be simply done with addon, an ingeration to source code is required and it is quite hard to get it through. When writting this post I am experimenting with [LSP](https://microsoft.github.io/language-server-protocol/) and `mypy` plugin + VS code extension. Writing stub generator proved to be 1. really hard to implement, 2. it requires ingeration in C code (see argument clinic in the devtalk thread) to do it right, 3. strict syntax in docstring `:type param:` annotation to enable parsing (and parsing doc strings in often not supported in type checkers) 4. results in huge `bpy.types` file - this is slow I wrote one, so I know. LSP might be the way to go, we will see. BTW. writing stub generator is very similar to writing API documentation generator (currently we use sphinx), so there is that.

Philipp Oeser removed the

Download

What's New

Blender Studio

Manual

Developers Blog

Documentation

Benchmark

Blender Conference

Development Fund

One-time Donations

Proposal for type hint use in Blender's Python scripts #87333

Motivation

Current Status

Proposal

Proposed Steps

Notes