Correct type-hinting of BindableProperty

[dantebben]

Question

I am implementing a class that has several binding.BindableProperty properties. I would like to type-hint these, and check the typing using mypy. However, I get errors for each property that has a type hint.

Here is a simple example (example_binding.py):

from nicegui import binding, ui

class State:
    status_string: str = binding.BindableProperty()

    def __init__(self):
        self.status_string = "Initial String"

class UIMain(ui.column):
    def __init__(self, state: State) -> None:
        super().__init__()
        with self:
            ui.input(label="Enter a message").bind_value(state, "status_string")
            ui.textarea(label="Here is your message").bind_value(state, "status_string")

state = State()
UIMain(state)
ui.run()

When I run the example, it works fine. However, running mypy results in:

$ mypy example_binding.py
example_binding.py:4: error: Incompatible types in assignment (expression has type "BindableProperty", variable has type "str")  [assignment]
Found 1 error in 1 file (checked 1 source file)

What is the correct way to type-hint the status_string property, or is there a configuration that needs to be set for mypy for BindableProperty()?

Using:
Python 3.13
mypy 1.13.0
NiceGui 2.5.0

[falkoschindler]

That's an interesting question, @dantebben!

The line

status_string: str = binding.BindableProperty()

is not correct, because the BindableProperty (which is not a str) is assigned to the static field status_string. So it can't be of type str.

You could type-annotate it like

status_string: binding.BindableProperty = binding.BindableProperty()

but this isn't very helpful. As far as I understand, this is what is being inferred automatically, so you can skip the type annotation.

By the way, make sure to add a return type for __init__ so that it isn't ignored by mypy:

def __init__(self) -> None:

The assignment

self.status_string = "Initial String"

will call the __set__ method of the bindable property status_string. Here you could add a type annotation:

self.status_string: str = "Initial String"

But as I just notice, this doesn't cause mypy to complain about type mismatches:

self.status_string: str = 42  # no error

or

self.status_string: str = "Initial String"
self.status_string = 42  # no error

I guess we could make BindableProperty a generic class so you can specify the type like this:

status_string = binding.BindableProperty[str]()

But right now I don't see a way to make this type optional to avoid breaking existing code.

Anyway, I'll convert this question into a feature request. Improving type-annotations for bindable properties would be great. We just have to find out how to do it without a breaking change.

[falkoschindler]

It looks like support for TypeVars with default values has been added in Python 3.13. But currently NiceGUI needs to support 3.8 or at least 3.9. I'm not sure if a workaround exists.

[balex89]

Hi, @dantebben ! In your case as a possible workaround i would suggest to use a generic typing.Protocol. that for bindableProperty might look something like this:

from typing import Callable, TypeVar, Protocol, Optional, Any, NoReturn, Union

T = TypeVar('T')


class BindablePropertyProtocol(Protocol[T]):

    def __init__(self, on_change: Optional[Callable[..., Any]] = None) -> None: ...

    def __set_name__(self, _: Any, name: str) -> None: ...

    def __get__(self, owner: Any, _: Any = None) -> Union[T, NoReturn]: ...

    def __set__(self, owner: Any, value: T) -> None: ...


class State:
    status_string: BindablePropertyProtocol[str] = binding.BindableProperty()

    def __init__(self) -> None:
        self.status_string = "Initial String"
        self.status_string = 1  # error: Incompatible types in assignment

[falkoschindler]

Great idea! Similarly, we could introduce something like GenericBindableProperty or TypedBindableProperty as an alternative to the existing BindableProperty:

class TypedBindableProperty(binding.BindableProperty, Generic[T]):

    def __init__(self, on_change: Optional[Callable[..., Any]] = None) -> None:
        super().__init__(on_change)

    def __get__(self, owner: Any, _=None) -> T:
        return super().__get__(owner)

    def __set__(self, owner: Any, value: T) -> None:
        super().__set__(owner, value)

[dantebben]

Thanks for all of the suggestions. I went with #3988 (comment), and it is working great. I even tried to enter something wrong, and mypy caught it.

[evnchn]

As mentioned in #5785, this would be tough.