#439 add docstrings for mixins

nicegui/elements/mixins/content_element.py

@@ -1,5 +1,7 @@
 from typing import Any, Callable
 
+from typing_extensions import Self
+
 from ...binding import BindableProperty, bind, bind_from, bind_to
 from ...element import Element
 
@@ -13,23 +15,65 @@ class ContentElement(Element):
         self.content = content
         self.on_content_change(content)
 
-    def bind_content_to(self, target_object: Any, target_name: str = 'content', forward: Callable = lambda x: x):
+    def bind_content_to(self,
+                        target_object: Any,
+                        target_name: str = 'content',
+                        forward: Callable = lambda x: x) -> Self:
+        """Bind the content of this element to the target object's target_name property.
+
+        The binding works one way only, from this element to the target.
+
+        :param target_object: The object to bind to.
+        :param target_name: The name of the property to bind to.
+        :param forward: A function to apply to the value before applying it to the target.
+        """
         bind_to(self, 'content', target_object, target_name, forward)
         return self
 
-    def bind_content_from(self, target_object: Any, target_name: str = 'content', backward: Callable = lambda x: x):
+    def bind_content_from(self,
+                          target_object: Any,
+                          target_name: str = 'content',
+                          backward: Callable = lambda x: x) -> Self:
+        """Bind the content of this element from the target object's target_name property.
+
+        The binding works one way only, from the target to this element.
+
+        :param target_object: The object to bind from.
+        :param target_name: The name of the property to bind from.
+        :param backward: A function to apply to the value before applying it to this element.
+        """
         bind_from(self, 'content', target_object, target_name, backward)
         return self
 
-    def bind_content(self, target_object: Any, target_name: str = 'content', *,
-                     forward: Callable = lambda x: x, backward: Callable = lambda x: x):
+    def bind_content(self,
+                     target_object: Any,
+                     target_name: str = 'content', *,
+                     forward: Callable = lambda x: x,
+                     backward: Callable = lambda x: x) -> Self:
+        """Bind the content of this element to the target object's target_name property.
+
+        The binding works both ways, from this element to the target and from the target to this element.
+
+        :param target_object: The object to bind to.
+        :param target_name: The name of the property to bind to.
+        :param forward: A function to apply to the value before applying it to the target.
+        :param backward: A function to apply to the value before applying it to this element.
+        """
         bind(self, 'content', target_object, target_name, forward=forward, backward=backward)
         return self
 
     def set_content(self, content: str) -> None:
+        """Set the content of this element.
+
+        :param content: The new content.
+        """
         self.content = content
 
     def on_content_change(self, content: str) -> None:
+        """Called when the content of this element changes.
+
+        :param content: The new content.
+        """
         if self.CONTENT_PROP == 'innerHTML' and '</script>' in content:
             raise ValueError('HTML elements must not contain <script> tags. Use ui.add_body_html() instead.')
         self._props[self.CONTENT_PROP] = content

nicegui/elements/mixins/filter_element.py

@@ -1,5 +1,7 @@
 from typing import Any, Callable, Optional
 
+from typing_extensions import Self
+
 from ...binding import BindableProperty, bind, bind_from, bind_to
 from ...element import Element
 
@@ -13,22 +15,64 @@ class FilterElement(Element):
         self.filter = filter
         self._props[self.FILTER_PROP] = filter
 
-    def bind_filter_to(self, target_object: Any, target_name: str = 'filter', forward: Callable = lambda x: x):
+    def bind_filter_to(self,
+                       target_object: Any,
+                       target_name: str = 'filter',
+                       forward: Callable = lambda x: x) -> Self:
+        """Bind the filter of this element to the target object's target_name property.
+
+        The binding works one way only, from this element to the target.
+
+        :param target_object: The object to bind to.
+        :param target_name: The name of the property to bind to.
+        :param forward: A function to apply to the value before applying it to the target.
+        """
         bind_to(self, 'filter', target_object, target_name, forward)
         return self
 
-    def bind_filter_from(self, target_object: Any, target_name: str = 'filter', backward: Callable = lambda x: x):
+    def bind_filter_from(self,
+                         target_object: Any,
+                         target_name: str = 'filter',
+                         backward: Callable = lambda x: x) -> Self:
+        """Bind the filter of this element from the target object's target_name property.
+
+        The binding works one way only, from the target to this element.
+
+        :param target_object: The object to bind from.
+        :param target_name: The name of the property to bind from.
+        :param backward: A function to apply to the value before applying it to this element.
+        """
         bind_from(self, 'filter', target_object, target_name, backward)
         return self
 
