cubevis 1.0.19__tar.gz → 1.0.21__tar.gz

{cubevis-1.0.19 → cubevis-1.0.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cubevis
-Version: 1.0.19
+Version: 1.0.21
 Summary: visualization toolkit and apps for casa
 License: LGPL
 Author-email: Darrell Schiebel <darrell@schiebel.us>,Pam Harris <pharris@nrao.edu>

{cubevis-1.0.19 → cubevis-1.0.21}/cubevis/bokeh/models/_bokeh_app_context.py

@@ -2,7 +2,13 @@ import logging
 from bokeh.core.properties import String, Dict, Any, Nullable, Instance
 from bokeh.models.layouts import LayoutDOM
 from bokeh.models.ui import UIElement
+from bokeh.resources import CDN
+from tempfile import TemporaryDirectory
 from uuid import uuid4
+import unicodedata
+import webbrowser
+import os
+import re
 
 logger = logging.getLogger(__name__)
 
@@ -29,9 +35,34 @@ class BokehAppContext(LayoutDOM):
             cls._session_id = str(uuid4())
         return cls._session_id
 
-    def __init__( self, ui=None, **kwargs ):
+    def _slugify(self, value, allow_unicode=False):
+        """
+        Taken from https://github.com/django/django/blob/master/django/utils/text.py
+        Convert to ASCII if 'allow_unicode' is False. Convert spaces or repeated
+        dashes to single dashes. Remove characters that aren't alphanumerics,
+        underscores, or hyphens. Convert to lowercase. Also strip leading and
+        trailing whitespace, dashes, and underscores.
+        https://stackoverflow.com/a/295466/2903943
+        """
+        value = str(value)
+        if allow_unicode:
+            value = unicodedata.normalize('NFKC', value)
+        else:
+            value = unicodedata.normalize('NFKD', value).encode('ascii', 'ignore').decode('ascii')
+        value = re.sub(r'[^\w\s-]', '', value.lower())
+        return re.sub(r'[-\s]+', '-', value).strip('-_')
+
+    def __init__( self, ui=None, title=str(uuid4( )), prefix=None, **kwargs ):
         logger.debug(f"\tBokehAppContext::__init__(ui={type(ui).__name__ if ui else None}, {kwargs}): {id(self)}")
 
+        if prefix is None:
+            ## create a prefix from the title
+            prefix = self._slugify(title)[:10]
+
+        self.__title = title
+        self.__workdir = TemporaryDirectory(prefix=prefix)
+        self.__htmlpath = os.path.join( self.__workdir.name, f'''{self._slugify(self.__title)}.html''' )
+
         if ui is not None and 'ui' in kwargs:
             raise RuntimeError( "'ui' supplied as both a positional parameter and a keyword parameter" )
 
@@ -61,3 +92,19 @@ class BokehAppContext(LayoutDOM):
         current_state = dict(self.app_state)
         current_state.update(state_updates)
         self.app_state = current_state
+
+    def show( self ):
+        """Always show plot in a new browser tab without changing output settings.
+           Jupyter display is handled by the Showable class. However, at some
+           point this function might need to support more than just independent
+           browser tab display.
+        """
+        logger.debug(f"\tBokehAppContext::show( ): {id(self)}")
+
+        from bokeh.plotting import save
+
+        # Save the plot
+        save( self, filename=self.__htmlpath, resources=CDN, title=self.__title)
+
+        # Open in browser
+        webbrowser.open('file://' + os.path.abspath(self.__htmlpath))

{cubevis-1.0.19 → cubevis-1.0.21}/cubevis/bokeh/models/_showable.py

@@ -48,39 +48,11 @@ class Showable(LayoutDOM,BokehInit):
                 # It might be a regular function or static method without explicit 'self'/'cls'
                 return None
 
-        # Detect Bokeh usage mode (i.e. self.__class__._usage_mode unset)
-        calling_mode = None
-        if self.__class__._usage_mode is None:
-            self.__class__._usage_mode = "bokeh"
-            calling_mode = "bokeh"
-
         # Allow None (detaching from document) without any further checking
         if doc is None:
             self._document = None
             return
 
-        if calling_mode is None:
-            import inspect
-            stack_frames = inspect.stack( )
-            try:
-                for frame in stack_frames[1:]:
-                    if frame.function == '_repr_mimebundle_' or frame.function == 'show':
-                        if get_caller_class_name(frame.frame) == self.__class__.__name__:
-                            calling_mode = "custom"
-                            break
-            finally:
-                # Essential to delete stack frames to avoid reference cycles
-                del stack_frames
-
-        if calling_mode != self.__class__._usage_mode:
-            ###  THIS CATCHES:   using Bokeh show after Showable display methods
-            ###                  using Showable.show after Bokeh show
-            raise RuntimeError(
-                f"\n{'='*70}\n" +
-                ( (self._usage_error['custom'] % self.__class__.__name__) if calling_mode == 'custom' else
-                  (self._usage_error['bokeh'] % 'bokeh.plotting.show') ) +
-                f"\n{'='*70}\n" )
-
         from bokeh.io.state import curstate
         state = curstate( )
 
@@ -118,12 +90,23 @@ class Showable(LayoutDOM,BokehInit):
             self._start_backend()
             self._backend_started = True
 
+    def to_serializable(self, *args, **kwargs):
+        if self._display_context:
+            self._display_context.on_to_serializable( )
+
+        # Call parent's to_serializable
+        return super().to_serializable(*args, **kwargs)
+
     def __init__( self, ui_element=None, backend_func=None,
                   result_retrieval=None,
                   notebook_width=1200, notebook_height=800,
-                  notebook_sizing='fixed', **kwargs):
+                  notebook_sizing='fixed',
+                  display_context=None,
+                  **kwargs ):
         logger.debug(f"\tShowable::__init__(ui_element={type(ui_element).__name__ if ui_element else None}, {kwargs}): {id(self)}")
 
