Add the metadata Parameter attribute (#1094)

Author: maximlt

doc/user_guide/Parameters.ipynb

@@ -40,6 +40,7 @@
     "- **precedence**: Optional numeric value controlling whether this parameter is visible in a listing and if so in what order.\n",
     "- **allow_refs**: Whether to allow the Parameter to accept references to other Parameters that will be dynamically resolved.\n",
     "- **nested_refs**: Whether references should be resolved even when they are nested inside a container.\n",
+    "- **metadata**: Optional arbitrary mapping, to be used to store additional metadata than cannot be declared with the other attributes. Useful for third-party libraries to extend Param.\n",
     "\n",
     "Most of these settings (apart from **name**) are accepted as keyword arguments to the Parameter's constructor, with `default` mostly also accepted as the only positional argument:"
    ]
@@ -929,6 +930,105 @@
     "Object().debug_id, SubObject().debug_id"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b4a9751f-e307-4b9e-8c25-fc2059200152",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import param"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "32cc7b01-55a2-43dd-b886-acf0c30cb5ba",
+   "metadata": {},
+   "source": [
+    "## Arbitrary Metadata\n",
+    "\n",
+    "Parameters may include arbitrary metadata as a mapping stored in the `metadata` attribute (default is `None`). This attribute is not used internally by Param, instead it is meant to enable rich functionality in third-party libraries, or to be leveraged in your own code base to extend Parameters with information that cannot be declared with the other attributes available. Note that a shallow copy of the mapping you'll pass will be made on class creation and on instance-level parameter creation. This behavior is not specific to the `metadata` attribute, it is how Param handles attributes with value that are mutable containers (lists, dicts, sets)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cf82e531-40f4-4960-9ba1-1df012711a93",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "extra_info = {'library': {'config': True}}\n",
+    "\n",
+    "class P(param.Parameterized):\n",
+    "    s = param.String(metadata=extra_info)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c9f6182e-320d-4e54-b8aa-7596ccabdb29",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "P.param['s'].metadata"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9207c2f0-44de-4bed-8f80-753393fcf66f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "p = P()\n",
+    "p.param.s.metadata"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "639dadc6-bf31-4eac-9327-8bcc12e0eb63",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "P.param['s'].metadata is extra_info  # shallow copy made on class creation"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d3cd5940-9b40-48a3-9fe1-4a14f2c6c803",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "p.param['s'].metadata is P.param['s'].metadata  # shallow copy made when the instance-level Parameter is created"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d0cfdb8c-29ac-4391-a0c8-353665e93e03",
+   "metadata": {},
+   "source": [
+    "To provide a more concrete example on how third-party libraries can benefit from the `metadata` attribute, we'll give an example with [Panel](https://panel.holoviz.org), a library to build web apps written in Python only. Panel already integrates with Param, and makes it easy to display a Parameterized instance as an app component, each Parameter type being automatically mapped to a widget type (e.g., a `Number` Parameter is displayed as a float slider). Customizing the automatically created widget requires additional work in Panel (e.g., using the `Widget.from_param(<parameter>)` API). To simplify this process, Panel could inspect the `metadata` attribute for custom widget configuration, and apply it on widget creation:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4ee588b7-5715-4846-a079-3e5fe8e47cf5",
+   "metadata": {},
+   "source": [
+    "```python\n",
+    "import panel as pn\n",
+    "\n",
+    "pn.extension()\n",
+    "\n",
+    "class MyPanelView(param.Parameterized):\n",
+    "    percentage = param.Number(default=0, bounds=(0, 100), metadata={'panel': {'width': 100}})\n",
+    "\n",
+    "pn.Param(MyPanelView())\n",
+    "```"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "14a20588",

param/parameterized.py

@@ -1317,7 +1317,8 @@ class Parameter(_ParameterBase):
     __slots__ = ['name', 'default', 'default_factory', 'doc',
                  'precedence', 'instantiate', 'constant', 'readonly',
                  'pickle_default_value', 'allow_None', 'per_instance',
-                 'watchers', 'owner', 'allow_refs', 'nested_refs', '_label']
+                 'watchers', 'owner', 'allow_refs', 'nested_refs', '_label',
+                 'metadata',]
 
     # Note: When initially created, a Parameter does not know which
     # Parameterized class owns it, nor does it know its names
@@ -1331,6 +1332,7 @@ class Parameter(_ParameterBase):
         default=None, precedence=None, doc=None, _label=None, instantiate=False,
         constant=False, readonly=False, pickle_default_value=True, allow_None=False,
         per_instance=True, allow_refs=False, nested_refs=False, default_factory=None,
+        metadata=None,
     )
 
     # Parameters can be updated during Parameterized class creation when they
@@ -1339,15 +1341,15 @@ class Parameter(_ParameterBase):
     # in this list do not have to trigger such re-validation.
     _non_validated_slots = ['_label', 'doc', 'name', 'precedence',
                             'constant', 'pickle_default_value',
-                            'watchers', 'owner']
+                            'watchers', 'owner', 'metadata']
 
     @typing.overload
     def __init__(
         self,
         default=None, *,
         doc=None, label=None, precedence=None, instantiate=False, constant=False,
         readonly=False, pickle_default_value=True, allow_None=False, per_instance=True,
-        allow_refs=False, nested_refs=False, default_factory=None,
+        allow_refs=False, nested_refs=False, default_factory=None, metadata=None,
     ):
         ...
 
@@ -1367,6 +1369,7 @@ def __init__( # pylint: disable-msg=R0913
         allow_refs=Undefined,
         nested_refs=Undefined,
         default_factory=Undefined,
+        metadata=Undefined,
     ):
         """
         Initialize a new :class:`Parameter` object with the specified attributes.
@@ -1449,6 +1452,12 @@ def __init__( # pylint: disable-msg=R0913
             If ``True`` and ``allow_refs=True``, inspects nested objects (e.g.,
             dictionaries, lists, slices, tuples) for references and resolves
             them automatically. Default is ``False``.
+        metadata : Mapping, optional
+            An arbitrary mapping, to be used to store additional metadata
+            than cannot be declared with the other attributes. Useful for
+            third-party libraries to extend Param. Default is ``None``.
+
+            .. versionadded:: 2.3.0
 
         Examples
         --------
@@ -1498,6 +1507,7 @@ def __init__( # pylint: disable-msg=R0913
             )
         self.pickle_default_value = pickle_default_value
         self._set_allow_None(allow_None)
+        self.metadata = metadata
         self.watchers = {}
         self.per_instance = per_instance
 
@@ -1995,7 +2005,7 @@ def __init__(
         default="", *, regex=None,
         doc=None, label=None, precedence=None, instantiate=False, constant=False,
         readonly=False, pickle_default_value=True, allow_None=False, per_instance=True,
-        allow_refs=False, nested_refs=False, default_factory=None
+        allow_refs=False, nested_refs=False, default_factory=None, metadata=None,
     ):
         ...