dara-components 1.8.5__py3-none-any.whl → 1.22.1__py3-none-any.whl

dara/components/common/table.py

@@ -15,22 +15,23 @@ See the License for the specific language governing permissions and
 limitations under the License.
 """
 
-from datetime import datetime
+from collections.abc import Sequence
 from enum import Enum
-from typing import List, Literal, Optional, Union
+from typing import Any, ClassVar, Literal
 
-from pydantic import BaseModel, validator
+from fastapi.encoders import jsonable_encoder
+from pandas import DataFrame
+from pydantic import ConfigDict, Field, SerializerFunctionWrapHandler, ValidationInfo, field_serializer, field_validator
 
 from dara.components.common.base_component import ContentComponent
-from dara.components.common.time_utils import coerce_to_timemilli
 from dara.core.base_definitions import Action
-from dara.core.definitions import ComponentInstance
+from dara.core.base_definitions import DaraBaseModel as BaseModel
 from dara.core.interactivity import (
-    AnyDataVariable,
-    NonDataVariable,
-    UrlVariable,
+    AnyVariable,
+    ClientVariable,
     Variable,
 )
+from dara.core.logging import dev_logger
 
 
 class TableFormatterType(Enum):
@@ -47,6 +48,9 @@ class TableFormatterType(Enum):
     THRESHOLD = 'threshold'
 
 
+TFormatterType = type[TableFormatterType]
+
+
 class TableFormatterCompareCondition(Enum):
     EQUAL = 'equal'
 
@@ -58,6 +62,9 @@ class TableFilter(Enum):
     DATETIME = 'datetime'
 
 
+TFilterType = type[TableFilter]
+
+
 class Column(BaseModel):
     """
     Internal representation of a Table column, required for serialization to work correctly
@@ -261,7 +268,7 @@ class Column(BaseModel):
 
     from pandas import DataFrame
     from dara.components.common import Table
-    from dara.core import DataVariable
+    from dara.core import ServerVariable
 
     Table.column(
         col_id='col1',
@@ -285,7 +292,7 @@ class Column(BaseModel):
         .
         .
     ])
-    data_var = DataVariable(data)
+    data_var = ServerVariable(data)
 
     ```
 
@@ -373,28 +380,35 @@ class Column(BaseModel):
     :param type: Optional prop to specify type of column, used to determine e.g. filter type. If not specified, inferred from formatters
     """
 
-    align: Optional[str] = None
+    align: str | None = None
     col_id: str
-    unique_items: Optional[List[str]] = None
-    filter: Optional[TableFilter] = None
-    formatter: Optional[dict] = None
-    label: Optional[str] = None
-    sticky: Optional[str] = None
-    tooltip: Optional[str] = None
-    width: Optional[Union[int, str]] = None
-    type: Optional[Union[Literal['number'], Literal['string'], Literal['datetime']]] = None
-
-    class Config:
-        use_enum_values = True
-
-    @validator('label', always=True)
+    unique_items: list[str] | None = None
+    filter: TableFilter | None = None
+    formatter: dict | None = None
+    label: str | None = Field(default=None, validate_default=True)  # mimics always=True in pydantic v1
+    sticky: str | None = None
+    tooltip: str | None = None
+    width: int | str | None = None
+    type: (
+        Literal['number']
+        | Literal['string']
+        | Literal['datetime']
+        | Literal['datetime64[ns]']
+        | Literal['datetime64[ms]']
+        | Literal['datetime64[s]']
+        | None
+    ) = None
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    @field_validator('label')
     @classmethod
-    def validate_label(cls, value, values):
+    def validate_label(cls, value, info: ValidationInfo):
         if value is None:
-            return values.get('col_id')
+            return info.data.get('col_id')
         return value
 
-    @validator('formatter')
+    @field_validator('formatter')
     @classmethod
     def vaildate_formatter_dict(cls, formatter):
         """
@@ -405,13 +419,12 @@ class Column(BaseModel):
         formatter_type = formatter.get('type')
         if formatter_type not in TableFormatterType:
             raise ValueError(
-                f"Invalid formatter type: {formatter.get('type')}, accepted values {list(TableFormatterType)}"
+                f'Invalid formatter type: {formatter.get("type")}, accepted values {list(TableFormatterType)}'
             )
         if formatter_type in (TableFormatterType.NUMBER, TableFormatterType.PERCENT):
             precision = formatter.get('precision')
-            if precision is not None:
-                if not isinstance(precision, int) or precision <= 0:
-                    raise ValueError(f'Invalid precision value: {precision}, must be positive integer')
+            if precision is not None and (not isinstance(precision, int) or precision <= 0):
+                raise ValueError(f'Invalid precision value: {precision}, must be positive integer')
         elif formatter_type == TableFormatterType.NUMBER_INTL:
             locales = formatter.get('locales')
             if not isinstance(locales, str) or not (
@@ -445,9 +458,9 @@ class Column(BaseModel):
                     )
                 lower_bound = threshold.get('bounds')[0]
                 upper_bound = threshold.get('bounds')[1]
-                if not (isinstance(lower_bound, int) or isinstance(lower_bound, float)):
+                if not (isinstance(lower_bound, (int, float))):
                     raise ValueError(f'Invalid bound type: {lower_bound}, must be int or float')
-                if not (isinstance(upper_bound, int) or isinstance(upper_bound, float)):
+                if not (isinstance(upper_bound, (int, float))):
                     raise ValueError(f'Invalid bound type: {upper_bound}, must be int or float')
         elif formatter_type == TableFormatterType.BADGE:
             badges = formatter.get('badges')
@@ -464,11 +477,11 @@ class Column(BaseModel):
                     )
                 if not isinstance(badges[badge].get('color'), str):
                     raise ValueError(
-                        f"Invalid color: {badges[badge].get('color')} for badge: {badges[badge]}, must be a string"
+                        f'Invalid color: {badges[badge].get("color")} for badge: {badges[badge]}, must be a string'
                     )
         return formatter
 
-    @validator('sticky')
+    @field_validator('sticky')
     @classmethod
     def validate_sticky(cls, sticky):
         """
@@ -478,15 +491,15 @@ class Column(BaseModel):
             raise ValueError(f'Invalid sticky value: {sticky}, accepted values: left, right')
         return sticky
 
-    @validator('filter')
+    @field_validator('filter')
     @classmethod
-    def validate_unique_items(cls, filter, values):
+    def validate_unique_items(cls, filter, info: ValidationInfo):
         """
         Validate that for categorical filters unique_items is provided
         """
         if filter == 'categorical':
-            unique_items = values.get('unique_items')
-            col_id = values.get('col_id')
+            unique_items = info.data.get('unique_items')
+            col_id = info.data.get('col_id')
             if unique_items is None:
                 raise ValueError(
                     f'Invalid unique_items: {col_id} has categorical filter, it must have unique_items defined'
@@ -499,10 +512,113 @@ class Table(ContentComponent):
     ![Table](../../../../docs/packages/dara-components/common/assets/Table.png)
 
     A Table Component for drawing a simple table into a document. Table's can be created by passing data
-    as a DataVariable or a DerivedDataVariable. Columns can be passed as lists of dicts, where the col_id
-    of the cols must match the column name in the dataframe. Alternatively they can be Variables/DerivedVariables,
-    and if left undefined it will be inferred from the data passed.
+    as a ServerVariable, DerivedVariable, DataFrame or correctly formatted raw tabular data.
+
+    For simple client-side tables, you can directly pass data as list of records, where each record is a dict with string keys.
+
+    ```python
+    from dara.components.common import Table
+
+    Table(
+        data=[
+            {
+                'col1': 'a',
+                'col2': 1,
+                'col3': 'F',
+                'col4': '1990-02-12T00:00:00.000Z',
+            },
+            {
+                'col1': 'b',
+                'col2': 2,
+                'col3': 'M',
+                'col4': '1991-02-12T00:00:00.000Z',
+            },
+        ]
+    )
+    ```
+
+    You can also pass a DataFrame directly:
+
+    ```python
+    import pandas
+    from dara.components.common import Table
+
+    data = pandas.DataFrame([
+        {
+            'col1': 'a',
+            'col2': 1,
+            'col3': 'F',
+            'col4': '1990-02-12T00:00:00.000Z',
+        },
+        {
+            'col1': 'b',
+            'col2': 2,
+            'col3': 'M',
+            'col4': '1991-02-12T00:00:00.000Z',
+        },
+    ])
 
