vitessce 3.6.9__py3-none-any.whl → 3.7.0__py3-none-any.whl

vitessce/config.py

@@ -925,6 +925,19 @@ class VitessceConfig:
             del self.background_servers[port]
 
     def stop_all_servers(self):
+        """
+        Stop all background servers associated with this config instance.
+
+        .. code-block:: python
+            :emphasize-lines: 5
+
+            from vitessce import VitessceConfig
+
+            vc = VitessceConfig(schema_version="1.0.18", name='My Config')
+            vw = vc.widget()
+            # ... do something with the widget ...
+            vc.stop_all_servers()
+        """
         for server in self.background_servers.values():
             server.stop()
         self.background_servers = {}
@@ -1791,6 +1804,17 @@ class VitessceConfig:
         :param int height: The height of the widget, in pixels. By default, 600.
         :param int port: The port to use when serving data objects on localhost. By default, 8000.
         :param bool proxy: Is this widget being served through a proxy, for example with a cloud notebook (e.g. Binder)?
+        :param str js_package_version: The version of the NPM package ('vitessce' if not js_dev_mode else '@vitessce/dev').
+        :param bool js_dev_mode: Should @vitessce/dev be used (typically for debugging purposes)? By default, False.
+        :param str custom_js_url: A URL to a JavaScript file to use (instead of 'vitessce' or '@vitessce/dev' NPM package).
+        :param list[VitesscePlugin] plugins: A list of subclasses of VitesscePlugin. Optional.
+        :param bool remount_on_uid_change: Passed to the remountOnUidChange prop of the <Vitessce/> React component. By default, True.
+        :param bool prefer_local: Should local data be preferred (only applies to `*_artifact` data objects)? By default, True.
+        :param int invoke_timeout: The timeout in milliseconds for invoking Python functions from JavaScript. By default, 300000.
+        :param bool invoke_batched: Should invocations (Zarr gets) be submitted in batch, or individually? By default, True.
+        :param bool page_mode: Whether to render the <Vitessce/> component in grid-mode or page-mode. By default, False.
+        :param str page_esm: The ES module string for the page component creation function. Optional.
+        :param bool prevent_scroll: Should mouseover in the Vitessce widget prevent disable the scrolling of the notebook? By default, True.
 
         :returns: The Jupyter widget.
         :rtype: VitessceWidget

vitessce/widget.py

