Skip to main content

configuration

Configuration​

from dara.core.configuration import Configuration

class Configuration(BaseModel)

Definition of the main framework configuration

Attributes​

  • auth_config: BaseAuthConfig
  • registry_lookup: CustomRegistryLookup
  • actions: List[ActionDef]
  • endpoint_configurations: List[EndpointConfiguration]
  • components: List[ComponentTypeAnnotation]
  • context_components: List[ComponentInstance]
  • enable_devtools: bool
  • module_dependencies: Dict[str, str]
  • live_reload: bool
  • powered_by_causalens: bool
  • pages: Dict[str, Page]
  • routes: Set[ApiRoute]
  • scheduled_jobs: List[Tuple[Union[ScheduledJob, ScheduledJobFactory], Callable, Optional[List[Any]]]]
  • startup_functions: List[Callable]
  • static_folders: List[str]
  • static_files_dir: str
  • package_tag_processors: List[Callable[[Dict[str, List[str]]], Dict[str, List[str]]]]
  • template_extra_js: str
  • task_module: Optional[str]
  • template: str
  • template_renderers: Dict[str, Callable[Template]]
  • theme: Union[BaseTheme, str]
  • title: str
  • ws_handlers: Dict[str, Callable[[str, Any], Any]]
  • encoders: Dict[Type[Any], Encoder]
  • middlewares: List[Middleware]

Methods​

get_package_map​

def get_package_map() -> Dict[str, str]

Get a map of python package names to js package names, based on currently registered components, actions etc.

ConfigurationBuilder​

from dara.core.configuration import ConfigurationBuilder

class ConfigurationBuilder()

The ConfigurationBuilder class lets you build a Configuration object up piece by piece using helper methods that

aid setup and point users in the right direction.

Arguments:

  • title: The title of the application as appears in the browser tab
  • static_files_dir: The directory to serve static files from
  • task_module: The path to the module to load tasks from
  • enable_devtools: Whether to enable the devtools in the application
  • template: The template to use for the sidebar of the application

Attributes​

  • auth_config: BaseAuthConfig
  • registry_lookup: CustomRegistryLookup
  • _actions: List[ActionDef]
  • _components: List[ComponentTypeAnnotation]
  • _module_dependencies: Dict[str, str]
  • _errors: List[str]
  • enable_devtools: bool
  • live_reload: bool
  • _pages: Dict[str, Page]
  • _template_renderers: Dict[str, Callable[Template]]
  • _endpoint_configurations: List[EndpointConfiguration]
  • _static_folders: List[str]
  • _package_tags_processors: List[Callable[[Dict[str, List[str]]], Dict[str, List[str]]]]
  • _template_extra_js: str
  • _custom_ws_handlers: Dict[str, Callable[[str, Any], Any]]
  • _custom_encoders: Dict[Type[Any], Encoder]
  • _middlewares: List[Middleware]
  • routes: Set[ApiRoute]
  • static_files_dir: str
  • scheduled_jobs: List[Tuple[Union[ScheduledJob, ScheduledJobFactory], Callable, Optional[List[Any]]]]
  • startup_functions: List[Callable]
  • context_components: List[ComponentInstance]
  • task_module: Optional[str]
  • template: str
  • theme: BaseTheme
  • title: str

Methods​

add_action​

def add_action(action: Type[ActionImpl], local: bool = False)

Register an Action with the application.

For example the below would explicitly import the UpdateVariable action from dara.core.

add_action(UpdateVariable)

Note that in most cases explicitly registering a action is not necessary in most cases for non-local actionts. Actions are auto-discovered based on imports within your application.

Arguments:

  • action: ActionImpl-subclass definition
  • local: whether the action is a local one. For local actions js_module is not required, as their location is defined via dara.config.json

add_endpoint​

def add_endpoint(endpoint: ApiRoute)

Register an API endpoint in the application

add_context_component​

def add_context_component(component: ComponentInstance)

Add a ContextComponent to the application.

Context components are rendered recursively in order around the application. E.g.

config.add_context_component(Component1)
config.add_context_component(Component2)

# Results in
<Component1>
    <Component2>
        <Page>
    </Component2>
</Component1>

This can be used by packages outside of core to provide global functionality to components on the page and hook into other application contexts, e.g. the router.

Arguments:

  • component: component instance

add_component​

def add_component(component: Type[ComponentInstance], local: bool = False)

Register a Component with the application.

For example the below would import the Menu component from dara.core.

add_component(Menu)

Note that in most cases explicitly registering a component is not necessary in most cases for non-local components. Components are auto-discovered based on imports within your application.

Arguments:

  • component: ComponentInstance-subclass definition
  • local: whether the component is a local one. For local components js_module is not required, as their location is defined via dara.config.json

add_module_dependency​

def add_module_dependency(py_module: str, js_module: str)

Explicitly add a module to the application. This is useful to ensure that a given module's assets are included in the build even if no components from it are used explicitly in the application.

For example, when building a plugin that registers custom JS (e.g. in the form of a context component) that relies on the JS side of @darajs/components, you could explicitly add the module in your plugin:

def my_plugin(config: ConfigurationBuilder):
    config.add_module('dara.components', '@darajs/components')

add_configuration​

def add_configuration(config: EndpointConfiguration)

Register an EndpointConfiguration instance with the application.

add_ws_handler​

def add_ws_handler(kind: str, handler: Callable[[str, Any], Any])

Register a custom websocket handler, which will be called when a message of a given kind is received.

Example:

# Received message
{
    "type": "custom",
    "message": {
        "kind": "my_custom_kind",
        "data": "some arbitrary data"
    }
}

# Handler
config.add_ws_handler(kind='my_custom_kind', handler=my_custom_handler)

def my_custom_handler(channel: str, data: Any):
    print(f'Received message on channel {channel} with data {data}')
    return 'some response'

# Message sent back
{
    "type": "custom",
    "message": {
        "kind": "my_custom_kind",
        "data": "some response"
    }
}

add_encoder​

def add_encoder(typ: Type[EncoderType], serialize: Callable[[EncoderType],
                                                            Any],
                deserialize: Callable[[Any], EncoderType])

Register a custom encoder, which serialize and deserialize the type

Arguments:

  • typ: The type of object
  • serialize: The handler to serialize the object to basic python type
  • deserialize: The handler to deserialize the object Example: import numpy config.add_encoder(typ=np.array, serialize=lambda x: x.tolist(), deserialize=lambda y: np.array(y))

add_package_tags_processor​

def add_package_tags_processor(processor: Callable[[Dict[str, List[str]]],
                                                   Dict[str, List[str]]])

Append a package tag processor. This is a function that takes a dictionary of package names to lists of script/link tags included when running in the UMD mode.

All processors are called in order, and the output of each processor is passed to the next one.

add_page​

def add_page(name: str,
             content: Union[ComponentInstanceType,
                            Type[CallableClassComponent], str],
             icon: Optional[str] = None,
             route: Optional[str] = None,
             include_in_menu: Optional[bool] = True,
             reset_vars_on_load: Optional[List[AnyVariable]] = [],
             on_load: Optional[Action] = None)

Add a new page to the layout of the platform. Switching between pages relies on the template implementing a

router for switching between the pages. The default template will do this automatically, but refer to the template documentation for more details on this.

Arguments:

  • name: the name of the page
  • content: the content for the page
  • icon: an optional icon for the page, see dara_core.css.get_icon for more detail
  • route: an optional url for the page, if not provided it's generated based on the page name
  • include_in_menu: an optional flag for not including the page in the main menu
  • on_load: optional action to execute upon visiting the page

add_template_renderer​

def add_template_renderer(name: str,
                          template_renderer: Callable[..., Template]) -> str

Add a new template renderer that can be selected by name as part of the configuration. By default calling this

function will update the template name to match automatically

Arguments:

  • name: the template name
  • template_renderer: the ComponentInstance to use for the template

add_registry_lookup​

def add_registry_lookup(registry_lookup: CustomRegistryLookup)

Register custom external registry lookup handlers, which will be called when a uid its not in the server registry

Example:

from dara.core import ConfigurationBuilder
config = ConfigurationBuilder()

def get_derived_variable(uid)-> DerivedVariableRegistryEntry:
    # return derived variable

def get_action(uid)-> Callable:
    # return action

config.add_registry_lookup(
            {
                'DerivedVariable': get_derived_variable,
                'Action Handler': get_action,
            }
        )

#### add\_middleware

```python
def add_middleware(middleware: Union[type, Callable], **options: Any)

Add a middleware to the application. The middleware can be a class or a callable.

set_theme​

def set_theme(main_theme: Optional[Union[ThemeDef, Literal['light'],
                                         Literal['dark']]] = None,
              base_theme: Optional[Union[Literal['light'],
                                         Literal['dark']]] = None)

Sets the color theme of the app. Takes ThemeDef models for the app, and reverts

to the default themes if they are not supplied.

Arguments:

  • main_theme: ThemeDef defining colors for the app, alternatively can be either 'light' or 'dark' to use default Dara colors

on_startup​

def on_startup(startup_function: Callable)

Adds a function to be run upon startup of a Dara app

Arguments:

  • startup_function: The function to be run