Skip to content

Introduce Widget.label and treat name as alias #8328

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
philippjfr wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Introduce Widget.label and treat name as alias #8328

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a4908a3
Introduce Widget.label and treat name as alias
philippjfr Dec 3, 2025
6558136
Apply suggestions from code review
philippjfr Dec 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 32 additions & 4 deletions panel/widgets/base.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@
"""
from __future__ import annotations

import warnings

from collections.abc import Callable, Mapping
from typing import (
TYPE_CHECKING, Any, ClassVar, TypeVar,
Expand Down Expand Up @@ -121,7 +123,11 @@ class Widget(Reactive, WidgetBase):
disabled = param.Boolean(default=False, doc="""
Whether the widget is disabled.""")

name = param.String(default='', constant=False)
label = param.String(default='', doc="""
The label for the widget.""")

name = param.String(default='', constant=False, doc="""
Alias for label.""")

height = param.Integer(default=None, bounds=(0, None))

Expand All @@ -132,7 +138,7 @@ class Widget(Reactive, WidgetBase):
be specified as a two-tuple of the form (vertical, horizontal)
or a four-tuple (top, right, bottom, left).""")

_rename: ClassVar[Mapping[str, str | None]] = {'name': 'title'}
_rename: ClassVar[Mapping[str, str | None]] = {'label': 'title', 'name': None}

# Whether the widget supports embedding
_supports_embed: bool = False
Expand All @@ -143,8 +149,22 @@ class Widget(Reactive, WidgetBase):
__abstract = True

def __init__(self, **params: Any):
if 'name' not in params:
params['name'] = ''
if "name" in params and "label" in params:
warnings.warn(
"Both 'name' and 'label' were provided; using 'label' and ignoring 'name'.",
DeprecationWarning,
stacklevel=2,
)
params.pop("name")
elif "name" in params:
warnings.warn(
"'name' is deprecated and will be removed in a future release. Use 'label' instead.",
DeprecationWarning,
stacklevel=2,
)
params["label"] = params.pop("name")
elif "label" not in params:
params["label"] = ""
if '_supports_embed' in params:
self._supports_embed = params.pop('_supports_embed')
if '_param_pane' in params:
Expand All @@ -153,6 +173,14 @@ def __init__(self, **params: Any):
self._param_pane = None
super().__init__(**params)

@param.depends("name", watch=True)
def _sync__label(self):
self.label = self.name

@param.depends("label", watch=True)
def _sync__name(self):
self.name = self.label

@property
def _linked_properties(self) -> tuple[str, ...]:
props = list(super()._linked_properties)
Expand Down
4 changes: 2 additions & 2 deletions panel/widgets/icon.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ class _ClickableIcon(Widget):
_widget_type = _PnClickableIcon

_rename: ClassVar[Mapping[str, str | None]] = {
**TooltipMixin._rename, 'name': 'title',
**TooltipMixin._rename, 'label': 'title',
}