+    Table(data=data)
+    ```
+
+    When working with larger datasets, it is recommended to use a ServerVariable or DerivedVariable to avoid sending the entire dataset to the client.
+    They have built-in server-side filtering and pagination which is utilized by the Table component and integrated into its UI. They both support customization
+    of the filtering and pagination behavior, respectively via a custom `ServerVariable.backend` or a custom `DerivedVariable.filter_resolver`.
+
+    ServerVariables are ideal for static or mutable dataset that can be shared among users or specific to a user (with `scope='user'`) via e.g. data upload.
+    If possible, avoid recreating ServerVariables within e.g. `py_components`, as each instance will store a new copy of the data in memory.
+
+    ```python
+    from dara.core import ServerVariable
+    from dara.components.common import Table
+
+    data = ServerVariable(pandas.DataFrame([
+        {
+            'col1': 'a',
+            'col2': 1,
+            'col3': 'F',
+            'col4': '1990-02-12T00:00:00.000Z',
+        },
+        {
+            'col1': 'b',
+            'col2': 2,
+            'col3': 'M',
+            'col4': '1991-02-12T00:00:00.000Z',
+        },
+    ]))
+
+    Table(data=data)
+    ```
+
+    DerivedVariables allow you to create or resolve datasets on the fly, e.g. depending on user input.
+
+    ```python
+    import pandas
+    from dara.core import DerivedVariable
+    from dara.components.common import Table
+
+    async def create_data(user_input: str, row_count: int):
+        df = pandas.DataFrame()
+        for i in range(row_count):
+            df = df.append({
+                'col1': user_input,
+                'col2': i,
+                'col3': 'F',
+                'col4': '1990-02-12T00:00:00.000Z',
+            }, ignore_index=True)
+        return df
+
+    user_input = Variable('a')
+    row_count = Variable(10)
+
+    data = DerivedVariable(create_data, variables=[user_input, row_count])
+
+    Table(data=data)
+    ```
+
+    By default, the `Table` component will display all columns of the dataset. You can choose to customize which columns to display, their order, types and more.
+    Columns can be passed as lists of dicts, where the col_id of the cols must match the column name in the dataframe. Alternatively they can be Variables/DerivedVariables,
+    and if left undefined it will be inferred from the data passed.
     The list of columns can be a mix of dicts and strings. If a string is passed then it will be used as
     the col_id and label for the column whereas, passing a dict allows more control over the options. The
     available options for columns are as follows (see Column class for more detail):
@@ -520,9 +636,9 @@ class Table(ContentComponent):
 
     from pandas import DataFrame
     from dara.components.common import Table
-    from dara.core import DataVariable
+    from dara.core import ServerVariable
 
-    data = DataVariable(
+    data = ServerVariable(
         DataFrame([
             {
                 'col1': 1,
@@ -549,9 +665,9 @@ class Table(ContentComponent):
 
     from pandas import DataFrame
     from dara.components.common import Table
-    from dara.core import DataVariable
+    from dara.core import ServerVariable
 
-    data = DataVariable(
+    data = ServerVariable(
         DataFrame([
             {
                 'col1': 1,
@@ -590,9 +706,9 @@ class Table(ContentComponent):
 
     from pandas import DataFrame
     from dara.components.common import Table
-    from dara.core import DataVariable, Variable
+    from dara.core import ServerVariable, Variable
 
-    data = DataVariable(
+    data = ServerVariable(
         DataFrame([
             {
                 'col1': 1,
@@ -626,9 +742,9 @@ class Table(ContentComponent):
 
     from pandas import DataFrame
     from dara.components.common import Table
-    from dara.core import DataVariable
+    from dara.core import ServerVariable
 
-    data = DataVariable(
+    data = ServerVariable(
         DataFrame([
             {
                 'col1': 1,
@@ -659,7 +775,7 @@ class Table(ContentComponent):
 
     import pandas
     from dara.components.common import Table
-    from dara.core import DataVariable
+    from dara.core import ServerVariable
 
     data = [{
         'age': 27,
@@ -672,7 +788,7 @@ class Table(ContentComponent):
     }]
     df = pandas.DataFrame(data, columns=['age', 'name', 'surname'])
     df.reset_index()
-    Table(data=DataVariable(df), columns=[{'col_id': 'age', 'label': 'Age'}, 'index'])
+    Table(data=ServerVariable(df), columns=[{'col_id': 'age', 'label': 'Age'}, 'index'])
 
     ```
 
