rafa-engineering 0.0.1b1__py3-none-any.whl

rafa/__init__.py

@@ -0,0 +1,463 @@
+"""
+Rafa - an application framework for engineering web applications.
+
+This module exports the public API for building applications. Names that were public
+earlier but are not in ``__all__`` any more still import, with a ``DeprecationWarning`` that
+names their new home (see ``_MOVED``).
+
+Examples
+--------
+>>> from rafa import (
+...     Application,
+...     Controller,
+...     Parametrization,
+...     Tab,
+...     Section,
+...     NumberField,
+...     TextField,
+...     OptionField,
+...     DateField,
+...     Table,
+...     DynamicArray,
+...     Lookup,
+...     view,
+...     action,
+...     HTMLResult,
+...     SuccessResult,
+...     format_html,
+... )
+>>>
+>>> class BeamParametrization(Parametrization):
+...     geometry = Tab("Geometry")
+...     geometry.width = NumberField(label="Width", default=0.3)
+...
+>>> class BeamController(Controller):
+...     label = "Beam"
+...     parametrization = BeamParametrization
+...
+...     @view("Overview")
+...     def overview(self, params, entity, **kwargs):
+...         # format_html escapes the values: a name like "<B1>" shows as typed
+...         return HTMLResult(
+...             format_html("<h2>{}</h2><p>Width: {} m</p>", entity.name, params.geometry.width)
+...         )
+...
+...     @action("Calculate")
+...     def calculate(self, params, entity, **kwargs):
+...         return SuccessResult(message="Done!")
+>>>
+>>> app = Application("sqlite:///app.db")
+>>> app.register(BeamController)
+"""
+
+import warnings as _warnings
+from importlib import import_module as _import_module
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _package_version
+from typing import Any as _Any
+
+# Actions
+from rafa.actions.decorators import action
+from rafa.actions.results import (
+    ActionResult,
+    ErrorResult,
+    FileResult,
+    OptimizationColumn,
+    OptimizationResult,
+    OptimizationResultElement,
+    SetParamsResult,
+    SuccessResult,
+)
+
+# Auth
+from rafa.auth import LOCAL_USER, User
+
+# Chats
+from rafa.chat.model import ChatMessage, ChatReply, ChatSuggestion, ChatTurn, Conversation
+
+# Core
+from rafa.core.access import Role
+from rafa.core.app_roles import AppRole, Permission
+from rafa.core.application import Application
+from rafa.core.calculations import CalculationLimitError
+from rafa.core.controller import CalculationContext, Controller
+from rafa.core.entity import Entity
+from rafa.core.jobs.model import Job
+from rafa.core.jobs.progress import CalculationStopped, Progress, ProgressUpdate
+from rafa.core.parametrization import Parametrization
+from rafa.core.params import MutableParams, Params
+from rafa.core.services import DeletedEntity
+from rafa.core.steps import StepCheck
+from rafa.core.storage import Storage, StorageLimitError
+from rafa.core.summary import SummaryItem, SummaryValue
+
+# Exceptions
+from rafa.exceptions import (
+    CircularRelationshipError,
+    ConflictError,
+    EditLockedError,
+    EntityNotFoundError,
+    InputsLockedError,
+    InputViolation,
+    InvalidParamsError,
+    JobNotFoundError,
+    MigrationError,
+    NotFoundError,
+    PermissionDeniedError,
+    RafaError,
+    StaleRevisionError,
+    UserError,
+)
+
+# Fields
+from rafa.fields.autocomplete import AutocompleteField
+from rafa.fields.base import Field, FieldError
+from rafa.fields.buttons import (
+    ActionButtonField,
+    DownloadButtonField,
+    OptimizationButtonField,
+    SetParamsButtonField,
+)
+from rafa.fields.chat import ChatField
+from rafa.fields.color import ColorField
+from rafa.fields.containers import DynamicArray, Table
+from rafa.fields.date import DateField
+from rafa.fields.file import FileField, FileValue, MultiFileField
+from rafa.fields.geo import GeoPointField, GeoPolygonField, GeoPolylineField, MapSelectField
+from rafa.fields.geometry_select import GeometryMultiSelectField, GeometrySelectField
+from rafa.fields.hidden import HiddenField
+from rafa.fields.layout import Image, LineBreak, Section, Step, Tab, Text
+from rafa.fields.multiselect import MultiSelectField
+from rafa.fields.numeric import IntegerField, NumberField
+from rafa.fields.options import BooleanField, OptionField, OptionListElement
+from rafa.fields.output import OutputField
+from rafa.fields.relationships import (
+    ChildEntityMultiSelectField,
+    ChildEntityOptionField,
+    EntityField,
+    EntityMultiSelectField,
+    SiblingEntityMultiSelectField,
+    SiblingEntityOptionField,
+)
+from rafa.fields.text import TextAreaField, TextField
+
+# Geo
+from rafa.geo import GeoPath, GeoPoint, rd_to_wgs, wgs_to_rd
+
+# Geometry (the objects are in rafa.geometry)
+from rafa.geometry.models import IFCResult
+from rafa.messages import Message, Messages, Status
+
+# Persistence
+from rafa.persistence.repository import CascadeMode
+
+# Themes
+from rafa.themes.model import Brand, FontFace, Fonts, Theme, ThemeError
+
+# Utils
+from rafa.utils.memoization import LRUCache, memoize
+from rafa.utils.migrations import MigrationRegistry, ParamsMigrator
+
+# Validation
+from rafa.validation.lookup import (
+    And,
+    Condition,
+    IsEqual,
+    IsFalse,
+    IsNotEqual,
+    IsNotNone,
+    IsTrue,
+    Lookup,
+    LookupExpression,
+    Not,
+    Or,
+    RowLookup,
+    resolve_lookup,
+)
+
+# Views
+from rafa.views.decorators import ViewLocation, ViewSpeed, metric, view
+from rafa.views.maps import (
+    GeoJSONResult,
+    MapCircle,
+    MapFeature,
+    MapLabel,
+    MapLegend,
+    MapLine,
+    MapPoint,
+    MapPolygon,
+    MapPolyline,
+    MapResult,
+    map_features,
+    require_mapyta,
+)
+from rafa.views.results import (
+    ALL,
+    DataItem,
+    DataResult,
+    ErrorViewResult,
+    GeometryResult,
+    HTMLResult,
+    ImageResult,
+    MetricResult,
+    PDFResult,
+    PlotlyResult,
+    TableCell,
+    TableColumn,
+    TableResult,
+    ViewResult,
+    WebResult,
+    math_html,
+)
+from rafa.views.results import (
+    DataViewResult as DataViewResult,  # older name of DataResult
+)
+from rafa.views.results import (
+    HTMLViewResult as HTMLViewResult,  # older name of HTMLResult
+)
+from rafa.views.safe_html import SafeHTML, format_html, html_escape
+
+try:
+    __version__ = _package_version("rafa-engineering")
+except PackageNotFoundError:  # pragma: no cover - only when running from an uninstalled tree
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "__version__",
+    # Core
+    "Application",
+    "User",
+    "LOCAL_USER",
+    "Role",
+    "Permission",
+    "AppRole",
+    "Controller",
+    "CalculationContext",
+    "StepCheck",
+    "Progress",
+    "ProgressUpdate",
+    "CalculationStopped",
+    "Messages",
+    "Message",
+    "Status",
+    "Job",
+    "Entity",
+    "Parametrization",
+    "Params",
+    "MutableParams",
+    "SummaryItem",
+    "SummaryValue",
+    "Storage",
+    # Exceptions
+    "RafaError",
+    "NotFoundError",
+    "EntityNotFoundError",
+    "ConflictError",
+    "StaleRevisionError",
+    "InputsLockedError",
+    "EditLockedError",
+    "JobNotFoundError",
+    "InvalidParamsError",
+    "CalculationLimitError",
+    "CircularRelationshipError",
+    "MigrationError",
+    "InputViolation",
+    "UserError",
+    "PermissionDeniedError",
+    "StorageLimitError",
+    # Fields - Base
+    "Field",
+    "FieldError",
+    # Fields - Numeric
+    "NumberField",
+    "IntegerField",
+    # Fields - Text
+    "TextField",
+    "TextAreaField",
+    # Fields - Date
+    "DateField",
+    # Fields - Options
+    "BooleanField",
+    "OptionField",
+    "OptionListElement",
+    # Fields - Containers
+    "Table",
+    "DynamicArray",
+    # Fields - Output
+    "OutputField",
+    # Fields - Multi-select
+    "MultiSelectField",
+    # Fields - Hidden
+    "HiddenField",
+    # Fields - Autocomplete
+    "AutocompleteField",
+    # Fields - Color
+    "ColorField",
+    # Fields - File
+    "FileField",
+    "FileValue",
+    "MultiFileField",
+    # Fields - Geo
+    "GeoPointField",
+    "GeoPolylineField",
+    "GeoPolygonField",
+    "MapSelectField",
+    # Fields - Buttons
+    "ActionButtonField",
+    "DownloadButtonField",
+    "SetParamsButtonField",
+    "OptimizationButtonField",
+    # Fields - Chat
+    "ChatField",
+    # Fields - Relationships
+    "EntityField",
+    "EntityMultiSelectField",
+    "ChildEntityOptionField",
+    "ChildEntityMultiSelectField",
+    "SiblingEntityOptionField",
+    "SiblingEntityMultiSelectField",
+    # Fields - Selection in a geometry view
+    "GeometrySelectField",
+    "GeometryMultiSelectField",
+    # Fields - Layout
+    "Tab",
+    "Step",
+    "Section",
+    "Text",
+    "LineBreak",
+    "Image",
+    # Validation
+    "Lookup",
+    "LookupExpression",
+    "RowLookup",
+    "resolve_lookup",
+    # Visibility operators
+    "And",
+    "Or",
+    "Not",
+    "IsTrue",
+    "IsFalse",
+    "IsNotNone",
+    "IsEqual",
+    "IsNotEqual",
+    "Condition",
+    # Geo
+    "GeoPoint",
+    "GeoPath",
+    "rd_to_wgs",
+    "wgs_to_rd",
+    # Persistence
+    "CascadeMode",
+    "DeletedEntity",
+    # Themes
+    "Theme",
+    "Brand",
+    "Fonts",
+    "FontFace",
+    "ThemeError",
+    # Utils - Memoization
+    "LRUCache",
+    "memoize",
+    # Utils - Migrations
+    "MigrationRegistry",
+    "ParamsMigrator",
+    # Actions
+    "action",
+    "ActionResult",
+    "SuccessResult",
+    "ErrorResult",
+    "FileResult",
+    "SetParamsResult",
+    "OptimizationResult",
+    "OptimizationResultElement",
+    "OptimizationColumn",
+    # Chats
+    "ChatMessage",
+    "ChatReply",
+    "ChatSuggestion",
+    "ChatTurn",
+    "Conversation",
+    # Views
+    "view",
+    "metric",
+    "ViewLocation",
+    "ViewSpeed",
+    "ViewResult",
+    "HTMLResult",
+    "math_html",
+    "format_html",
+    "html_escape",
+    "SafeHTML",
+    "DataResult",
+    "DataItem",
+    "ErrorViewResult",
+    "MetricResult",
+    "PlotlyResult",
+    "GeometryResult",
+    "IFCResult",
+    "TableResult",
+    "TableCell",
+    "TableColumn",
+    "ImageResult",
+    "PDFResult",
+    "WebResult",
+    "ALL",
+    # Views - Maps
+    "MapResult",
+    "GeoJSONResult",
+    "MapFeature",
+    "MapPoint",
+    "MapLine",
+    "MapPolyline",
+    "MapPolygon",
+    "MapCircle",
+    "MapLabel",
+    "MapLegend",
+    "map_features",
+    "require_mapyta",
+]
+
+# Names that left the top-level API: still importable, with a DeprecationWarning.
+# name -> (module, attribute)
+_MOVED: dict[str, tuple[str, str]] = {
+    # The protocol layer for other front ends; the web app does not use it
+    **{
+        name: ("rafa.ui", name)
+        for name in (
+            "UIContext",
+            "FormRenderer",
+            "ViewRenderer",
+            "ActionHandler",
+            "EntityBrowser",
+            "NotificationHandler",
+            "UIApplication",
+            "DefaultUIContext",
+        )
+    },
+    # Internals of conditions, caching, validation and the decorators
+    "LookupContext": ("rafa.validation.lookup", "LookupContext"),
+    "resolve_visibility": ("rafa.validation.lookup", "resolve_visibility"),
+    "evaluate_condition": ("rafa.validation.lookup", "evaluate_condition"),
+    "get_view_cache": ("rafa.utils.memoization", "get_view_cache"),
+    "ActionDefinition": ("rafa.actions", "ActionDefinition"),
+    "ViewDefinition": ("rafa.views", "ViewDefinition"),
+    "ValidationResult": ("rafa.fields", "ValidationResult"),
+    # Renamed: pydantic has a ValidationError too
+    "ValidationError": ("rafa", "FieldError"),
+}
+
+
+def __getattr__(name: str) -> _Any:
+    """Import a name that moved out of the top-level API, with a DeprecationWarning."""
+    if name not in _MOVED:
+        raise AttributeError(f"module 'rafa' has no attribute {name!r}")
+    module, attribute = _MOVED[name]
+    new = f"{module}.{attribute}" if module != "rafa" else f"rafa.{attribute}"
+    _warnings.warn(
+        f"rafa.{name} is deprecated; import {new} instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    if module == "rafa":
+        return globals()[attribute]
+    return getattr(_import_module(module), attribute)

rafa/actions/__init__.py

@@ -0,0 +1,42 @@
+"""
+Action system for buttons and user interactions.
+
+Actions are button-triggered operations defined on Controllers
+that execute backend logic and return results to the UI.
+"""
+
+from rafa.actions.decorators import (
+    ActionDefinition,
+    ActionLocation,
+    action,
+    get_action_definition,
+    is_action,
+)
+from rafa.actions.results import (
+    ActionResult,
+    ErrorResult,
+    FileResult,
+    OptimizationColumn,
+    OptimizationResult,
+    OptimizationResultElement,
+    SetParamsResult,
+    SuccessResult,
+)
+
+__all__ = [
+    # Decorators
+    "action",
+    "ActionDefinition",
+    "ActionLocation",
+    "is_action",
+    "get_action_definition",
+    # Results
+    "ActionResult",
+    "SuccessResult",
+    "ErrorResult",
+    "FileResult",
+    "SetParamsResult",
+    "OptimizationResult",
+    "OptimizationResultElement",
+    "OptimizationColumn",
+]

rafa/actions/decorators.py

@@ -0,0 +1,204 @@
+"""
+Action decorators for defining button-triggered operations on Controllers.
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from functools import wraps
+from typing import Any, Literal, TypeVar, get_args
+
+from rafa.actions.results import ActionResult
+from rafa.core.calculations import check_timeout
+
+ActionLocation = Literal["sidebar", "inspector"]
+"""Where an action button is placed in the workspace."""
+
+ACTION_LOCATIONS: tuple[str, ...] = get_args(ActionLocation)
+
+
+@dataclass
+class ActionDefinition:
+    """
+    Metadata about an action method.
+
+    Stored on the method and used by the runtime to:
+    - Register actions for an entity type
+    - Display buttons in the UI
+    - Handle confirmation dialogs
+
+    Attributes
+    ----------
+    label : str
+        Button label shown in UI.
+    method_name : str
+        Name of the decorated method.
+    description : str | None
+        Tooltip text.
+    confirmation_message : str | None
+        If set, shows confirmation dialog before executing.
+    dangerous : bool
+        If True, button gets warning styling (e.g., red color).
+    icon : str | None
+        Icon name (e.g., "play", "bolt").
+    location : ActionLocation
+        ``"sidebar"`` (in the inputs panel, below the inputs) or ``"inspector"`` (in the
+        results panel, below the results).
+    validate_inputs : bool
+        Only run when every input is valid (default). ``False`` for actions that repair
+        the inputs, such as "reset to defaults".
+    timeout : float | None
+        Time limit in seconds; ``None`` uses the application's, ``0`` means none.
+    permission : str
+        What a user's role must allow to run it: ``"edit"`` (default, Editor), ``"read"``
+        (Viewer too, e.g. an export) or ``"manage"`` (Project admin). A ``SetParamsResult``
+        is saved only for an Editor.
+    locks_inputs : bool
+        Whether the entity's inputs are locked while the action is queued or running (D37):
+        saves, restores and other actions that save inputs are refused. Only for actions
+        whose ``permission`` is not ``"read"``. Default True.
+    """
+
+    label: str
+    method_name: str
+    description: str | None
+    confirmation_message: str | None
+    dangerous: bool
+    icon: str | None = None
+    location: ActionLocation = "sidebar"
+    validate_inputs: bool = True
+    timeout: float | None = None
+    permission: str = "edit"
+    locks_inputs: bool = True
+
+    @property
+    def locks(self) -> bool:
+        """Whether running it locks the inputs: ``locks_inputs`` and not a ``read`` action."""
+        return self.locks_inputs and self.permission != "read"
+
+
+A = TypeVar("A", bound=Callable[..., ActionResult])
+
+
+def action(
+    label: str,
+    *,
+    description: str | None = None,
+    confirmation_message: str | None = None,
+    dangerous: bool = False,
+    icon: str | None = None,
+    location: ActionLocation = "sidebar",
+    validate_inputs: bool = True,
+    timeout: float | None = None,
+    permission: str = "edit",
+    locks_inputs: bool = True,
+) -> Callable[[A], A]:
+    """
+    Decorator to mark a method as an action.
+
+    Actions are button-triggered operations that execute backend logic
+    and return a result to the UI.
+
+    Parameters
+    ----------
+    label : str
+        Button label shown in UI.
+    description : str | None, optional
+        Tooltip/help text.
+    confirmation_message : str | None, optional
+        If set, shows "Are you sure?" dialog with this message.
+    dangerous : bool, optional
+        If True, button gets warning styling. Default False.
+    icon : str | None, optional
+        Icon name (Material Symbols, e.g. ``"bolt"``).
+    location : {"sidebar", "inspector"}, optional
+        ``"sidebar"`` puts the button in the inputs panel, below the inputs;
+        ``"inspector"`` in the results panel, below the results. Default ``"sidebar"``.
+    validate_inputs : bool, optional
+        Only run when every input is valid; otherwise the action returns an
+        ``ErrorResult`` that lists the invalid fields. Default True. Set it to False for
+        actions that repair the inputs, such as "reset to defaults".
+    timeout : float | None, optional
+        Seconds the action may calculate. On the server it is then stopped (D37) and
+        returns an ``ErrorResult`` "No result within … s."; its ``SetParamsResult`` is never
+        saved. ``None`` (default) uses the application's limit
+        (``RAFA_CALCULATION_TIMEOUT`` on the server), ``0`` means no limit.
+    permission : str, optional
+        What a user's role must allow to run the action (access control, D36):
+        ``"edit"`` (default: Editors and Project admins), ``"read"`` (Viewers too; for
+        actions that change nothing, such as an export) or ``"manage"`` (Project admins).
+        Whatever it allows, a ``SetParamsResult`` is saved only for an Editor. The
+        controller's ``check_definition()`` refuses other names.
+    locks_inputs : bool, optional
+        Lock the entity's inputs while the action is queued or running (default True): on
+        the server, saves, restores and other actions that save inputs are refused (409)
+        until it ends, so it never saves over a change made meanwhile, nor another over
+        its own. ``False`` for an action that never saves inputs (no ``SetParamsResult``,
+        no save through ``kwargs["app"]``). Actions with ``permission="read"`` never lock.
+
+    Returns
+    -------
+    Callable
+        Decorator function.
+
+    Raises
+    ------
+    ValueError
+        If ``location`` is not one of the supported locations, ``timeout`` is
+        negative, or ``locks_inputs`` is not a bool.
+    """
+    check_timeout(timeout, f"@action({label!r})")
+    if not isinstance(locks_inputs, bool):
+        raise ValueError(
+            f"@action({label!r}): locks_inputs must be True or False, got {locks_inputs!r}"
+        )
+    if location not in ACTION_LOCATIONS:
+        raise ValueError(
+            f"@action({label!r}): unknown location {location!r}. "
+            f"Use one of: {', '.join(ACTION_LOCATIONS)}"
+        )
+
+    def decorator(func: A) -> A:
+        # Create action definition
+        action_def = ActionDefinition(
+            label=label,
+            method_name=func.__name__,
+            description=description,
+            confirmation_message=confirmation_message,
+            dangerous=dangerous,
+            icon=icon,
+            location=location,
+            validate_inputs=validate_inputs,
+            timeout=timeout,
+            permission=permission,
+            locks_inputs=locks_inputs,
+        )
+
+        # Attach metadata to function
+        func._action_definition = action_def
+
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> ActionResult:
+            result = func(*args, **kwargs)
+            if not isinstance(result, ActionResult):
+                raise TypeError(
+                    f"Action '{func.__name__}' must return an ActionResult, "
+                    f"got {type(result).__name__}"
+                )
+            return result
+
+        # Preserve metadata on wrapper
+        wrapper._action_definition = action_def  # type: ignore[attr-defined]
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+def is_action(obj: Any) -> bool:
+    """Check if an object is an action method."""
+    return callable(obj) and hasattr(obj, "_action_definition")
+
+
+def get_action_definition(method: Callable[..., Any]) -> ActionDefinition | None:
+    """Get the ActionDefinition for an action method."""
+    return getattr(method, "_action_definition", None)