-    def bind_filter(self, target_object: Any, target_name: str = 'filter', *,
-                    forward: Callable = lambda x: x, backward: Callable = lambda x: x):
+    def bind_filter(self,
+                    target_object: Any,
+                    target_name: str = 'filter', *,
+                    forward: Callable = lambda x: x,
+                    backward: Callable = lambda x: x) -> Self:
+        """Bind the filter of this element to the target object's target_name property.
+
+        The binding works both ways, from this element to the target and from the target to this element.
+
+        :param target_object: The object to bind to.
+        :param target_name: The name of the property to bind to.
+        :param forward: A function to apply to the value before applying it to the target.
+        :param backward: A function to apply to the value before applying it to this element.
+        """
         bind(self, 'filter', target_object, target_name, forward=forward, backward=backward)
         return self
 
     def set_filter(self, filter: str) -> None:
+        """Set the filter of this element.
+
+        :param filter: The new filter.
+        """
         self.filter = filter
 
     def on_filter_change(self, filter: str) -> None:
+        """Called when the filter of this element changes.
+
+        :param filter: The new filter.
+        """
         self._props[self.FILTER_PROP] = filter
         self.update()

nicegui/elements/mixins/source_element.py

@@ -1,5 +1,7 @@
 from typing import Any, Callable
 
+from typing_extensions import Self
+
 from ...binding import BindableProperty, bind, bind_from, bind_to
 from ...element import Element
 
@@ -12,22 +14,64 @@ class SourceElement(Element):
         self.source = source
         self._props['src'] = source
 
-    def bind_source_to(self, target_object: Any, target_name: str = 'source', forward: Callable = lambda x: x):
+    def bind_source_to(self,
+                       target_object: Any,
+                       target_name: str = 'source',
+                       forward: Callable = lambda x: x) -> Self:
+        """Bind the source of this element to the target object's target_name property.
+
+        The binding works one way only, from this element to the target.
+
+        :param target_object: The object to bind to.
+        :param target_name: The name of the property to bind to.
+        :param forward: A function to apply to the value before applying it to the target.
+        """
         bind_to(self, 'source', target_object, target_name, forward)
         return self
 
-    def bind_source_from(self, target_object: Any, target_name: str = 'source', backward: Callable = lambda x: x):
+    def bind_source_from(self,
+                         target_object: Any,
+                         target_name: str = 'source',
+                         backward: Callable = lambda x: x) -> Self:
+        """Bind the source of this element from the target object's target_name property.
+
+        The binding works one way only, from the target to this element.
+
+        :param target_object: The object to bind from.
+        :param target_name: The name of the property to bind from.
+        :param backward: A function to apply to the value before applying it to this element.
+        """
         bind_from(self, 'source', target_object, target_name, backward)
         return self
 
-    def bind_source(self, target_object: Any, target_name: str = 'source', *,
-                    forward: Callable = lambda x: x, backward: Callable = lambda x: x):
+    def bind_source(self,
+                    target_object: Any,
+                    target_name: str = 'source', *,
+                    forward: Callable = lambda x: x,
+                    backward: Callable = lambda x: x) -> Self:
+        """Bind the source of this element to the target object's target_name property.
+
+        The binding works both ways, from this element to the target and from the target to this element.
+
+        :param target_object: The object to bind to.
+        :param target_name: The name of the property to bind to.
+        :param forward: A function to apply to the value before applying it to the target.
+        :param backward: A function to apply to the value before applying it to this element.
+        """
         bind(self, 'source', target_object, target_name, forward=forward, backward=backward)
         return self
 
     def set_source(self, source: str) -> None:
+        """Set the source of this element.
+
+        :param source: The new source.
+        """
         self.source = source
 
     def on_source_change(self, source: str) -> None:
+        """Called when the source of this element changes.
+
+        :param source: The new source.
+        """
         self._props['src'] = source
         self.update()

nicegui/elements/mixins/text_element.py

@@ -1,5 +1,7 @@
 from typing import Any, Callable
 
+from typing_extensions import Self
+
 from ...binding import BindableProperty, bind, bind_from, bind_to
 from ...element import Element
 
@@ -12,23 +14,65 @@ class TextElement(Element):
         self.text = text
         self._text_to_model_text(text)
 
-    def bind_text_to(self, target_object: Any, target_name: str = 'text', forward: Callable = lambda x: x):
+    def bind_text_to(self,
+                     target_object: Any,
+                     target_name: str = 'text',
+                     forward: Callable = lambda x: x) -> Self:
+        """Bind the text of this element to the target object's target_name property.
+
+        The binding works one way only, from this element to the target.
+
+        :param target_object: The object to bind to.
+        :param target_name: The name of the property to bind to.
+        :param forward: A function to apply to the value before applying it to the target.
+        """
         bind_to(self, 'text', target_object, target_name, forward)
         return self
 