+        self._display_context = display_context
+
         # Set default sizing if not provided
         sizing_params = {'sizing_mode', 'width', 'height'}
         provided_sizing_params = set(kwargs.keys()) & sizing_params
@@ -147,18 +130,6 @@ class Showable(LayoutDOM,BokehInit):
             'browser': { 'mode': self.sizing_mode, 'width': self.width, 'height': self.height }
         }
 
-        # Error messages included in RuntimeErrors
-        self._usage_error = {
-            'custom': "❌ Cannot use %s display methods:\n\n" \
-                      "Reason: bokeh.plotting.show() has already been used for display\n" \
-                      "        of this class. Mixing display methods within a single notebook\n" \
-                      "        corrupts Bokeh display within the notebook\n",
-            'bokeh':  "❌ Cannot use %s display method:\n\n" \
-                      "Reason: Showable display methods have already been used for display\n" \
-                      "        of this class. Mixing display methods within a single notebook\n" \
-                      "        corrupts Bokeh display within the notebook\n" }
-
-
         # Set the function to be called upon display
         if backend_func is not None:
             self._backend_startup_callback = backend_func
@@ -304,13 +275,6 @@ class Showable(LayoutDOM,BokehInit):
         from bokeh.embed import components
         from bokeh.io.state import curstate
 
-        if self.__class__._usage_mode != "custom":
-            ###  THIS CATCHES:   Showable display via evaluation ( "ic" ) after Bokeh show
-            raise RuntimeError(
-                f"\n{'='*70}\n" +
-                (self._usage_error['custom'] % self.__class__.__name__) +
-                f"\n{'='*70}\n" )
-
         state = curstate()
 
         if not state.notebook:
@@ -319,6 +283,9 @@ class Showable(LayoutDOM,BokehInit):
         if self.ui is None:
             return '<div style="color: red; padding: 10px; border: 1px solid red;">Showable object with no UI set</div>'
 
+        if self._display_context:
+            self._display_context.on_show( )
+
         if self._notebook_rendering:
             # Return a lightweight reference instead of re-rendering the full GUI
             return f'''

{cubevis-1.0.19 → cubevis-1.0.21}/cubevis/private/apps/_createmask.py

@@ -35,7 +35,7 @@ from contextlib import asynccontextmanager
 from bokeh.layouts import row, column
 from bokeh.plotting import show
 from bokeh.models import Button, CustomJS, TabPanel, Tabs, Spacer, Div
-from cubevis.toolbox import CubeMask, AppContext
+from cubevis.toolbox import CubeMask
 from cubevis.bokeh.utils import svg_icon
 from bokeh.io import reset_output as reset_bokeh_output
 from bokeh.io import output_notebook
@@ -149,12 +149,6 @@ class CreateMask:
             if False a mask path which does not exist results in an exception
         '''
 
-        ###
-        ### Create application context (which includes a temporary directory).
-        ### This sets the title of the plot.
-        ###
-        self._app_state = AppContext( 'Create Mask' )
-
         ###
         ### widgets shared across image tabs (masking multiple images)
         ###
@@ -382,7 +376,7 @@ class CreateMask:
             app_state={                         ### while the state dictionary itself
                 'name': 'create mask',          ### is used, these particular element
                 'initialized': True             ### are not currently used for anything
-            } )
+            }, title='Create Mask' )
 
         ###
         ### Keep track of which image is currently active in appstate.image_name (which is
@@ -411,7 +405,7 @@ class CreateMask:
 ###         output_file(self._imagename+'_webpage/index.html')
             pass
 
-        show(self._fig['layout'])
+        self._fig['layout'].show( )
 
     def _asyncio_loop( self ):
         '''return the event loop which can be mixed in with an existing event loop

{cubevis-1.0.19 → cubevis-1.0.21}/cubevis/private/apps/_createregion.py

@@ -35,7 +35,7 @@ from contextlib import asynccontextmanager
 from bokeh.layouts import row, column, grid
 from bokeh.plotting import show
 from bokeh.models import Button, CustomJS, TabPanel, Tabs, Spacer, Div, Dropdown
-from cubevis.toolbox import CubeMask, AppContext, RegionList
+from cubevis.toolbox import CubeMask, RegionList
 from cubevis.bokeh.utils import svg_icon
 from bokeh.io import curdoc
 from bokeh.io import reset_output as reset_bokeh_output
@@ -141,12 +141,6 @@ class CreateRegion:
             path(s) to CASA image for which interactive regions will be drawn
         '''
 
-        ###
-        ### Create application context (which includes a temporary directory).
-        ### This sets the title of the plot.
-        ###
-        self._app_state = AppContext( 'Create Region' )
-
         ###
         ### widgets shared across image tabs (masking multiple images)
         ###
@@ -435,7 +429,7 @@ class CreateRegion:
             app_state={                         ### while the state dictionary itself
                 'name': 'create region',        ### is used, these particular element
                 'initialized': True             ### are not currently used for anything
-            } )
+            }, title='Create Region' )
 
         ###
         ### Keep track of which image is currently active in appstate.image_name (which is
@@ -464,7 +458,7 @@ class CreateRegion:
 ###         output_file(self._imagename+'_webpage/index.html')
             pass
 
-        show(self._fig['layout'])
+        self._fig['layout'].show( )
 
     def _asyncio_loop( self ):
         '''return the event loop which can be mixed in with an existing event loop

{cubevis-1.0.19 → cubevis-1.0.21}/cubevis/private/apps/_interactiveclean.mustache

@@ -87,7 +87,8 @@ class InteractiveClean:
                                interpolation='nearest', ... )( ) )
         '''
         self._id = uuid4( )
+        self._ui.exclusion_mgr.set_mode("tab")
         context = exe.Context( exe.Mode.SYNC )
         bokeh_ui, exec_task = self._ui( context, self._id )
-        show(bokeh_ui)
+        bokeh_ui.show( )
         return context.execute( exec_task, self._id )

{cubevis-1.0.19 → cubevis-1.0.21}/cubevis/private/apps/_interactiveclean.py