_source_transforms: ClassVar[Mapping[str, str | None]] = {
Expand Down Expand Up @@ -118,7 +118,7 @@ class ButtonIcon(_ClickableIcon, _ClickButton, TooltipMixin):
_widget_type = _PnButtonIcon

_rename: ClassVar[Mapping[str, str | None]] = {
**TooltipMixin._rename, 'name': 'title', 'clicks': None,
**TooltipMixin._rename, 'label': 'title', 'clicks': None,
}

_target_transforms: ClassVar[Mapping[str, str | None]] = {
Expand Down
40 changes: 20 additions & 20 deletions panel/widgets/indicators.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
---------------------

>>> pn.indicators.Number(
... name='Rate', value=72, format='{value}%',
... label='Rate', value=72, format='{value}%',
... colors=[(80, 'green'), (100, 'red')]
... )
"""
Expand Down Expand Up @@ -71,7 +71,7 @@ class Indicator(Widget):

_linked_properties: tuple[str,...] = ()

_rename: ClassVar[Mapping[str, str | None]] = {'name': None}
_rename: ClassVar[Mapping[str, str | None]] = {'label': None}

__abstract = True

Expand Down Expand Up @@ -217,7 +217,7 @@ class LoadingSpinner(BooleanIndicator):
value = param.Boolean(default=False, doc="""
Whether the indicator is active or not.""")

_rename = {'name': 'text'}
_rename = {'label': 'text'}

_source_transforms: ClassVar[Mapping[str, str | None]] = {
'value': None, 'color': None, 'bgcolor': None, 'size': None
Expand Down Expand Up @@ -327,7 +327,7 @@ class Number(ValueIndicator):

:Example:

>>> Number(name='Rate', value=72, format='{value}%', colors=[(80, 'green'), (100, 'red')]
>>> Number(label='Rate', value=72, format='{value}%', colors=[(80, 'green'), (100, 'red')]
"""

default_color = param.String(default='black', doc="""
Expand All @@ -347,9 +347,9 @@ class Number(ValueIndicator):
How to format nan values.""")

title_size = param.String(default='18pt', doc="""
The size of the title given by the name.""")
The size of the title given by the label.""")

_rename: ClassVar[Mapping[str, str | None]] = {'name': 'name'}
_rename: ClassVar[Mapping[str, str | None]] = {'label': 'label'}

_source_transforms: ClassVar[Mapping[str, str | None]] = {
'value': None, 'colors': None, 'default_color': None,
Expand All @@ -370,7 +370,7 @@ def _process_param_change(self, msg):
return msg
font_size = msg.pop('font_size', self.font_size)
title_font_size = msg.pop('title_size', self.title_size)
name = msg.pop('name', self.name)
label = msg.pop('label', self.label)
format = msg.pop('format', self.format)
value = msg.pop('value', self.value)
nan_format = msg.pop('nan_format', self.nan_format)
Expand All @@ -383,9 +383,9 @@ def _process_param_change(self, msg):
value = float('nan')
value = format.format(value=value).replace('nan', nan_format)
text = f'<div style="font-size: {font_size}; color: {color}">{value}</div>'
if self.name:
if self.label:
title_font_size = msg.pop('title_size', self.title_size)
text = f'<div style="font-size: {title_font_size}; color: {color}">{name}</div>\n{text}'
text = f'<div style="font-size: {title_font_size}; color: {color}">{label}</div>\n{text}'
msg['text'] = escape(text)
return msg

Expand All @@ -402,7 +402,7 @@ class String(ValueIndicator):
The size of number itself.""")

title_size = param.String(default='18pt', doc="""
The size of the title given by the name.""")
The size of the title given by the label.""")

value = param.String(default=None, allow_None=True, doc="""
The string to display""")
Expand All @@ -426,13 +426,13 @@ def _process_param_change(self, msg):
return msg
font_size = msg.pop('font_size', self.font_size)
title_font_size = msg.pop('title_size', self.title_size)
name = msg.pop('name', self.name)
label = msg.pop('label', self.label)
value = msg.pop('value', self.value)
color = msg.pop('default_color', self.default_color)
text = f'<div style="font-size: {font_size}; color: {color}">{value}</div>'
if self.name:
if self.label:
title_font_size = msg.pop('title_size', self.title_size)
text = f'<div style="font-size: {title_font_size}; color: {color}">{name}</div>\n{text}'
text = f'<div style="font-size: {title_font_size}; color: {color}">{label}</div>\n{text}'
msg['text'] = escape(text)
return msg

Expand All @@ -447,7 +447,7 @@ class Gauge(ValueIndicator):

:Example:

>>> Gauge(name='Speed', value=79, bounds=(0, 200), colors=[(0.4, 'green'), (1, 'red')])
>>> Gauge(label='Speed', value=79, bounds=(0, 200), colors=[(0.4, 'green'), (1, 'red')])
"""

annulus_width = param.Integer(default=10, doc="""
Expand Down Expand Up @@ -541,7 +541,7 @@ def _process_param_change(self, msg):
'startAngle': msg.pop('start_angle', self.start_angle),
'endAngle': msg.pop('end_angle', self.end_angle),
'splitNumber': msg.pop('num_splits', self.num_splits),
'data': [{'value': msg.pop('value', self.value), 'name': self.name}],
'data': [{'value': msg.pop('value', self.value), 'name': self.label}],
'axisLine': {
'lineStyle': {
'width': msg.pop('annulus_width', self.annulus_width),
Expand Down Expand Up @@ -580,7 +580,7 @@ class Dial(ValueIndicator):

:Example:

>>> Dial(name='Speed', value=79, format="{value} km/h", bounds=(0, 200), colors=[(0.4, 'green'), (1, 'red')])
>>> Dial(label='Speed', value=79, format="{value} km/h", bounds=(0, 200), colors=[(0.4, 'green'), (1, 'red')])
"""

annulus_width = param.Number(default=0.2, doc="""
Expand Down Expand Up @@ -732,7 +732,7 @@ def _get_data(self, properties):
text_data= {
'x': np.array([0, 0, tminx, tmaxx]),
'y': np.array([-.2, -.5, tminy, tmaxy]),
'text': [self.name, value, min_value, max_value],
'text': [self.label, value, min_value, max_value],
'rot': np.array([0, 0, tmin_angle, tmax_angle]),
'size': [title_size, value_size, tick_size, tick_size],
'color': [self.label_color, color, self.label_color, self.label_color]
Expand Down Expand Up @@ -890,7 +890,7 @@ class LinearGauge(ValueIndicator):

_rename: ClassVar[Mapping[str, str | None]] = {
'background': 'background_fill_color',
'name': 'name',
'label': 'label',
'show_boundaries': None,
'default_color': None
}
Expand Down Expand Up @@ -1118,7 +1118,7 @@ class Trend(SyncableData, Indicator):
:Example:

>>> data = {'x': np.arange(50), 'y': np.random.randn(50).cumsum()}
>>> Trend(name='Price', data=data, plot_type='area', width=200, height=200)
>>> Trend(label='Price', data=data, plot_type='area', width=200, height=200)
"""

data = param.Parameter(doc="""
Expand Down Expand Up @@ -1150,7 +1150,7 @@ class Trend(SyncableData, Indicator):
'fixed', 'stretch_width', 'stretch_height', 'stretch_both',
'scale_width', 'scale_height', 'scale_both', None])

name = param.String(constant=False, doc="""The name or a short description of the card""")
label = param.String(constant=False, doc="""The label or a short description of the card""")

value = param.Parameter(default='auto', doc="""
The primary value to be displayed.""")
Expand Down
14 changes: 7 additions & 7 deletions panel/widgets/input.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -444,7 +444,7 @@ class StaticText(Widget):

_format: ClassVar[str] = '<b>{title}</b>: {value}'

_rename: ClassVar[Mapping[str, str | None]] = {'name': None, 'value': 'text'}
_rename: ClassVar[Mapping[str, str | None]] = {'label': None, 'value': 'text'}

_target_transforms: ClassVar[Mapping[str, str | None]] = {
'value': 'target.text.split(": ")[0]+": "+value'
Expand Down Expand Up @@ -1238,9 +1238,9 @@ def _process_property_change(self, msg):
else:
value = typed_value
msg['value'] = value
msg['name'] = msg.get('title', self.name).replace(self._state, '') + new_state
msg['label'] = msg.get('title', self.label).replace(self._state, '') + new_state
self._state = new_state
self.param.trigger('name')
self.param.trigger('label')
return msg

def _process_param_change(self, msg):
Expand Down Expand Up @@ -1399,7 +1399,7 @@ def _process_property_change(self, msg):
new_state = ' (out of bounds)'
value = self.value
msg['value'] = value
msg['name'] = msg.get('title', self.name).replace(self._state, '') + new_state
msg['label'] = msg.get('title', self.label).replace(self._state, '') + new_state
self._state = new_state
return msg

Expand Down Expand Up @@ -1460,9 +1460,9 @@ def __init__(self, **params):
self._update_widgets()
self._update_label()

@param.depends('name', '_start.name', '_end.name', watch=True)
@param.depends('label', '_start.label', '_end.label', watch=True)
def _update_label(self):
self._text.value = f'{self.name}{self._start.name}{self._end.name}{self._msg}'
self._text.value = f'{self.label}{self._start.label}{self._end.label}{self._msg}'

@param.depends('_start.value', '_end.value', watch=True)
def _update(self):
Expand Down Expand Up @@ -1507,7 +1507,7 @@ class _BooleanWidget(Widget):

_supports_embed: bool = True

_rename: ClassVar[Mapping[str, str | None]] = {'value': 'active', 'name': 'label'}
_rename: ClassVar[Mapping[str, str | None]] = {'value': 'active'}

__abstract = True

Expand Down
9 changes: 4 additions & 5 deletions panel/widgets/misc.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,11 +37,10 @@ class VideoStream(Widget):

:Example:

>>> VideoStream(name='Video Stream', timeout=100)
>>> VideoStream(label='Video Stream', timeout=100)
"""

format = param.Selector(default='png', objects=['png', 'jpeg'],
doc="""
format = param.Selector(default='png', objects=['png', 'jpeg'], doc="""
The file format as which the video is returned.""")

paused = param.Boolean(default=False, doc="""
Expand All @@ -55,7 +54,7 @@ class VideoStream(Widget):

_widget_type: ClassVar[type[Model]] = _BkVideoStream

_rename: ClassVar[Mapping[str, str | None]] = {'name': None}
_rename: ClassVar[Mapping[str, str | None]] = {'label': None}

def snapshot(self):
"""
Expand Down Expand Up @@ -333,7 +332,7 @@ class JSONEditor(Widget):
JSON data to be edited.""")

_rename: ClassVar[Mapping[str, str | None]] = {
'name': None, 'value': 'data'
'label': None, 'value': 'data'
}

def _get_model(self, doc, root=None, parent=None, comm=None):
Expand Down
6 changes: 3 additions & 3 deletions panel/widgets/select.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -999,7 +999,7 @@ class AutocompleteInput(SingleSelectBase):

_allows_none: ClassVar[bool] = True

_rename: ClassVar[Mapping[str, str | None]] = {'name': 'title', 'options': 'completions'}
_rename: ClassVar[Mapping[str, str | None]] = {'label': 'title', 'options': 'completions'}

_widget_type: ClassVar[type[Model]] = _BkAutocompleteInput

Expand Down Expand Up @@ -1030,7 +1030,7 @@ class _RadioGroupBase(SingleSelectBase):
_supports_embed = False

_rename: ClassVar[Mapping[str, str | None]] = {
'name': None, 'options': 'labels', 'value': 'active'
'label': None, 'options': 'labels', 'value': 'active'
}

_source_transforms = {'value': "source.labels[value]"}
Expand Down Expand Up @@ -1146,7 +1146,7 @@ class _CheckGroupBase(SingleSelectBase):

value = param.List(default=[])

_rename: ClassVar[Mapping[str, str | None]] = {'name': None, 'options': 'labels', 'value': 'active'}
_rename: ClassVar[Mapping[str, str | None]] = {'label': None, 'options': 'labels', 'value': 'active'}

_source_transforms = {'value': "value.map((index) => source.labels[index])"}

Expand Down
2 changes: 1 addition & 1 deletion panel/widgets/speech_to_text.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -393,7 +393,7 @@ class SpeechToText(Widget):
browser.""")

_rename: ClassVar[Mapping[str, str | None]] = {
'grammars': None, '_grammars': 'grammars', 'name': None, 'value': None,
'grammars': None, '_grammars': 'grammars', 'label': None, 'value': None,
}

_widget_type: ClassVar[type[Model]] = _BkSpeechToText
Expand Down
10 changes: 5 additions & 5 deletions panel/widgets/tables.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,7 @@ class BaseTable(ReactiveData, Widget):
]

_rename: ClassVar[Mapping[str, str | None]] = {
'hierarchical': None, 'name': None, 'selection': None
'hierarchical': None, 'label': None, 'selection': None
}

__abstract = True
Expand Down Expand Up @@ -2250,15 +2250,15 @@ def download_menu(self, text_kwargs={}, button_kwargs={}):
The Button that triggers a download.
"""
text_kwargs = dict(text_kwargs)
if 'name' not in text_kwargs:
text_kwargs['name'] = 'Filename'
if 'label' not in text_kwargs:
text_kwargs['label'] = 'Filename'
if 'value' not in text_kwargs:
text_kwargs['value'] = 'table.csv'
filename = TextInput(**text_kwargs)

button_kwargs = dict(button_kwargs)
if 'name' not in button_kwargs:
button_kwargs['name'] = 'Download'
if 'label' not in button_kwargs:
button_kwargs['label'] = 'Download'
button = Button(**button_kwargs)
button.js_on_click({'table': self, 'filename': filename}, code="""
table.filename = filename.value
Expand Down
Loading
Loading