-    def bind_text_from(self, target_object: Any, target_name: str = 'text', backward: Callable = lambda x: x):
+    def bind_text_from(self,
+                       target_object: Any,
+                       target_name: str = 'text',
+                       backward: Callable = lambda x: x) -> Self:
+        """Bind the text of this element from the target object's target_name property.
+
+        The binding works one way only, from the target to this element.
+
+        :param target_object: The object to bind from.
+        :param target_name: The name of the property to bind from.
+        :param backward: A function to apply to the value before applying it to this element.
+        """
         bind_from(self, 'text', target_object, target_name, backward)
         return self
 
-    def bind_text(self, target_object: Any, target_name: str = 'text', *,
-                  forward: Callable = lambda x: x, backward: Callable = lambda x: x):
+    def bind_text(self,
+                  target_object: Any,
+                  target_name: str = 'text', *,
+                  forward: Callable = lambda x: x,
+                  backward: Callable = lambda x: x) -> Self:
+        """Bind the text of this element to the target object's target_name property.
+
+        The binding works both ways, from this element to the target and from the target to this element.
+
+        :param target_object: The object to bind to.
+        :param target_name: The name of the property to bind to.
+        :param forward: A function to apply to the value before applying it to the target.
+        :param backward: A function to apply to the value before applying it to this element.
+        """
         bind(self, 'text', target_object, target_name, forward=forward, backward=backward)
         return self
 
     def set_text(self, text: str) -> None:
+        """Set the text of this element.
+
+        :param text: The new text.
+        """
         self.text = text
 
     def on_text_change(self, text: str) -> None:
+        """Called when the text of this element changes.
+
+        :param text: The new text.
+        """
         self._text_to_model_text(text)
         self.update()
 

nicegui/elements/mixins/value_element.py

@@ -1,5 +1,7 @@
 from typing import Any, Callable, Dict, Optional
 
+from typing_extensions import Self
+
 from ...binding import BindableProperty, bind, bind_from, bind_to
 from ...element import Element
 from ...events import ValueChangeEventArguments, handle_event
@@ -25,23 +27,65 @@ class ValueElement(Element):
             self._send_update_on_value_change = True
         self.on(f'update:{self.VALUE_PROP}', handle_change, self.EVENT_ARGS, throttle=throttle)
 
-    def bind_value_to(self, target_object: Any, target_name: str = 'value', forward: Callable = lambda x: x):
+    def bind_value_to(self,
+                      target_object: Any,
+                      target_name: str = 'value',
+                      forward: Callable = lambda x: x) -> Self:
+        """Bind the value of this element to the target object's target_name property.
+
+        The binding works one way only, from this element to the target.
+
+        :param target_object: The object to bind to.
+        :param target_name: The name of the property to bind to.
+        :param forward: A function to apply to the value before applying it to the target.
+        """
         bind_to(self, 'value', target_object, target_name, forward)
         return self
 
-    def bind_value_from(self, target_object: Any, target_name: str = 'value', backward: Callable = lambda x: x):
+    def bind_value_from(self,
+                        target_object: Any,
+                        target_name: str = 'value',
+                        backward: Callable = lambda x: x) -> Self:
+        """Bind the value of this element from the target object's target_name property.
+
+        The binding works one way only, from the target to this element.
+
+        :param target_object: The object to bind from.
+        :param target_name: The name of the property to bind from.
+        :param backward: A function to apply to the value before applying it to this element.
+        """
         bind_from(self, 'value', target_object, target_name, backward)
         return self
 
-    def bind_value(self, target_object: Any, target_name: str = 'value', *,
-                   forward: Callable = lambda x: x, backward: Callable = lambda x: x):
+    def bind_value(self,
+                   target_object: Any,
+                   target_name: str = 'value', *,
+                   forward: Callable = lambda x: x,
+                   backward: Callable = lambda x: x) -> Self:
+        """Bind the value of this element to the target object's target_name property.
+
+        The binding works both ways, from this element to the target and from the target to this element.
+
+        :param target_object: The object to bind to.
+        :param target_name: The name of the property to bind to.
+        :param forward: A function to apply to the value before applying it to the target.
+        :param backward: A function to apply to the value before applying it to this element.
+        """
         bind(self, 'value', target_object, target_name, forward=forward, backward=backward)
         return self
 
     def set_value(self, value: Any) -> None:
+        """Set the value of this element.
+
+        :param value: The value to set.
+        """
         self.value = value
 
     def on_value_change(self, value: Any) -> None:
+        """Called when the value of this element changes.
+
+        :param value: The new value.
+        """
         self._props[self.VALUE_PROP] = self._value_to_model_value(value)
         if self._send_update_on_value_change:
             self.update()

nicegui/elements/mixins/visibility.py

@@ -1,5 +1,7 @@
 from typing import TYPE_CHECKING, Any, Callable
 
+from typing_extensions import Self
+
 from ...binding import BindableProperty, bind, bind_from, bind_to
 
 if TYPE_CHECKING:
@@ -13,28 +15,73 @@ class Visibility:
         super().__init__(**kwargs)
         self.visible = True
 
-    def bind_visibility_to(self, target_object: Any, target_name: str = 'visible', forward: Callable = lambda x: x):
+    def bind_visibility_to(self,
+                           target_object: Any,
+                           target_name: str = 'visible',
+                           forward: Callable = lambda x: x) -> Self:
+        """Bind the visibility of this element to the target object's target_name property.
+
+        The binding works one way only, from this element to the target.
+
+        :param target_object: The object to bind to.
+        :param target_name: The name of the property to bind to.
+        :param forward: A function to apply to the value before applying it to the target.
+        """
         bind_to(self, 'visible', target_object, target_name, forward)
         return self
 
-    def bind_visibility_from(self, target_object: Any, target_name: str = 'visible',
-                             backward: Callable = lambda x: x, *, value: Any = None):
+    def bind_visibility_from(self,
+                             target_object: Any,
+                             target_name: str = 'visible',
+                             backward: Callable = lambda x: x, *,
+                             value: Any = None) -> Self:
+        """Bind the visibility of this element from the target object's target_name property.
+
+        The binding works one way only, from the target to this element.
+
+        :param target_object: The object to bind from.
+        :param target_name: The name of the property to bind from.
+        :param backward: A function to apply to the value before applying it to this element.
+        :param value: If specified, the element will be visible only when the target value is equal to this value.
+        """
         if value is not None:
             def backward(x): return x == value
         bind_from(self, 'visible', target_object, target_name, backward)
         return self
 
-    def bind_visibility(self, target_object: Any, target_name: str = 'visible', *,
-                        forward: Callable = lambda x: x, backward: Callable = lambda x: x, value: Any = None):
+    def bind_visibility(self,
+                        target_object: Any,
+                        target_name: str = 'visible', *,
+                        forward: Callable = lambda x: x,
+                        backward: Callable = lambda x: x,
+                        value: Any = None) -> Self:
+        """Bind the visibility of this element to the target object's target_name property.
+
+        The binding works both ways, from this element to the target and from the target to this element.
+
+        :param target_object: The object to bind to.
+        :param target_name: The name of the property to bind to.
+        :param forward: A function to apply to the value before applying it to the target.
+        :param backward: A function to apply to the value before applying it to this element.
+        :param value: If specified, the element will be visible only when the target value is equal to this value.
+        """
         if value is not None:
             def backward(x): return x == value
         bind(self, 'visible', target_object, target_name, forward=forward, backward=backward)
         return self
 
     def set_visibility(self, visible: str) -> None:
+        """Set the visibility of this element.
+
+        :param visible: Whether the element should be visible.
+        """
         self.visible = visible
 
     def on_visibility_change(self: 'Element', visible: str) -> None:
+        """Called when the visibility of this element changes.
+
+        :param visible: Whether the element should be visible.
+        """
         if visible and 'hidden' in self._classes:
             self._classes.remove('hidden')
             self.update()

website/documentation_tools.py

@@ -175,8 +175,7 @@ def generate_method_signature_description(method: Callable) -> str:
     return_annotation = inspect.signature(method).return_annotation
     if return_annotation != inspect.Parameter.empty:
         return_type = inspect.formatannotation(return_annotation)
-        return_description = f''' -> {return_type.strip("'")}'''
-        description += return_description
+        description += f''' -> {return_type.strip("'").replace("typing_extensions.", "").replace("typing.", "")}'''
     return description
 
 
@@ -186,8 +185,7 @@ def generate_property_signature_description(property: property) -> str:
         return_annotation = inspect.signature(property.fget).return_annotation
         if return_annotation != inspect.Parameter.empty:
             return_type = inspect.formatannotation(return_annotation)
-            return_description = f': {return_type}'
-            description += return_description
+            description += f': {return_type}'
     if property.fset:
         description += ' (settable)'
     if property.fdel: