bec_widgets.widgets.containers.dock_area.profile_utils#

Utilities for managing BECDockArea profiles stored in INI files.

Policy: - All created/modified profiles are stored under the BEC settings root: <base_path>/profiles/{default,user} - Bundled read-only defaults are discovered in BW core states/default and plugin bec_widgets/profiles but never written to. - Lookup order when reading: user → settings default → app or plugin bundled default.

Attributes#

MODULE_PATH

ProfileOrigin

SETTINGS_KEYS

Classes#

ProfileInfo

Pydantic model capturing profile metadata surfaced in the UI.

Functions#

_app_settings(→ qtpy.QtCore.QSettings)

Access the application-wide metadata settings file for dock profiles.

_default_path_candidates(→ list[str])

Generate candidate default-profile paths honoring namespace fallbacks.

_existing_default_settings(→ qtpy.QtCore.QSettings | None)

Resolve the first existing default profile settings object.

_existing_user_settings(→ qtpy.QtCore.QSettings | None)

Resolve the first existing user profile settings object.

_file_modified_iso(→ str)

Get the file modification time as an ISO 8601 UTC string.

_last_profile_key(→ str)

Build the QSettings key used to store the last profile per namespace and

_load_screenshot_from_settings(→ qtpy.QtGui.QPixmap | None)

Load the screenshot pixmap stored in the given settings.

_manifest_count(→ int)

Get the number of widgets recorded in the manifest.

_plugin_display_name(→ str | None)

Determine a user-friendly plugin name for provenance labels.

_plugin_repo_root(→ pathlib.Path | None)

Resolve the plugin repository root path if running inside a plugin context.

_profiles_dir(→ str)

Build (and ensure) the directory that holds profiles for a namespace segment.

_settings_profiles_root(→ str)

Resolve the writable profiles root provided by the BEC client.

_user_path_candidates(→ list[str])

Generate candidate user-profile paths honoring namespace fallbacks.

default_profile_candidates(→ list[str])

List all default profile path candidates for a profile name.

default_profile_path(→ str)

Compute the canonical default profile path for a profile name.

default_profiles_dir(→ str)

Return the directory that stores default profiles for the namespace.

delete_profile_files(→ bool)

Delete the profile files from the writable settings directories.

get_last_profile(→ str | None)

Retrieve the last-used profile name persisted in app settings.

get_profile_info(→ ProfileInfo)

Assemble metadata and statistics for a profile.

is_profile_read_only(→ bool)

Check whether a profile is read-only because it originates from bundles.

is_quick_select(→ bool)

Return True if profile is marked to appear in quick-select combo.

list_profiles(→ list[str])

Enumerate all known profile names, syncing bundled defaults when missing locally.

list_quick_profiles(→ list[str])

List only profiles that have quick-select enabled (user wins over default).

load_default_profile_screenshot(...)

Load the screenshot from the default profile copy, if available.

load_profile_screenshot(→ qtpy.QtGui.QPixmap | None)

Load the stored screenshot pixmap for a profile from settings (user preferred).

load_user_profile_screenshot(→ qtpy.QtGui.QPixmap | None)

Load the screenshot from the user profile copy, if available.

module_profile_path(→ str)

Build the absolute path to a bundled module profile.

module_profiles_dir(→ str)

Return the built-in BECDockArea profiles directory bundled with the module.

now_iso_utc(→ str)

Return the current UTC timestamp formatted in ISO 8601.

open_default_settings(→ qtpy.QtCore.QSettings)

Open (and create if necessary) the default profile settings file.

open_user_settings(→ qtpy.QtCore.QSettings)

Open (and create if necessary) the user profile settings file.

plugin_profile_path(→ str | None)

Build the absolute path to a bundled plugin profile if available.

plugin_profiles_dir(→ str | None)

Locate the read-only profiles directory shipped with a beamline plugin.

profile_origin(→ ProfileOrigin)

Determine where a profile originates from.

profile_origin_display(→ str | None)

Build a user-facing label describing a profile's origin.

read_manifest(→ list[dict])

Read the manifest of dock widgets from settings.

restore_user_from_default(→ None)

Copy the default profile to the user profile, preserving quick-select flag.

set_last_profile(→ None)

Persist the last-used profile name (or clear the value when None).

set_quick_select(→ None)

Set or clear the quick-select flag for a profile.

user_profile_candidates(→ list[str])

List all user profile path candidates for a profile name.

user_profile_path(→ str)

Compute the canonical user profile path for a profile name.

user_profiles_dir(→ str)

Return the directory that stores user profiles for the namespace.

write_manifest(→ None)

Write the manifest of dock widgets to settings.