@@ -1849,7 +1849,8 @@ class InteractiveClean:
                                interpolation='nearest', ... )( ) )
         '''
         self._id = uuid4( )
+        self._ui.exclusion_mgr.set_mode("tab")
         context = exe.Context( exe.Mode.SYNC )
         bokeh_ui, exec_task = self._ui( context, self._id )
-        show(bokeh_ui)
+        bokeh_ui.show( )
         return context.execute( exec_task, self._id )

{cubevis-1.0.19 → cubevis-1.0.21}/cubevis/private/apps/_interactivecleannotebook.mustache

@@ -43,6 +43,22 @@ from cubevis.utils import find_pkg, load_pkg
 from cubevis.toolbox import InteractiveCleanUI
 from cubevis import exe
 
+class DisplayContext:
+    def __init__(self, exclusion_manager):
+        self.exclusion_manager = exclusion_manager
+        self._custom_show_called = False
+
+    def on_show(self):
+        self._custom_show_called = True
+        self.exclusion_manager.set_mode('cell-custom-show')
+
+    def on_to_serializable(self):
+        # Only set mode if custom_show hasn't been called
+        if not self._custom_show_called:
+            self.exclusion_manager.set_mode('cell-bokeh-show')
+        # If custom_show was called, we're already in 'cell-custom-show' mode
+        # and don't need to do anything
+
 class InteractiveCleanNotebook:
     r'''InteractiveCleanNotebook(...) implements interactive clean using Bokeh
     {{docstring}}
@@ -107,6 +123,13 @@ class InteractiveCleanNotebook:
         def startup( ):
             self._future = context.execute( exec_task, self._id )
 
+        display_ctx = DisplayContext(self._ui.exclusion_mgr)
         ### name is used in summary output of the Showable
-        showed = Showable(bokeh_ui, startup, self.get_future, name="iclean-jpy")
+        showed = Showable(
+            bokeh_ui,
+            startup,
+            self.get_future,
+            name="iclean-jpy",
+            display_context=display_ctx
+        )
         return showed

{cubevis-1.0.19 → cubevis-1.0.21}/cubevis/private/apps/_interactivecleannotebook.py

@@ -42,6 +42,22 @@ from cubevis.utils import find_pkg, load_pkg
 from cubevis.toolbox import InteractiveCleanUI
 from cubevis import exe
 
