API Reference¶

@dataclass(frozen=True)
class PanelAppMetadata:
    """Metadata attached to a component or page by the @register decorator."""

    page: bool = True
    component: bool = False
    sidebar: bool = False
    title: str | None = None
    icon: str | None = None
    description: str | None = None
    tags: list[str] = field(default_factory=list)
    default_size: dict[str, Any] | None = None
    min_size: dict[str, Any] | None = None
    max_size: dict[str, Any] | None = None
    singleton: bool = False
    provides: list[str] = field(default_factory=list)
    requires: list[Any] = field(default_factory=list)
    config_schema: Any = None
    config: list[str] = field(default_factory=list)
    config_editor: Callable | None = None
    allow_users: list[str] = field(default_factory=list)
    allow_groups: list[str] = field(default_factory=list)
    deny_users: list[str] = field(default_factory=list)
    deny_groups: list[str] = field(default_factory=list)
    authorize: Callable | None = None

    @property
    def permission(self) -> Permission:
        """Build a :class:`~panel_flowdash.auth.Permission` from the declared rules."""
        return Permission.from_spec(
            allow_users=self.allow_users,
            allow_groups=self.allow_groups,
            deny_users=self.deny_users,
            deny_groups=self.deny_groups,
        )

    @classmethod
    def from_app(cls, app: Any) -> PanelAppMetadata:
        """Extract metadata from an app object."""
        metadata = getattr(app, "__panel_app_metadata__", None)
        if metadata is None:
            metadata = _APP_METADATA_BY_ID.get(id(app))
        if metadata is None:
            return cls()
        if isinstance(metadata, cls):
            return metadata
        if isinstance(metadata, dict):
            return cls(**metadata)
        raise TypeError("Unsupported panel app metadata type.")

@dataclass(frozen=True)
class Permission:
    """An allow/deny rule set evaluated against an :class:`Identity`.

    All four fields match either the resolved ``user`` (OAuth login *or* system
    user) or one of the identity's ``groups``. An empty ``Permission`` declares
    no constraints and defers entirely to the caller's default policy.
    """

    allow_users: frozenset[str] = field(default_factory=frozenset)
    allow_groups: frozenset[str] = field(default_factory=frozenset)
    deny_users: frozenset[str] = field(default_factory=frozenset)
    deny_groups: frozenset[str] = field(default_factory=frozenset)

    @property
    def is_empty(self) -> bool:
        """Whether the permission declares no allow or deny rules."""
        return not (self.allow_users or self.allow_groups or self.deny_users or self.deny_groups)

    @classmethod
    def from_spec(
        cls,
        *,
        allow_users: Iterable[str] | None = None,
        allow_groups: Iterable[str] | None = None,
        deny_users: Iterable[str] | None = None,
        deny_groups: Iterable[str] | None = None,
    ) -> Permission:
        """Build a :class:`Permission` from loosely-typed iterables."""
        return cls(
            allow_users=frozenset(allow_users or ()),
            allow_groups=frozenset(allow_groups or ()),
            deny_users=frozenset(deny_users or ()),
            deny_groups=frozenset(deny_groups or ()),
        )

    def to_dict(self) -> dict[str, list[str]]:
        """Serialize to sorted lists for JSON persistence."""
        return {
            "allow_users": sorted(self.allow_users),
            "allow_groups": sorted(self.allow_groups),
            "deny_users": sorted(self.deny_users),
            "deny_groups": sorted(self.deny_groups),
        }

    @classmethod
    def from_dict(cls, data: dict[str, Any] | None) -> Permission:
        """Deserialize from a (possibly ``None`` or partial) mapping."""
        data = data or {}
        return cls.from_spec(
            allow_users=data.get("allow_users"),
            allow_groups=data.get("allow_groups"),
            deny_users=data.get("deny_users"),
            deny_groups=data.get("deny_groups"),
        )

@dataclass
class RegistryEntry:
    """A registered component/page with its metadata."""

    app_id: str
    section: str
    name: str
    page_path: str
    module_name: str
    metadata: PanelAppMetadata
    module_path: pathlib.Path | None = None
    app: Any = None

    @property
    def title(self) -> str:
        """Human-readable title."""
        return self.metadata.title or self.name.replace("_", " ")

    def load(self) -> Any:
        """Import the module and return the app object.

        Caches the result on ``self.app``.  Raises on import failure.
        """
        if self.app is not None:
            return self.app
        module = importlib.import_module(self.module_name)
        app = getattr(module, "app", None)
        if app is None:
            raise ImportError(f"Module '{self.module_name}' has no 'app' export.")
        # Refresh metadata from the live object (decorators may carry richer info
        # e.g. config_schema / config_editor that AST cannot capture).
        object.__setattr__(self, "app", app)
        live_metadata = PanelAppMetadata.from_app(app)
        # Only replace if the live decorator actually produced a non-default result
        # (guards against bare Viewer classes with no @register decorator).
        if live_metadata != PanelAppMetadata():
            object.__setattr__(self, "metadata", live_metadata)
        return app