@@ -681,9 +797,9 @@ class Table(ContentComponent):
     ```python
     from pandas import DataFrame
     from dara.components.common import Table
-    from dara.core import DataVariable
+    from dara.core import ServerVariable
 
-    data = DataVariable(
+    data = ServerVariable(
         DataFrame(
             [
                 {
@@ -720,42 +836,77 @@ class Table(ContentComponent):
     ```
 
     :param columns: The table's columns, this can be a list, a Variable/DerivedVariable or if left undefined it will be inferred from the data
-    :param data: The table's data, must be a DataVariable or DerivedDataVariable
+    :param data: The table's data, can be a list of records or a Variable resolving to a list of records
     :param multi_select: Whether to allow selection of multiple rows, works with onclick_row and defaults to False
     :param show_checkboxes: Whether to show or hide checkboxes column when onclick_row is set. Defaults to True
     :param onclick_row: An action handler for when a row is clicked on the table
+    :param onselect_row: An action handler for when a row is selected via the checkbox column
     :param selected_indices: Optional variable to store the selected rows indices, must be a list of numbers. Note that these indices are
     the sequential indices of the rows as accepted by `DataFrame.iloc`, not the `row.index` value. If you would like the selection to persist over
-    page reloads, you must set `persist_value=True` on the variable.
+    page reloads, you must use a `BrowserStore` on a `Variable`.
     :param search_columns: Optional list defining the columns to be searched, only the columns passed are searchable
     :param searchable: Boolean, if True table can be searched via Input and will only render matching rows
+    :param include_index: Boolean, if True the table will render the index column(s), defaults to True
     :param max_rows: if specified, table height will be fixed to accommodate the specified number of rows