+class DisplayContext:
+    def __init__(self, exclusion_manager):
+        self.exclusion_manager = exclusion_manager
+        self._custom_show_called = False
+
+    def on_show(self):
+        self._custom_show_called = True
+        self.exclusion_manager.set_mode('cell-custom-show')
+
+    def on_to_serializable(self):
+        # Only set mode if custom_show hasn't been called
+        if not self._custom_show_called:
+            self.exclusion_manager.set_mode('cell-bokeh-show')
+        # If custom_show was called, we're already in 'cell-custom-show' mode
+        # and don't need to do anything
+
 class InteractiveCleanNotebook:
     r'''InteractiveCleanNotebook(...) implements interactive clean using Bokeh
         tclean ---- Radio Interferometric Image Reconstruction
@@ -1869,6 +1885,13 @@ class InteractiveCleanNotebook:
         def startup( ):
             self._future = context.execute( exec_task, self._id )
 
+        display_ctx = DisplayContext(self._ui.exclusion_mgr)
         ### name is used in summary output of the Showable
-        showed = Showable(bokeh_ui, startup, self.get_future, name="iclean-jpy")
+        showed = Showable(
+            bokeh_ui,
+            startup,
+            self.get_future,
+            name="iclean-jpy",
+            display_context=display_ctx
+        )
         return showed

{cubevis-1.0.19 → cubevis-1.0.21}/cubevis/toolbox/__init__.py

@@ -28,6 +28,5 @@
 '''Common tools used in creating applications.'''
 
 from ._cube import CubeMask
-from ._app_context import AppContext
 from ._region_list import RegionList
 from ._interactive_clean_ui import InteractiveCleanUI

{cubevis-1.0.19 → cubevis-1.0.21}/cubevis/toolbox/_cube.py

@@ -1513,18 +1513,24 @@ class CubeMask:
                                                                             ##     """console.log("Running from script/terminal. Closing window.")
                                                                             ##        window.close()"""
                                                                             ##) +
-                                                                            ( """if ( showable ) {
-                                                                                      console.log("Running in jupyter notebook.\\nDisabling GUI via root Showable.")
-                                                                                      showable.disabled = true
-                                                                                      const data_pipes = Bokeh.activeDataPipes.getInstances( )
-                                                                                      console.log("Data pipes to be closed:", data_pipes)
+                                                                            ###
+                                                                            ###  Previously the Python is_interactive_jupyter( ) function was used
+                                                                            ###  to decide whether the window should be closed or not. However, to
+                                                                            ###  support the use of the regular iclean (i.e. display in a separate
+                                                                            ###  browser tab) the check is now whether a showable is available or
+                                                                            ###  not since Showable is the coupling between GUIs and Jupyter
+                                                                            ###  notebooks.
+                                                                            ###
+                                                                            """if ( showable ) {
+                                                                                     console.log("Running in jupyter notebook.\\nDisabling GUI via root Showable.")
+                                                                                     showable.disabled = true
+                                                                                     const data_pipes = Bokeh.activeDataPipes.getInstances( )
+                                                                                     console.log("Data pipes to be closed:", data_pipes)
                                                                                  } else {
-                                                                                     console.log("Running in jupyter notebook.\\nCannot find root Showable so cannot disable GUI.")
+                                                                                     console.log("Running from script/terminal. Closing window.")
+                                                                                     window.close()
                                                                                  }
-                                                                              """ if is_interactive_jupyter( ) else
-                                                                              """console.log("Running from script/terminal. Closing window.")
-                                                                                 window.close()"""
-                                                                            ) +
+                                                                              """ +
                                                                     """
                                                                               }
                                                                           }

{cubevis-1.0.19 → cubevis-1.0.21}/cubevis/toolbox/_interactive_clean_ui.mustache

@@ -53,6 +53,7 @@ from cubevis.bokeh.models import TipButton, Tip, EvTextInput, BokehAppContext
 
 from cubevis.utils import resource_manager, reset_resource_manager, is_interactive_jupyter, find_pkg, load_pkg
 from cubevis.utils import ContextMgrChain as CMC
+from cubevis.utils import MutualExclusionManager
 
 # pylint: disable=no-name-in-module
 from casatasks.private.imagerhelpers.imager_return_dict import ImagingDict
@@ -61,7 +62,7 @@ from casatasks.private.imagerhelpers.input_parameters import ImagerParameters
 # pylint: enable=no-name-in-module
 
 from cubevis.utils import find_ws_address, convert_masks
-from cubevis.toolbox import CubeMask, AppContext
+from cubevis.toolbox import CubeMask
 from cubevis.bokeh.utils import svg_icon
 from cubevis.bokeh.sources import DataPipe
 from cubevis.utils import DocEnum
@@ -74,6 +75,25 @@ USE_MULTIPLE_GCLEAN_HACK=False
 class InteractiveCleanUI:
     '''InteractiveCleanUI(...) implements interactive clean using Bokeh
     '''
+
+    exclusion_mgr = MutualExclusionManager(
+        name="interactive clean",
+        valid_modes={
+            "tab":              "❌ Cannot use iclean task display:\n\n" \
+                                "Reason: bokeh.plotting.show() or iclean show method has already been\n" \
+                                "        used for display of this class. Mixing display methods within\n" \
+                                "        a single notebook corrupts Bokeh display within the notebook\n",
+            "cell-bokeh-show":  "❌ Cannot use bokeh.plotting.show() display method:\n\n" \
+                                "Reason: iclean show or task method has already been used for display\n" \
+                                "        of this class. Mixing display methods within a single notebook\n" \
+                                "        corrupts Bokeh display within the notebook\n",
+            "cell-custom-show": "❌ Cannot use iclean show method:\n\n" \
+                                "Reason: bokeh.plotting.show() or task has already been used for display\n" \
+                                "        of this class. Mixing display methods within a single notebook\n" \
+                                "        corrupts Bokeh display within the notebook\n",
+        }
+    )
+
     def __stop( self, _=None ):
         self.__result_future.set_result(self.__retrieve_result( ))
 
@@ -164,11 +184,6 @@ class InteractiveCleanUI:
         ### the image display.
         ###
         self._conv_spect_plot_width = 450
-        ###
-        ### Create application context (which includes a temporary directory).
-        ### This sets the title of the plot.
-        ###
-        self._app_state = AppContext( 'Interactive Clean' )
 
         ###
         ### Whether or not the Interactive Clean session is running remotely
@@ -948,7 +963,7 @@ class InteractiveCleanUI:
             app_state={                         ### while the state dictionary itself
                 'name': 'interactive clean',    ### is used, these particular element
                 'initialized': True             ### are not currently used for anything
-            } )
+            }, title='Interactive Clean' )
 
         ###
         ### Keep track of which image is currently active in appstate.image_name (which is

{cubevis-1.0.19 → cubevis-1.0.21}/cubevis/toolbox/_interactive_clean_ui.py

@@ -52,6 +52,7 @@ from cubevis.bokeh.models import TipButton, Tip, EvTextInput, BokehAppContext
 
 from cubevis.utils import resource_manager, reset_resource_manager, is_interactive_jupyter, find_pkg, load_pkg
 from cubevis.utils import ContextMgrChain as CMC
+from cubevis.utils import MutualExclusionManager
 
 # pylint: disable=no-name-in-module
 from casatasks.private.imagerhelpers.imager_return_dict import ImagingDict
@@ -60,7 +61,7 @@ from casatasks.private.imagerhelpers.input_parameters import ImagerParameters
 # pylint: enable=no-name-in-module
 
 from cubevis.utils import find_ws_address, convert_masks
-from cubevis.toolbox import CubeMask, AppContext
+from cubevis.toolbox import CubeMask
 from cubevis.bokeh.utils import svg_icon
 from cubevis.bokeh.sources import DataPipe
 from cubevis.utils import DocEnum
@@ -73,6 +74,25 @@ USE_MULTIPLE_GCLEAN_HACK=False
 class InteractiveCleanUI:
     '''InteractiveCleanUI(...) implements interactive clean using Bokeh
     '''
+
+    exclusion_mgr = MutualExclusionManager(
+        name="interactive clean",
+        valid_modes={
+            "tab":              "❌ Cannot use iclean task display:\n\n" \
+                                "Reason: bokeh.plotting.show() or iclean show method has already been\n" \
+                                "        used for display of this class. Mixing display methods within\n" \
+                                "        a single notebook corrupts Bokeh display within the notebook\n",
+            "cell-bokeh-show":  "❌ Cannot use bokeh.plotting.show() display method:\n\n" \
+                                "Reason: iclean show or task method has already been used for display\n" \
+                                "        of this class. Mixing display methods within a single notebook\n" \
+                                "        corrupts Bokeh display within the notebook\n",
+            "cell-custom-show": "❌ Cannot use iclean show method:\n\n" \
+                                "Reason: bokeh.plotting.show() or task has already been used for display\n" \
+                                "        of this class. Mixing display methods within a single notebook\n" \
+                                "        corrupts Bokeh display within the notebook\n",
+        }
+    )
+
     def __stop( self, _=None ):
         self.__result_future.set_result(self.__retrieve_result( ))
 
@@ -163,11 +183,6 @@ class InteractiveCleanUI:
         ### the image display.
         ###
         self._conv_spect_plot_width = 450
-        ###
-        ### Create application context (which includes a temporary directory).
-        ### This sets the title of the plot.
-        ###
-        self._app_state = AppContext( 'Interactive Clean' )
 
         ###
         ### Whether or not the Interactive Clean session is running remotely
@@ -947,7 +962,7 @@ class InteractiveCleanUI:
             app_state={                         ### while the state dictionary itself
                 'name': 'interactive clean',    ### is used, these particular element
                 'initialized': True             ### are not currently used for anything
-            } )
+            }, title='Interactive Clean' )
 
         ###
         ### Keep track of which image is currently active in appstate.image_name (which is

{cubevis-1.0.19 → cubevis-1.0.21}/cubevis/utils/__init__.py

@@ -67,6 +67,7 @@ from ._static import static_vars, static_dir
 from ._tiles import TMSTiles
 from ._contextmgrchain import ContextMgrChain
 from ._import_protected_module import ImportProtectedModule
+from ._mutual_exclusion import MutualExclusionManager
 
 @static_vars(mgr=None)
 def resource_manager( ):

cubevis-1.0.21/cubevis/utils/_mutual_exclusion.py

@@ -0,0 +1,117 @@
+import threading
+from typing import Dict
+
+
+class MutualExclusionManager:
+    """
+    Generic manager for enforcing mutual exclusion between different execution paths.
+
+    Use this when you want to ensure only one of several mutually exclusive paths
+    can be taken within a given context (thread).
+
+    Example:
+        mode_manager = MutualExclusionManager(
+            name="display_mode",
+            valid_modes={
+                'notebook': "Cannot use Showable after displaying with bokeh.plotting.show().",
+                'separate_tab': "Cannot use bokeh.plotting.show() after displaying with Showable."
+            }
+        )
+
+        # In path A:
+        mode_manager.set_mode('notebook')
+
+        # In path B (will raise error if path A was already taken):
+        mode_manager.set_mode('separate_tab')
+    """
+
+    def __init__(self, name: str, valid_modes: Dict[str, str]):
+        """
+        Args:
+            name: Descriptive name for this manager (used in error messages)
+            valid_modes: Dictionary mapping mode names to error messages to display
+                        when that mode conflicts with an already-set mode.
+        """
+        self.name = name
+        self.valid_modes = valid_modes
+        self._local = threading.local()
+
+    def set_mode(self, mode: str):
+        """
+        Set the execution mode. Raises RuntimeError if a different mode was already set.
+
+        Args:
+            mode: The mode identifier to set
+
+        Raises:
+            ValueError: If mode is not in valid_modes
+            RuntimeError: If a different mode was already set in this context
+        """
+        if mode not in self.valid_modes:
+            raise ValueError(
+                f"Invalid mode '{mode}' for {self.name}. "
+                f"Valid modes: {set(self.valid_modes.keys())}"
+            )
+
+        current_mode = self.get_mode()
+        if current_mode is not None and current_mode != mode:
+            # Use the error message associated with the mode being set
+            error_message = self.valid_modes[mode]
+            raise RuntimeError(error_message)
+
+        self._local.mode = mode
+
+    def get_mode(self) -> str | None:
+        """
+        Get the current mode, or None if no mode has been set.
+
+        Returns:
+            The current mode string, or None
+        """
+        return getattr(self._local, 'mode', None)
+
+    def require_mode(self, mode: str):
+        """
+        Check that we're in the specified mode, set it if unset, error if different.
+
+        This is a convenience method that combines get_mode checking with set_mode.
+
+        Args:
+            mode: The required mode
+
+        Raises:
+            RuntimeError: If a different mode was already set
+        """
+        self.set_mode(mode)
+
+    def forbid_mode(self, mode: str, message: str | None = None):
+        """
+        Raise an error if the current mode matches the specified mode.
+
+        Args:
+            mode: The mode to forbid
+            message: Optional custom error message. If None, uses the message from valid_modes.
+
+        Raises:
+            RuntimeError: If current mode matches the forbidden mode
+        """
+        current_mode = self.get_mode()
+        if current_mode == mode:
+            if message is None:
+                message = self.valid_modes.get(
+                    mode,
+                    f"Cannot proceed: {self.name} is set to '{mode}', "
+                    f"which is not allowed in this context."
+                )
+            raise RuntimeError(message)
+
+    def reset(self):
+        """
+        Reset the mode for this context. Useful for testing or manual mode switching.
+        """
+        if hasattr(self._local, 'mode'):
+            del self._local.mode
+
+    def __repr__(self):
+        mode = self.get_mode()
+        return f"MutualExclusionManager(name='{self.name}', current_mode={mode!r})"