Module Contents#

class ProfileInfo(/, **data: Any)#

Bases: pydantic.BaseModel

Pydantic model capturing profile metadata surfaced in the UI.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

author: str = 'BEC Widgets'#
created: str = None#
default_path: str = ''#
is_quick_select: bool = False#
is_read_only: bool = False#
modified: str = None#
name: str#
notes: str = ''#
origin: ProfileOrigin = 'unknown'#
size_kb: int = 0#
user_path: str = ''#
widget_count: int = 0#
_app_settings() → qtpy.QtCore.QSettings#

Access the application-wide metadata settings file for dock profiles.

Returns:

Handle to the _meta.ini metadata store under the profiles root.

Return type:

QSettings

_default_path_candidates(name: str, namespace: str | None) → list[str]#

Generate candidate default-profile paths honoring namespace fallbacks.

Parameters:

  • name (str) – Profile name without extension.

  • namespace (str | None) – Optional namespace label.

Returns:

Ordered list of candidate default profile paths (.ini files).

Return type:

list[str]

_existing_default_settings(name: str, namespace: str | None = None) → qtpy.QtCore.QSettings | None#

Resolve the first existing default profile settings object.

Parameters:

  • name (str) – Profile name without extension.

  • namespace (str | None, optional) – Namespace label to search. Defaults to None.

Returns:

Config for the first existing default profile candidate, or None

when no files are present.

Return type:

QSettings | None

_existing_user_settings(name: str, namespace: str | None = None) → qtpy.QtCore.QSettings | None#

Resolve the first existing user profile settings object.

Parameters:

  • name (str) – Profile name without extension.

  • namespace (str | None, optional) – Namespace label to search. Defaults to None.

Returns:

Config for the first existing user profile candidate, or None

when no files are present.

Return type:

QSettings | None

_file_modified_iso(path: str) → str#

Get the file modification time as an ISO 8601 UTC string.

Parameters:

path (str) – Path to the file.

Returns:

ISO 8601 UTC timestamp of last modification, or current time if unavailable.

Return type:

str

_last_profile_key(namespace: str | None, instance: str | None = None) → str#

Build the QSettings key used to store the last profile per namespace and optional instance id.

Parameters:

namespace (str | None) – Namespace label.

Returns:

Scoped key string.

Return type:

str

_load_screenshot_from_settings(settings: qtpy.QtCore.QSettings) → qtpy.QtGui.QPixmap | None#

Load the screenshot pixmap stored in the given settings.

Parameters:

settings (QSettings) – Settings object to read from.

Returns:

Screenshot pixmap or None if unavailable.

Return type:

QPixmap | None

_manifest_count(settings: qtpy.QtCore.QSettings) → int#

Get the number of widgets recorded in the manifest.

Parameters:

settings (QSettings) – Settings object to read from.

Returns:

Number of widgets in the manifest.

Return type:

int

_plugin_display_name() → str | None#

Determine a user-friendly plugin name for provenance labels.

Returns:

Human-readable name inferred from the plugin repo or package,

or None if it cannot be determined.

Return type:

str | None

_plugin_repo_root() → pathlib.Path | None#

Resolve the plugin repository root path if running inside a plugin context.

Returns:

Root path of the active plugin repository, or None when

no plugin context is detected.

Return type:

Path | None

_profiles_dir(segment: str, namespace: str | None) → str#

Build (and ensure) the directory that holds profiles for a namespace segment.

Parameters:

  • segment (str) – Either "user" or "default".

  • namespace (str | None) – Optional namespace label to scope profiles.

Returns:

Absolute directory path for the requested segment/namespace pair.

Return type:

str

_settings_profiles_root() → str#

Resolve the writable profiles root provided by the BEC client.

Returns:

Absolute path to the profiles root. The directory is created if missing.

Return type:

str

_user_path_candidates(name: str, namespace: str | None) → list[str]#

Generate candidate user-profile paths honoring namespace fallbacks.

Parameters:

  • name (str) – Profile name without extension.

  • namespace (str | None) – Optional namespace label.

Returns:

Ordered list of candidate user profile paths (.ini files).

Return type:

list[str]

default_profile_candidates(name: str, namespace: str | None = None) → list[str]#

List all default profile path candidates for a profile name.

Parameters:

  • name (str) – Profile name without extension.

  • namespace (str | None, optional) – Namespace label. Defaults to None.

Returns:

De-duplicated list of candidate default profile paths.

Return type:

list[str]

default_profile_path(name: str, namespace: str | None = None) → str#

Compute the canonical default profile path for a profile name.

