Extend the binding API to support structured persistent storage

[Aues6uen11Z]

As discussed in #2923, the existing methods find it difficult to create a multi-layered JSON structure in persistent storage (such as app.storage.general), which makes subsequent retrieval and access challenging. Directly using libraries like addict to improve PersistDict might bring some potential problems.

Therefore, my idea is to improve the binding API by automatically creating non-existent keys when binding dictionary data. This way, we can achieve the goal without affecting the existing binding usage. Specifically, I added the _convert_target method as shown below.

# nicegui/elements/mixins/value_element.py


def _convert_target(
        self,
        target_object: Any,
        target_name: Union[str, Tuple[str, ...]]
        ) -> Tuple[Any, str]:
    if isinstance(target_name, tuple):
        if isinstance(target_object, dict):
            for key in target_name[:-1]:
                try:
                    target_object[key]
                except KeyError:
                    target_object[key] = {}
                target_object = target_object[key]
            target_name = target_name[-1]
        else:
            raise TypeError

    return target_object, target_name

def bind_value(self,
                target_object: Any,
                target_name: Union[str, Tuple[str, ...]] = 'value', *,
                forward: Callable[..., Any] = lambda x: x,
                backward: Callable[..., Any] = lambda x: x,
                ) -> Self:

    # Also in bind_value_to, bind_value_from
    target_object, target_name = self._convert_target(target_object, target_name)
    bind(self, 'value', target_object, target_name, forward=forward, backward=backward)
    return self

Then we can use it like this:

from nicegui import ui
from nicegui.storage import PersistentDict


test = PersistentDict(Path('test.json'))

ui.input().bind_value(test, ('1', '2', '3'))
ui.input().bind_value(test, ('4', '5'))
ui.input().bind_value(test, ('6'))
ui.run()
"""
test.json:

{
    "1": {
        "2": {
            "3": "test"
        }
    },
    "4": {
        "5": "test"
    },
    "6": "test"
}
"""

This method is indeed a bit quirky because the original target_name of bind_value was all of type str, and now tuple type has been specially added for dict, which seems inconsistent. I wonder if there is a better implementation method?

[falkoschindler]

Thanks, @Aues6uen11Z!

Creating nested structures like

ui.number().bind_value(robot, ('motors', 'left_axis', 'max_speed'))

sounds very convenient. I wonder if an API like this would be even more handy:

ui.number().bind_value(robot, 'motors.left_axis.max_speed')

But this would cause conflicts with dictionary keys containing dots...

Or could we use *args for an API like

ui.number().bind_value(robot, 'motors', 'left_axis', 'max_speed')

[Aues6uen11Z]

Do you mean in this way? It does look better.

def bind_value(self,
               target_object: Any,
               *target_names: str,
               forward: Callable[..., Any] = lambda x: x,
               backward: Callable[..., Any] = lambda x: x,
               ) -> Self:
    if not target_names:
        target_names = ('value',)
    ......

[jixian01]

Hey
Is this feature already implemented? could this also works with bind_text_from?

BR

[falkoschindler]

No, it is not yet implemented.
But yes, if we implement it, we should do it for all binding methods.

[jixian01]

thank you!

[evnchn]

*args can't possibly work because there is the lambda forward and backward functions after it, which can be called in positional manner.

[falkoschindler]

Agreed. Even though you could distinguish strings and callables at runtime, the IDE experience wouldn't be great.

[evnchn]

Though, I think we should make forward and backward keyword-only in 4.0

[falkoschindler]

Hm, I like that you don't have to specify the direction twice for one-way bindings: bind_value_from already indicates a direction. The need for an explicit forward= or backward= requires extra care and doesn't provide value. I mean, we could rename it to a universal transform=, but what's the point?

[evnchn]

You're right. Considering the one-way binding use case, positional transformation functions are here to stay.

Guess it adds to the weight that *args can't possibly work, then.

[evnchn]

#5738