add version information to docstrings

nicegui/app/app.py

@@ -158,7 +158,7 @@ def add_static_files(self,
         :param url_path: string that starts with a slash "/" and identifies the path at which the files should be served
         :param local_directory: local folder with files to serve as static content
         :param follow_symlink: whether to follow symlinks (default: False)
-        :param max_cache_age: value for max-age set in Cache-Control header
+        :param max_cache_age: value for max-age set in Cache-Control header (*added in version 2.8.0*)
         """
         if url_path == '/':
             raise ValueError('''Path cannot be "/", because it would hide NiceGUI's internal "/_nicegui" route.''')
@@ -188,7 +188,7 @@ def add_static_file(self, *,
         :param local_file: local file to serve as static content
         :param url_path: string that starts with a slash "/" and identifies the path at which the file should be served (default: None -> auto-generated URL path)
         :param single_use: whether to remove the route after the file has been downloaded once (default: False)
-        :param max_cache_age: value for max-age set in Cache-Control header
+        :param max_cache_age: value for max-age set in Cache-Control header (*added in version 2.8.0*)
         :return: encoded URL which can be used to access the file
         """
         if max_cache_age < 0:
@@ -279,6 +279,8 @@ def clients(path: str) -> Iterator[Client]:
         When using `@ui.page("/path")` each client gets a private view of this page.
         Updates must be sent to each client individually, which this iterator simplifies.
 
+        *Added in version 2.7.0*
+
         :param path: string to filter clients by
         """
         for client in Client.instances.values():

nicegui/classes.py

@@ -25,7 +25,7 @@ def __call__(self,
 
         :param add: whitespace-delimited string of classes
         :param remove: whitespace-delimited string of classes to remove from the element
-        :param toggle: whitespace-delimited string of classes to toggle
+        :param toggle: whitespace-delimited string of classes to toggle (*added in version 2.7.0*)
         :param replace: whitespace-delimited string of classes to use instead of existing ones
         """
         new_classes = self.update_list(self, add, remove, toggle, replace)

nicegui/client.py

@@ -91,7 +91,10 @@ def is_auto_index_client(self) -> bool:
     @property
     def ip(self) -> Optional[str]:
         """Return the IP address of the client, or None if it is an
-        `auto-index page <https://nicegui.io/documentation/section_pages_routing#auto-index_page>`_."""
+        `auto-index page <https://nicegui.io/documentation/section_pages_routing#auto-index_page>`_.
+
+        *Updated in version 2.0.0: The IP address is available even before the client connects.*
+        """
         return self.request.client.host if self.request is not None and self.request.client is not None else None
 
     @property

nicegui/element.py

@@ -234,7 +234,7 @@ def default_classes(cls,
 
         :param add: whitespace-delimited string of classes
         :param remove: whitespace-delimited string of classes to remove from the element
-        :param toggle: whitespace-delimited string of classes to toggle
+        :param toggle: whitespace-delimited string of classes to toggle (*added in version 2.7.0*)
         :param replace: whitespace-delimited string of classes to use instead of existing ones
         """
         cls._default_classes = Classes.update_list(cls._default_classes, add, remove, toggle, replace)

nicegui/elements/aggrid.py

@@ -101,6 +101,8 @@ def from_polars(cls,
         If the DataFrame contains non-UTF-8 datatypes, they will be converted to strings.
         To use a different conversion, convert the DataFrame manually before passing it to this method.
 
+        *Added in version 2.7.0*
+
         :param df: Polars DataFrame
         :param theme: AG Grid theme (default: 'balham')
         :param auto_size_columns: whether to automatically resize columns to fit the grid width (default: `True`)

nicegui/elements/card.py

@@ -20,6 +20,8 @@ def __init__(self, *,
         the original QCard has no padding by default and hides outer borders and shadows of nested elements.
         If you want the original behavior, use the `tight` method.
 
+        *Updated in version 2.0.0: Don't hide outer borders and shadows of nested elements anymore.*
+
         :param align_items: alignment of the items in the card ("start", "end", "center", "baseline", or "stretch"; default: `None`)
         """
         super().__init__('q-card')

nicegui/elements/colors.py

@@ -28,7 +28,7 @@ def __init__(self, *,
         :param negative: Negative color (default: "#c10015")
         :param info: Info color (default: "#31ccec")
         :param warning: Warning color (default: "#f2c037")
-        :param custom_colors: Custom color definitions for branding (needs ``ui.colors`` to be called before custom color is ever used)
+        :param custom_colors: Custom color definitions for branding (needs ``ui.colors`` to be called before custom color is ever used, *added in version 2.2.0*)
         """
         super().__init__()
         self._props['primary'] = primary

nicegui/elements/echart.py

@@ -37,7 +37,7 @@ def __init__(self,
         :param options: dictionary of EChart options
         :param on_click_point: callback that is invoked when a point is clicked
         :param enable_3d: enforce importing the echarts-gl library
-        :param renderer: renderer to use ("canvas" or "svg")
+        :param renderer: renderer to use ("canvas" or "svg", *added in version 2.7.0*)
         """
         super().__init__()
         self._props['options'] = options

nicegui/elements/json_editor.py

@@ -30,7 +30,7 @@ def __init__(self,
         :param properties: dictionary of JSONEditor properties
         :param on_select: callback which is invoked when some of the content has been selected
         :param on_change: callback which is invoked when the content has changed
-        :param schema: optional `JSON schema <https://json-schema.org/>`_ for validating the data being edited
+        :param schema: optional `JSON schema <https://json-schema.org/>`_ for validating the data being edited (*added in version 2.8.0*)
         """
         super().__init__()
         self._props['properties'] = properties

nicegui/elements/leaflet.py

@@ -36,7 +36,7 @@ def __init__(self,
         :param zoom: initial zoom level of the map (default: 13)
         :param draw_control: whether to show the draw toolbar (default: False)
         :param options: additional options passed to the Leaflet map (default: {})
-        :param hide_drawn_items: whether to hide drawn items on the map (default: False)
+        :param hide_drawn_items: whether to hide drawn items on the map (default: False, *added in version 2.0.0*)
         """
         super().__init__()
         self.add_resource(Path(__file__).parent / 'lib' / 'leaflet')

nicegui/elements/mixins/validation_element.py

@@ -57,6 +57,8 @@ def validate(self, *, return_result: bool = True) -> bool:
         For async validation functions, ``return_result`` must be set to ``False`` and the return value will be ``True``,
         independently of the validation result which is evaluated in the background.
 
+        *Updated in version 2.7.0: Added support for async validation functions.*
+
         :param return_result: whether to return the result of the validation (default: ``True``)
         :return: whether the validation was successful (always ``True`` for async validation functions)
         """

nicegui/elements/query.py

@@ -51,7 +51,7 @@ def classes(self,
 
         :param add: whitespace-delimited string of classes
         :param remove: whitespace-delimited string of classes to remove from the element
-        :param toggle: whitespace-delimited string of classes to toggle
+        :param toggle: whitespace-delimited string of classes to toggle (*added in version 2.7.0*)
         :param replace: whitespace-delimited string of classes to use instead of existing ones
         """
         classes = Classes.update_list(self.element.props['classes'], add, remove, toggle, replace)

nicegui/elements/scene_object3d.py

@@ -203,6 +203,8 @@ def attach(self, parent: Object3D) -> None:
 
         But note that scaling is not preserved.
         If either the parent or the object itself is scaled, the object shape and position can change.
+
+        *Added in version 2.7.0*
         """
         self.detach()
         self.parent = parent
@@ -274,6 +276,8 @@ def detach(self) -> None:
 
         But note that scaling is not preserved.
         If either the parent or the object itself is scaled, the object shape and position can change.
+
+        *Added in version 2.7.0*
         """
         self._move_out_of_parent(self.parent)
         self.parent = self.scene.stack[0]
@@ -330,7 +334,10 @@ def _move_out_of_parent(self, parent: Union[Object3D, SceneObject]) -> None:
 
     @property
     def children(self) -> List[Object3D]:
-        """List of children of the object."""
+        """List of children of the object.
+
+        *Added in version 2.4.0*
+        """
         return [object for object in self.scene.objects.values() if object.parent == self]
 
     def delete(self) -> None:

nicegui/elements/table.py

@@ -45,8 +45,8 @@ def __init__(self,
         A table based on Quasar's `QTable <https://quasar.dev/vue-components/table>`_ component.
 
         :param rows: list of row objects
-        :param columns: list of column objects (defaults to the columns of the first row)
-        :param column_defaults: optional default column properties
+        :param columns: list of column objects (defaults to the columns of the first row *since version 2.0.0*)
+        :param column_defaults: optional default column properties, *added in version 2.0.0*
         :param row_key: name of the column containing unique data identifying the row (default: "id")
         :param title: title of the table
         :param selection: selection type ("single" or "multiple"; default: `None`)
@@ -128,6 +128,8 @@ def from_pandas(cls,
         To use a different conversion, convert the DataFrame manually before passing it to this method.
         See `issue 1698 <https://github.com/zauberzeug/nicegui/issues/1698>`_ for more information.
 
+        *Added in version 2.0.0*
+
         :param df: Pandas DataFrame
         :param columns: list of column objects (defaults to the columns of the dataframe)
         :param column_defaults: optional default column properties
@@ -168,6 +170,8 @@ def from_polars(cls,
         If the DataFrame contains non-UTF-8 datatypes, they will be converted to strings.
         To use a different conversion, convert the DataFrame manually before passing it to this method.
 
+        *Added in version 2.7.0*
+
         :param df: Polars DataFrame
         :param columns: list of column objects (defaults to the columns of the dataframe)
         :param column_defaults: optional default column properties

nicegui/functions/javascript.py

@@ -8,7 +8,7 @@ def run_javascript(code: str, *, timeout: float = 1.0) -> AwaitableResponse:
     This function runs arbitrary JavaScript code on a page that is executed in the browser.
     The client must be connected before this function is called.
     To access a client-side Vue component or HTML element by ID,
-    use the JavaScript functions `getElement()` or `getHtmlElement()`.
+    use the JavaScript functions `getElement()` or `getHtmlElement()` (*added in version 2.9.0*).
 
     If the function is awaited, the result of the JavaScript code is returned.
     Otherwise, the JavaScript code is executed without waiting for a response.

nicegui/functions/navigate.py

@@ -10,6 +10,8 @@ class Navigate:
     """Navigation functions
 
     These functions allow you to navigate within the browser history and to external URLs.
+
+    *Added in version 2.0.0*
     """
 
     def back(self) -> None:

nicegui/functions/style.py

@@ -18,6 +18,8 @@ def add_css(content: Union[str, Path]) -> None:
 
     This function can be used to add CSS style definitions to the head of the HTML page.
 
+    *Added in version 2.0.0*
+
     :param content: CSS content (string or file path)
     """
     if helpers.is_file(content):
@@ -30,6 +32,8 @@ def add_scss(content: Union[str, Path], *, indented: bool = False) -> None:
 
     This function can be used to add SCSS style definitions to the head of the HTML page.
 
+    *Added in version 2.0.0*
+
     :param content: SCSS content (string or file path)
     :param indented: whether the content is indented (SASS) or not (SCSS) (default: `False`)
     """
@@ -46,6 +50,8 @@ def add_sass(content: Union[str, Path]) -> None:
 
     This function can be used to add SASS style definitions to the head of the HTML page.
 
+    *Added in version 2.0.0*
+
     :param content: SASS content (string or file path)
     """
     add_scss(content, indented=True)

nicegui/page_layout.py

@@ -275,7 +275,7 @@ def __init__(self,
         :param position: position on the screen (default: "bottom-right")
         :param x_offset: horizontal offset (default: 0)
         :param y_offset: vertical offset (default: 0)
-        :param expand: whether to fully expand instead of shrinking to fit the content (default: ``False``)
+        :param expand: whether to fully expand instead of shrinking to fit the content (default: ``False``, *added in version 2.1.0*)
         """
         super().__init__('q-page-sticky')
         self._props['position'] = position

nicegui/ui_run.py

@@ -89,8 +89,8 @@ def run(*,
     :param language: language for Quasar elements (default: `'en-US'`)
     :param binding_refresh_interval: time between binding updates (default: `0.1` seconds, bigger is more CPU friendly)
     :param reconnect_timeout: maximum time the server waits for the browser to reconnect (default: 3.0 seconds)
-    :param message_history_length: maximum number of messages that will be stored and resent after a connection interruption (default: 1000, use 0 to disable)
-    :param fastapi_docs: enable FastAPI's automatic documentation with Swagger UI, ReDoc, and OpenAPI JSON (bool or dictionary as described `here <https://fastapi.tiangolo.com/tutorial/metadata/>`_, default: `False`)
+    :param message_history_length: maximum number of messages that will be stored and resent after a connection interruption (default: 1000, use 0 to disable, *added in version 2.9.0*)
+    :param fastapi_docs: enable FastAPI's automatic documentation with Swagger UI, ReDoc, and OpenAPI JSON (bool or dictionary as described `here <https://fastapi.tiangolo.com/tutorial/metadata/>`_, default: `False`, *updated in version 2.9.0*)
     :param show: automatically open the UI in a browser tab (default: `True`)
     :param on_air: tech preview: `allows temporary remote access <https://nicegui.io/documentation/section_configuration_deployment#nicegui_on_air>`_ if set to `True` (default: disabled)
     :param native: open the UI in a native window of size 800x600 (default: `False`, deactivates `show`, automatically finds an open port)

nicegui/ui_run_with.py

@@ -39,7 +39,7 @@ def run_with(
     :param language: language for Quasar elements (default: `'en-US'`)
     :param binding_refresh_interval: time between binding updates (default: `0.1` seconds, bigger is more CPU friendly)
     :param reconnect_timeout: maximum time the server waits for the browser to reconnect (default: 3.0 seconds)
-    :param message_history_length: maximum number of messages that will be stored and resent after a connection interruption (default: 1000, use 0 to disable)
+    :param message_history_length: maximum number of messages that will be stored and resent after a connection interruption (default: 1000, use 0 to disable, *added in version 2.9.0*)
     :param mount_path: mount NiceGUI at this path (default: `'/'`)
     :param on_air: tech preview: `allows temporary remote access <https://nicegui.io/documentation/section_configuration_deployment#nicegui_on_air>`_ if set to `True` (default: disabled)
     :param tailwind: whether to use Tailwind CSS (experimental, default: `True`)

website/documentation/content/html_documentation.py

@@ -21,6 +21,8 @@ def demo_inline() -> None:
 
     Like with any other element, you can add classes, style, props, tooltips and events.
     One convenience is that the keyword arguments are automatically added to the element's `props` dictionary.
+
+    *Added in version 2.5.0*
 ''')
 def other_html_elements():
     from nicegui import html, ui

website/documentation/content/interactive_image_documentation.py

@@ -66,7 +66,8 @@ def loaded_event():
     You can show crosshairs by passing `cross=True`.
     You can also change the color of the crosshairs by passing a color string.
 
-    Alternatively, you can use the `add_slot` method to add a custom "cross" slot with your own SVG template.
+    *Since version 2.4.0:*
+    You can use the `add_slot` method to add a custom "cross" slot with your own SVG template.
     The `props.x` and `props.y` variables will be available in the template, representing the crosshair position.
 ''')
 def crosshairs():

website/documentation/content/section_text_elements.py

@@ -28,6 +28,8 @@
 
     Like with any other element, you can add classes, style, props, tooltips and events.
     One convenience is that the keyword arguments are automatically added to the element's `props` dictionary.
+
+    *Added in version 2.5.0*
 ''')
 def other_html_elements():
     from nicegui import html, ui

website/documentation/content/timer_documentation.py

@@ -47,6 +47,8 @@ def start_immediately_demo():
 @doc.demo('Global app timer', '''
     While `ui.timer` is kind of a UI element that runs in the context of the current page,
     you can also use the global `app.timer` for UI-independent timers.
+
+    *Added in version 2.9.0*
 ''')
 def app_timer_demo():
     from nicegui import app