Parameters:

  • name (str) – Profile name without extension.

  • namespace (str | None, optional) – Namespace label. Defaults to None.

Returns:

Absolute path to the default profile file (.ini).

Return type:

str

default_profiles_dir(namespace: str | None = None) → str#

Return the directory that stores default profiles for the namespace.

Parameters:

namespace (str | None, optional) – Namespace label. Defaults to None.

Returns:

Absolute path to the default profile directory.

Return type:

str

delete_profile_files(name: str, namespace: str | None = None) → bool#

Delete the profile files from the writable settings directories.

Parameters:

  • name (str) – Profile name without extension.

  • namespace (str | None, optional) – Namespace label scoped to the profile. Defaults to None.

Returns:

True if at least one file was removed.

Return type:

bool

get_last_profile(namespace: str | None = None, instance: str | None = None, *, allow_namespace_fallback: bool = True) → str | None#

Retrieve the last-used profile name persisted in app settings.

When instance is provided, the lookup is scoped to that particular dock area instance. If the instance-specific entry is missing and allow_namespace_fallback is True, the namespace-wide entry is consulted next.

Parameters:

  • namespace (str | None, optional) – Namespace label. Defaults to None.

  • instance (str | None, optional) – Optional instance ID. Defaults to None.

  • allow_namespace_fallback (bool) – Whether to fall back to the namespace entry when an instance-specific value is not found. Defaults to True.

Returns:

Profile name or None if none has been stored.

Return type:

str | None

get_profile_info(name: str, namespace: str | None = None) → ProfileInfo#

Assemble metadata and statistics for a profile.

Parameters:

  • name (str) – Profile name without extension.

  • namespace (str | None, optional) – Namespace label. Defaults to None.

Returns:

Structured profile metadata, preferring the user copy when present.

Return type:

ProfileInfo

is_profile_read_only(name: str, namespace: str | None = None) → bool#

Check whether a profile is read-only because it originates from bundles.

Parameters:

  • name (str) – Profile name without extension.

  • namespace (str | None, optional) – Namespace label to consider. Defaults to None.

Returns:

True if the profile originates from module or plugin bundles.

Return type:

bool

is_quick_select(name: str, namespace: str | None = None) → bool#

Return True if profile is marked to appear in quick-select combo.

Parameters:

  • name (str) – Profile name without extension.

  • namespace (str | None, optional) – Namespace label. Defaults to None.

Returns:

True if quick-select is enabled for the profile.

Return type:

bool

list_profiles(namespace: str | None = None) → list[str]#

Enumerate all known profile names, syncing bundled defaults when missing locally.

Parameters:

namespace (str | None, optional) – Namespace label scoped to the profile set. Defaults to None.

Returns:

Sorted unique profile names.

Return type:

list[str]

list_quick_profiles(namespace: str | None = None) → list[str]#

List only profiles that have quick-select enabled (user wins over default).

Parameters:

namespace (str | None, optional) – Namespace label. Defaults to None.

Returns:

Sorted list of profile names with quick-select enabled.

Return type:

list[str]

load_default_profile_screenshot(name: str, namespace: str | None = None) → qtpy.QtGui.QPixmap | None#

Load the screenshot from the default profile copy, if available.

Parameters:

  • name (str) – Profile name without extension.

  • namespace (str | None, optional) – Namespace label. Defaults to None.

Returns:

Screenshot pixmap or None if unavailable.

Return type:

QPixmap | None

load_profile_screenshot(name: str, namespace: str | None = None) → qtpy.QtGui.QPixmap | None#

Load the stored screenshot pixmap for a profile from settings (user preferred).

Parameters:

  • name (str) – Profile name without extension.

  • namespace (str | None, optional) – Namespace label. Defaults to None.

Returns:

Screenshot pixmap or None if unavailable.

Return type:

QPixmap | None

load_user_profile_screenshot(name: str, namespace: str | None = None) → qtpy.QtGui.QPixmap | None#

Load the screenshot from the user profile copy, if available.

Parameters:

  • name (str) – Profile name without extension.

  • namespace (str | None, optional) – Namespace label. Defaults to None.

Returns:

Screenshot pixmap or None if unavailable.

Return type:

QPixmap | None

module_profile_path(name: str) → str#

Build the absolute path to a bundled module profile.

Parameters:

name (str) – Profile name without extension.

Returns:

Absolute path to the module’s read-only profile file.

Return type:

str

module_profiles_dir() → str#

Return the built-in BECDockArea profiles directory bundled with the module.

Returns:

Absolute path of the read-only module profiles directory.

Return type:

str

now_iso_utc() → str#

Return the current UTC timestamp formatted in ISO 8601.

Returns:

UTC timestamp string (e.g., "2024-06-05T12:34:56Z").

Return type:

str

open_default_settings(name: str, namespace: str | None = None) → qtpy.QtCore.QSettings#

Open (and create if necessary) the default profile settings file.

Parameters:

  • name (str) – Profile name without extension.

  • namespace (str | None, optional) – Namespace label. Defaults to None.

Returns:

Settings instance targeting the default profile file.

Return type:

QSettings

open_user_settings(name: str, namespace: str | None = None) → qtpy.QtCore.QSettings#

Open (and create if necessary) the user profile settings file.

Parameters:

  • name (str) – Profile name without extension.

  • namespace (str | None, optional) – Namespace label. Defaults to None.

Returns:

Settings instance targeting the user profile file.

Return type:

QSettings

plugin_profile_path(name: str) → str | None#

Build the absolute path to a bundled plugin profile if available.

Parameters:

name (str) – Profile name without extension.

Returns:

Absolute plugin profile path, or None when plugins do not

provide profiles.

Return type:

str | None

plugin_profiles_dir() → str | None#

Locate the read-only profiles directory shipped with a beamline plugin.

Returns:

Directory containing bundled plugin profiles, or None if

no plugin profiles are available.

Return type:

str | None

profile_origin(name: str, namespace: str | None = None) → ProfileOrigin#

Determine where a profile originates from.

Parameters:

  • name (str) – Profile name without extension.

  • namespace (str | None, optional) – Namespace label to consider. Defaults to None.

Returns:

"module" for bundled BEC profiles, "plugin" for beamline

plugin bundles, "settings" for writable copies, and "unknown" when no backing files are found.

Return type:

ProfileOrigin

profile_origin_display(name: str, namespace: str | None = None) → str | None#

Build a user-facing label describing a profile’s origin.

Parameters:

  • name (str) – Profile name without extension.

  • namespace (str | None, optional) – Namespace label to consider. Defaults to None.

Returns:

Localized display label such as "BEC Widgets" or "User",

or None when origin cannot be determined.

Return type:

str | None

read_manifest(settings: qtpy.QtCore.QSettings) → list[dict]#

Read the manifest of dock widgets from settings.

Parameters:

settings (QSettings) – Settings object to read from.

Returns:

List of dock widget metadata dictionaries.

Return type:

list[dict]

restore_user_from_default(name: str, namespace: str | None = None) → None#

Copy the default profile to the user profile, preserving quick-select flag.

Parameters:

  • name (str) – Profile name without extension.

  • namespace (str | None, optional) – Namespace label. Defaults to None.

set_last_profile(name: str | None, namespace: str | None = None, instance: str | None = None) → None#

Persist the last-used profile name (or clear the value when None).

When instance is provided, the value is stored under a key specific to that dock area instance; otherwise it is stored under the namespace-wide key.

Parameters:

  • name (str | None) – Profile name to store.

  • namespace (str | None, optional) – Namespace label. Defaults to None.

  • instance (str | None, optional) – Optional instance ID. Defaults to None.

set_quick_select(name: str, enabled: bool, namespace: str | None = None) → None#

Set or clear the quick-select flag for a profile.

Parameters:

  • name (str) – Profile name without extension.

  • enabled (bool) – True to enable quick-select, False to disable.

  • namespace (str | None, optional) – Namespace label. Defaults to None.

user_profile_candidates(name: str, namespace: str | None = None) → list[str]#

List all user profile path candidates for a profile name.

Parameters:

  • name (str) – Profile name without extension.

  • namespace (str | None, optional) – Namespace label. Defaults to None.

Returns:

De-duplicated list of candidate user profile paths.

Return type:

list[str]

user_profile_path(name: str, namespace: str | None = None) → str#

Compute the canonical user profile path for a profile name.

Parameters:

  • name (str) – Profile name without extension.

  • namespace (str | None, optional) – Namespace label. Defaults to None.

Returns:

Absolute path to the user profile file (.ini).

Return type:

str

user_profiles_dir(namespace: str | None = None) → str#

Return the directory that stores user profiles for the namespace.

Parameters:

namespace (str | None, optional) – Namespace label. Defaults to None.

Returns:

Absolute path to the user profile directory.

Return type:

str

write_manifest(settings: qtpy.QtCore.QSettings, docks: list[bec_widgets.widgets.containers.qt_ads.CDockWidget]) → None#

Write the manifest of dock widgets to settings.

Parameters:

  • settings (QSettings) – Settings object to write to.

  • docks (list[CDockWidget]) – List of dock widgets to serialize.

MODULE_PATH#
ProfileOrigin#
SETTINGS_KEYS#