+    :param suppress_click_events_for_selection: Whether to suppress click events for clicks in select boxes. Defaults to False
     """
 
-    columns: Optional[Union[List[Union[Column, dict, str]], NonDataVariable]]
-    data: AnyDataVariable
+    model_config = ConfigDict(ser_json_timedelta='float', use_enum_values=True, arbitrary_types_allowed=True)
+
+    columns: Sequence[Column | dict | str] | ClientVariable | None = None
+    data: AnyVariable | DataFrame | list
     multi_select: bool = False
     show_checkboxes: bool = True
-    onclick_row: Optional[Action] = None
-    selected_indices: Optional[Union[List[int], UrlVariable, Variable]] = None
-    search_columns: Optional[List[str]] = None
+    onclick_row: Action | None = None
+    onselect_row: Action | None = None
+    selected_indices: list[int] | Variable | None = None
+    search_columns: list[str] | None = None
     searchable: bool = False
-    max_rows: Optional[int] = None
-    children: List[ComponentInstance] = []
+    include_index: bool = True
+    max_rows: int | None = None
+    suppress_click_events_for_selection: bool | None = False
 
-    TableFormatterType = TableFormatterType
-    TableFilter = TableFilter
+    TableFormatterType: ClassVar[TFormatterType] = TableFormatterType
+    TableFilter: ClassVar[TFilterType] = TableFilter
+
+    @field_validator('data')
+    @classmethod
+    def validate_data(cls, data):
+        # variables are fine, can't validate here
+        if isinstance(data, (DataFrame, AnyVariable)):
+            return data
+        if isinstance(data, list):
+            if not all(isinstance(item, dict) and all(isinstance(key, str) for key in item) for item in data):
+                raise ValueError(f'Invalid data passed to Table: {data}, expected a list of dicts with string keys')
+            return data
+        raise ValueError(f'Invalid data passed to Table: {type(data)}, expected a DataFrame or a variable')
+
+    @field_serializer('data', mode='wrap')
+    def serialize_field(self, value: Any, nxt: SerializerFunctionWrapHandler):
+        if isinstance(value, AnyVariable):
+            return nxt(value)
+
+        from dara.core.internal.encoder_registry import get_jsonable_encoder
+
+        try:
+            if isinstance(value, DataFrame):
+                value = value.to_dict(orient='records')
+            return jsonable_encoder(value, custom_encoder=get_jsonable_encoder())
+        except Exception as e:
+            dev_logger.error(
+                'Error serializing raw data in Table, falling back to default serialization.'
+                'Alternatively, you can provide a JSON-serializable dictionary in the "records format", i.e. `[{"col_a": 1}, {"col_a": 2}]`.',
+                error=e,
+            )
 
-    class Config:
-        json_encoders = {datetime: coerce_to_timemilli}
-        use_enum_values = True
+        return nxt(value)
 
-    @validator('columns')
+    @field_validator('columns')
     @classmethod
     def validate_columns(cls, columns):
         if columns is None:
             return None
-        if isinstance(columns, List):
+        if isinstance(columns, list):
             cols = []
             for col in columns:
                 if isinstance(col, Column):
@@ -765,14 +916,14 @@ class Table(ContentComponent):
                 else:
                     cols.append(Column(**col))
             return cols
-        elif isinstance(columns, NonDataVariable):
+        elif isinstance(columns, ClientVariable):
             return columns
         else:
             raise ValueError(f'Invalid list passed to Table columns: {columns}, expected a list')
 
-    def add_column(self, col: Union[str, dict, Column]):
+    def add_column(self, col: str | dict | Column):
         """Adds a new column to the data"""
-        if not isinstance(self.columns, List):
+        if not isinstance(self.columns, list):
             raise ValueError('You cannot add_columns to a Variable type columns or if they are undefined')
         if isinstance(col, str):
             self.columns.append(Column(col_id=col))

dara/components/common/text.py

@@ -15,12 +15,10 @@ See the License for the specific language governing permissions and
 limitations under the License.
 """
 
-from typing import Union
-
-from pydantic import validator
+from pydantic import field_validator
 
 from dara.components.common.base_component import ContentComponent
-from dara.core.interactivity import NonDataVariable
+from dara.core.interactivity import ClientVariable
 
 
 class Text(ContentComponent):
@@ -53,16 +51,16 @@ class Text(ContentComponent):
     :param formatted: Whether to display the text with existing formatting intact or not, default False
     """
 
-    text: Union[str, NonDataVariable]
-    align: str = 'left'
+    text: str | ClientVariable
+    align: str | None = 'left'  # type: ignore # this is actually textAlign not align-items
     formatted: bool = False
 
-    @validator('text')
+    @field_validator('text')
     @classmethod
     def only_strings(cls, value: str):
-        if not isinstance(value, (str, NonDataVariable)):
+        if not isinstance(value, (str, ClientVariable)):
             raise ValueError(f'Invalid text passed to Text: {value}, expected a string')
         return value
 
-    def __init__(self, text: Union[str, NonDataVariable], **kwargs):
+    def __init__(self, text: str | ClientVariable, **kwargs):
         super().__init__(text=text, **kwargs)

dara/components/common/textarea.py

@@ -15,7 +15,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 """
 