@@ -445,7 +445,7 @@ async function render(view) {
     function VitessceWidget(props) {
         const { model, styleContainer } = props;
 
-        const [config, setConfig] = React.useState(prependBaseUrl(model.get('config'), model.get('proxy'), model.get('has_host_name')));
+        const [config, setConfig] = React.useState(prependBaseUrl(model.get('_config'), model.get('proxy'), model.get('has_host_name')));
         const [validateConfig, setValidateConfig] = React.useState(true);
         const height = model.get('height');
         const theme = model.get('theme') === 'auto' ? (prefersDark ? 'dark' : 'light') : model.get('theme');
@@ -484,7 +484,7 @@ async function render(view) {
         // Config changed on JS side (from within <Vitessce/>),
         // send updated config to Python side.
         const onConfigChange = React.useCallback((config) => {
-            model.set('config', config);
+            model.set('_config', config);
             setValidateConfig(false);
             model.save_changes();
         }, [model]);
@@ -492,8 +492,8 @@ async function render(view) {
         // Config changed on Python side,
         // pass to <Vitessce/> component to it is updated on JS side.
         React.useEffect(() => {
-            model.on('change:config', () => {
-                const newConfig = prependBaseUrl(model.get('config'), model.get('proxy'), model.get('has_host_name'));
+            model.on('change:_config', () => {
+                const newConfig = prependBaseUrl(model.get('_config'), model.get('proxy'), model.get('has_host_name'));
 
                 // Force a re-render and re-validation by setting a new config.uid value.
                 // TODO: make this conditional on a parameter from Python.
@@ -597,8 +597,12 @@ class VitesscePlugin:
     """
     A class that represents a Vitessce widget plugin. Custom plugins can be created by subclassing this class.
     """
-    plugin_esm = DEFAULT_PLUGIN_ESM
-    commands = {}
+
+    #: The ES module string for the plugin.
+    plugin_esm = DEFAULT_PLUGIN_ESM  # type: str
+
+    #: A dictionary mapping command name strings to functions. Functions should take two arguments (message, buffers) and return a tuple (response, buffers).
+    commands = {}  # type: dict
 
     def on_config_change(self, new_config):
         """
@@ -614,7 +618,16 @@ class VitesscePlugin:
 
 class VitessceWidget(anywidget.AnyWidget):
     """
-    A class to represent a Jupyter widget for Vitessce.
+    A class to represent a Jupyter widget for Vitessce. Not intended to be instantiated directly; instead, use ``VitessceConfig.widget``.
+
+    .. code-block:: python
+        :emphasize-lines: 4
+
+        from vitessce import VitessceConfig
+
+        vc = VitessceConfig.from_object(my_scanpy_object)
+        vw = vc.widget()
+        vw
     """
     _esm = ESM
 
@@ -622,7 +635,13 @@ class VitessceWidget(anywidget.AnyWidget):
     # Widget properties are defined as traitlets. Any property tagged with `sync=True`
     # is automatically synced to the frontend *any* time it changes in Python.
     # It is synced back to Python from the frontend *any* time the model is touched.
-    config = Dict({}).tag(sync=True)
+
+    #: Dictionary representation of the Vitessce JSON configuration. Synced via traitlets upon interactions.
+    _config = Dict({}).tag(sync=True)  # type: dict
+
+    #: The VitessceConfig instance used to create this widget. Not synced upon interactions.
+    config = None  # type: vitessce.config.VitessceConfig
+
     height = Int(600).tag(sync=True)
     theme = Unicode('auto').tag(sync=True)
     proxy = Bool(False).tag(sync=True)
@@ -631,7 +650,7 @@ class VitessceWidget(anywidget.AnyWidget):
 
     next_port = DEFAULT_PORT
 
-    js_package_version = Unicode('3.6.11').tag(sync=True)
+    js_package_version = Unicode('3.6.12').tag(sync=True)
     js_dev_mode = Bool(False).tag(sync=True)
     custom_js_url = Unicode('').tag(sync=True)
     plugin_esm = List(trait=Unicode(''), default_value=[]).tag(sync=True)
@@ -644,9 +663,10 @@ class VitessceWidget(anywidget.AnyWidget):
 
     store_urls = List(trait=Unicode(''), default_value=[]).tag(sync=True)
 
-    def __init__(self, config, height=600, theme='auto', uid=None, port=None, proxy=False, js_package_version='3.6.11', js_dev_mode=False, custom_js_url='', plugins=None, remount_on_uid_change=True, prefer_local=True, invoke_timeout=300000, invoke_batched=True, page_mode=False, page_esm=None, prevent_scroll=True):
+    def __init__(self, config, height=600, theme='auto', uid=None, port=None, proxy=False, js_package_version='3.6.12', js_dev_mode=False, custom_js_url='', plugins=None, remount_on_uid_change=True, prefer_local=True, invoke_timeout=300000, invoke_batched=True, page_mode=False, page_esm=None, prevent_scroll=True):
+        """ """
         """
-        Construct a new Vitessce widget.
+        Construct a new Vitessce widget. Not intended to be instantiated directly; instead, use ``VitessceConfig.widget``.
 
         :param config: A view config instance.
         :type config: VitessceConfig
@@ -666,19 +686,16 @@ class VitessceWidget(anywidget.AnyWidget):
         :param str page_esm: The ES module string for the page component creation function. Optional.
         :param bool prevent_scroll: Should mouseover in the Vitessce widget prevent disable the scrolling of the notebook? By default, True.
 
-        .. code-block:: python
-            :emphasize-lines: 4
-
-            from vitessce import VitessceConfig, VitessceWidget
-
-            vc = VitessceConfig.from_object(my_scanpy_object)
-            vw = vc.widget()
-            vw
+        Note: these parameter docstrings need to be manually kept in sync with the VitessceConfig.widget docstring.
         """
 
         base_url, use_port, VitessceWidget.next_port = get_base_url_and_port(
             port, VitessceWidget.next_port, proxy=proxy)
-        self.config_obj = config
+        # Note:
+        # - self.config is the VitessceConfig instance.
+        # - self._config is the JSON configuration, synced via traitlets
+
+        self.config = config
         self.port = use_port
         config_dict = config.to_dict(base_url=base_url)
         routes = config.get_routes()
@@ -694,7 +711,7 @@ class VitessceWidget(anywidget.AnyWidget):
         uid_str = get_uid_str(uid)
 
         super(VitessceWidget, self).__init__(
-            config=config_dict, height=height, theme=theme, proxy=proxy,
+            _config=config_dict, height=height, theme=theme, proxy=proxy,
             js_package_version=js_package_version, js_dev_mode=js_dev_mode, custom_js_url=custom_js_url,
             plugin_esm=plugin_esm, remount_on_uid_change=remount_on_uid_change,
             page_mode=page_mode, page_esm=('' if page_esm is None else page_esm),
@@ -712,14 +729,14 @@ class VitessceWidget(anywidget.AnyWidget):
                     # It is optional for plugins to implement on_config_change.
                     pass
             if new_config is not None:
-                self.config = new_config
+                self._config = new_config
 
-        self.observe(handle_config_change, names=['config'])
+        self.observe(handle_config_change, names=['_config'])
 
         serve_routes(config, routes, use_port)
 
     def _get_coordination_value(self, coordination_type, coordination_scope):
-        obj = self.config['coordinationSpace'][coordination_type]
+        obj = self._config['coordinationSpace'][coordination_type]
         obj_scopes = list(obj.keys())
         if coordination_scope is not None:
             if coordination_scope in obj_scopes:
@@ -742,7 +759,7 @@ class VitessceWidget(anywidget.AnyWidget):
         return self._get_coordination_value('cellSelection', scope)
 
     def close(self):
-        self.config_obj.stop_server(self.port)
+        self.config.stop_server(self.port)
         super().close()
 
     @anywidget.experimental.command
@@ -780,7 +797,7 @@ class VitessceWidget(anywidget.AnyWidget):
 # Launch Vitessce using plain HTML representation (no ipywidgets)
 
 
-def ipython_display(config, height=600, theme='auto', base_url=None, host_name=None, uid=None, port=None, proxy=False, js_package_version='3.6.11', js_dev_mode=False, custom_js_url='', plugins=None, remount_on_uid_change=True, page_mode=False, page_esm=None):
+def ipython_display(config, height=600, theme='auto', base_url=None, host_name=None, uid=None, port=None, proxy=False, js_package_version='3.6.12', js_dev_mode=False, custom_js_url='', plugins=None, remount_on_uid_change=True, page_mode=False, page_esm=None):
     from IPython.display import display, HTML
     uid_str = "vitessce" + get_uid_str(uid)
 
@@ -808,7 +825,7 @@ def ipython_display(config, height=600, theme='auto', base_url=None, host_name=N
         "has_host_name": host_name is not None,
         "height": height,
         "theme": theme,
-        "config": config_dict,
+        "_config": config_dict,
         "store_urls": [],
     }
 

{vitessce-3.6.9.dist-info → vitessce-3.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vitessce
-Version: 3.6.9
+Version: 3.7.0
 Summary: Jupyter widget facilitating interactive visualization of spatial single-cell data with Vitessce
 Project-URL: repository, https://github.com/vitessce/vitessce-python
 Author-email: Mark Keller <mark_keller@hms.harvard.edu>

{vitessce-3.6.9.dist-info → vitessce-3.7.0.dist-info}/RECORD

@@ -1,5 +1,5 @@
 vitessce/__init__.py,sha256=GWGahpQMOGFotQXilRccGT0Bnn3OyoCQUCUphW_DtTI,1632
-vitessce/config.py,sha256=GLiFSYh-ACJvQhrEVu3-nqFj1HtlCF86V_mMDljvwFo,81206
+vitessce/config.py,sha256=0U10mtZZx_DBKM8AipD1Xw-L1hRgQcfOFASKHSGJ5BE,82949
 vitessce/config_converter.py,sha256=IRPnGPGaETvJbYZNUv2pe54SHHHsDY9VWo3JRjSI5FM,14681
 vitessce/constants.py,sha256=nBMH55TcnSavcpvYE-epyx3cJ0iDS31eHsL_1e9qb9M,15360
 vitessce/export.py,sha256=L7j5sVC0nBSqGocFWQyyHImSiAF4IjXhmqV1QtpuNc4,3874
@@ -8,7 +8,7 @@ vitessce/repr.py,sha256=qMmefmZ3E-3sRVxeI5q1DTZnfuwbXKiA85eyqk5MCT4,2287
 vitessce/responses.py,sha256=Z6Wo4AXN-RyzmxMPhSuhpIsHTItHM4GyIgMLGoVEYcU,339
 vitessce/routes.py,sha256=U8T-L-3QCD_tAbPF8LsUlSMhPWNbyzbLNUnxP9Z9s9o,2140
 vitessce/utils.py,sha256=obzjj65qsagu60_yuhGc-0jmHO-BW0Y-bDs0FgrBqLY,981
-vitessce/widget.py,sha256=AfTvp9tVlFJH8U-NX01xOEuHPtjuS7vRcN4UKsTs7P0,34985
+vitessce/widget.py,sha256=D4xrcIZWp_nZwaWe9X5rH2EThRBbECt1uYlRGYQpyXk,35898
 vitessce/wrappers.py,sha256=gbJggLGoFTRa1odnBvBDE5EspQ8vc_CpNq_eTbZBGSM,76091
 vitessce/data_utils/__init__.py,sha256=3mWi1lMjoj4_dNbhMOvyE-HEJu0qpMzcmkhfz_5T6n8,361
 vitessce/data_utils/anndata.py,sha256=iLa5-bRezHgBzL_XCHO7w0pc0RQ4urzZbDsqJbBYeCk,10668
@@ -18,7 +18,7 @@ vitessce/data_utils/ome.py,sha256=tJHlSHbZTxpjRgYfTxbYMS9zSnSHQwJVWPZpREAvHtU,55
 vitessce/widget_plugins/__init__.py,sha256=lto2GXnc7KwjIoT-jvzyRYLj0XTJG3uxoX45Hc9EcWA,82
 vitessce/widget_plugins/demo_plugin.py,sha256=14S7nOxdlKSxIHw9DUcNCN83NE_U1EMPy2D4k0FDues,1797
 vitessce/widget_plugins/spatial_query.py,sha256=CYxvmMT1Je_jguikPROQxlegkPgIIzemKGbZSJfZMyI,12314
-vitessce-3.6.9.dist-info/METADATA,sha256=XmyTy2_Zn6Nd5JezsYcOJ6jYPh_2gkhF4HfsSRdcNpc,9826
-vitessce-3.6.9.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-vitessce-3.6.9.dist-info/licenses/LICENSE,sha256=sNNpI0PQ57AW8_XnTAjU5Yw8YBA_DRNkVHrHYpCIhRU,1067
-vitessce-3.6.9.dist-info/RECORD,,
+vitessce-3.7.0.dist-info/METADATA,sha256=C_3I3Pgll9lUncQxm-jUKm3NA11AQWgcVzYE4yBoWJM,9826
+vitessce-3.7.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+vitessce-3.7.0.dist-info/licenses/LICENSE,sha256=sNNpI0PQ57AW8_XnTAjU5Yw8YBA_DRNkVHrHYpCIhRU,1067
+vitessce-3.7.0.dist-info/RECORD,,