-from typing import Any, Literal, Optional
+from typing import Any, Literal
 
 from dara.components.common.base_component import FormComponent
 from dara.core.base_definitions import Action
@@ -33,12 +33,12 @@ class Textarea(FormComponent):
     A Textarea component is created via:
 
     ```python
-
     from dara.core import Variable
     from dara.components.common import Textarea
 
-    Textarea(value=Variable('initial textarea content'))
+    value_var = Variable('initial textarea content')
 
+    Textarea(value=value_var)
     ```
 
     :param autofocus: Boolean, if True then then initially render with the cursor in the component
@@ -49,7 +49,7 @@ class Textarea(FormComponent):
     """
 
     autofocus: bool = False
-    value: Optional[Variable[Any]] = None
-    onchange: Optional[Action] = None
-    id: Optional[str] = None
-    resize: Optional[Literal['none', 'both', 'horizontal', 'vertical', 'block', 'inline']] = None
+    value: Variable[Any] | None = None
+    onchange: Action | None = None
+    id: str | None = None
+    resize: Literal['none', 'both', 'horizontal', 'vertical', 'block', 'inline'] | None = None

dara/components/common/time_utils.py

@@ -16,7 +16,6 @@ limitations under the License.
 """
 
 import datetime
-from typing import Union
 
 import numpy
 
@@ -37,11 +36,9 @@ def date_to_datetime(d: datetime.date, hh=23, mm=59, ss=59) -> datetime.datetime
     return datetime.datetime(d.year, d.month, d.day, hh, mm, ss)
 
 
-def coerce_to_timemilli(t: Union[int, float, datetime.date, datetime.datetime]) -> float:
+def coerce_to_timemilli(t: int | float | datetime.date | datetime.datetime) -> float:
     """Convert any of int/float/date/datetime into a timemilli."""
-    if isinstance(t, int) or isinstance(t, numpy.int_):
-        return float(t)
-    elif isinstance(t, float) or isinstance(t, numpy.float_):
+    if isinstance(t, (int, numpy.signedinteger, float, numpy.floating)):
         return float(t)
     # The order matters - datetime.datetime is a subclass of the datetime.date
     elif isinstance(t, datetime.datetime):

dara/components/common/tooltip.py

@@ -15,8 +15,6 @@ See the License for the specific language governing permissions and
 limitations under the License.
 """
 
-from typing import Union
-
 from dara.components.common.base_component import ModifierComponent
 from dara.components.common.stack import Stack
 from dara.core.definitions import ComponentInstance
@@ -74,17 +72,17 @@ class Tooltip(ModifierComponent):
     :param styling: Defines the style of the tooltip, can be 'default' or 'error'
     """
 
-    content: Union[str, ComponentInstance, Variable[str], DerivedVariable[str]]
+    content: str | ComponentInstance | Variable[str] | DerivedVariable[str]
     placement: str = 'auto'
     styling: str = 'default'
 
     def __init__(
         self,
-        *components: ComponentInstance,
-        content: Union[str, ComponentInstance, Variable[str], DerivedVariable[str]],
+        *components: ComponentInstance | None,
+        content: str | ComponentInstance | Variable[str] | DerivedVariable[str],
         placement: str = 'auto',
         styling: str = 'default',
-        **kwargs
+        **kwargs,
     ):
         # Unless there's one component and it's Stack, wrap components in Stack
         if not (len(components) == 1 and isinstance(components[0], Stack)):