cubevis 0.5.2__py3-none-any.whl

cubevis/bokeh/sources/_updatable_data_source.py

@@ -0,0 +1,189 @@
+########################################################################
+#
+# Copyright (C) 2025
+# Associated Universities, Inc. Washington DC, USA.
+#
+# This script is free software; you can redistribute it and/or modify it
+# under the terms of the GNU Library General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or (at your
+# option) any later version.
+#
+# This library is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Library General Public License
+# along with this library; if not, write to the Free Software Foundation,
+# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
+#
+# Correspondence concerning AIPS++ should be adressed as follows:
+#        Internet email: casa-feedback@nrao.edu.
+#        Postal address: AIPS++ Project Office
+#                        National Radio Astronomy Observatory
+#                        520 Edgemont Road
+#                        Charlottesville, VA 22903-2475 USA
+#
+########################################################################
+'''Specialization of the Bokeh ``DataSource`` which allows for update via WebSockets.'''
+
+from uuid import uuid4
+from sys import stderr
+from contextlib import asynccontextmanager
+from bokeh.plotting import ColumnDataSource
+from bokeh.core.properties import Instance, String, Nullable
+from bokeh.models.callbacks import Callback
+from bokeh.models import CustomJS
+import websockets
+from ._data_pipe import DataPipe
+from ..state import casalib_url, cubevisjs_url
+from ...utils import find_ws_address
+
+class UpdatableDataSource(ColumnDataSource):
+    """Implementation of a `ColumnDataSource` customized to allow updates from Python via
+    WebSockets after the Bokeh GUI has been displayed. This class is derived from `ColumnDataSource`
+    and provides an `update` function that can be used to update the plotted data. While this
+    is useful when Bokeh is used directly in a Python session, the `stream` function provided
+    by `ColumnDataSource` should be used to update plots which are implemented using the Bokeh
+    server. This function can be used for plots which may displayed and managed directly from an
+    interactive Python session via `asyncio`. However, even in this case it may be more performant
+    to include all of the initial plot points when creating the data source. Future updates in
+    response to user interaction could be accomplished using this class.
+
+    This class allows the use to specify `js_init` code that is run in the browser when this
+    class is initialized there. The JavaScript implementation provides default code which is
+    run in the browser when the user calls the `update` function from Python. This code works
+    for single dimemsion data by simply appending the supplied updates to the end of the existing
+    plot data. If the user supplies an implementation for `js_update` then this code is used
+    in preference to the simple, default implementation. In the future the default update
+    implementation may be expanded to be more useful for 2D plots.
+
+    Attributes
+    ----------
+    js_init: CustomJS
+        JavaScript code to be run when this DataSource is loaded
+    js_update: CustomJS
+        JavaScript code to be run to update the data
+    pipe: DataPipe
+        Optional attribute that allows the user to specify a reused DataPipe
+    data:
+        INHERITED contains the data provided by this DataSource
+    """
+
+    js_init = Nullable(Instance(Callback), help="""
+    JavaScript to be run during initialization of an instance of this DataSource object.
+    """)
+
+    js_update = Nullable(Instance(Callback), help="""
+    JavaScript to be run to update during initialization of an instance of this DataSource object.
+    The default behavior is to append to the existing data.
+    """)
+
+    pipe = Instance(DataPipe, help="""
+    Optional attribute that allows for reusing a single DataPipe for multiple purposes
+    """ )
+
+    session_id = String( help="""
+    Internal id used for communcations.
+    """ )
+
+    __javascript__ = [ casalib_url( ), cubevisjs_url( ) ]
+
+    __created_pipe = False
+    __id = str(uuid4( ))
+    __user_init = None
+
+    def __init__( self, *args,
+                  callback=None,
+                  **kwargs ):
+
+        ### websocket communication id
+        kwargs['session_id'] = self.__id
+
+        if 'pipe' not in kwargs:
+            kwargs['pipe'] = DataPipe( address=find_ws_address( ) ) #, abort=abort )
+            self.__created_pipe = True
+        if 'js_init' in kwargs:
+            self.__user_init = kwargs['js_init']
+
+        kwargs['js_init'] = CustomJS( args=dict( userinit=self.__user_init ),
+                                      code='''this._data_keys = casalib.reduce(
+                                                  (acc,key,value) => {
+                                                      if ( Array.isArray(value) ) acc.push( key )
+                                                      return acc }, this.data, [ ] )
+
+                                              this.pipe.register( this.session_id,
+                                                                  ( msg ) => {
+                                                                      // [...array1, ...array2]
+                                                                      if ( ! ('data' in msg) )
+                                                                          return { result: 'error', msg: 'expected to find "data" in message' }
+                                                                      for (const k of this._data_keys) {
+                                                                          if ( ! (k in msg.data) )
+                                                                              return { result: 'error', msg: `expected "${k}" field in update "data"` }
+                                                                      }
+                                                                      if ( this.js_update ) {
+                                                                          this.js_update.execute( this, { data: msg.data } ).then(
+                                                                             (data) => { this.data = data } )
+                                                                      } else {
+                                                                          const data_update = { }
+                                                                          for (const k of this._data_keys) {
+                                                                              const existing = this.data[k]
+                                                                              const addition = msg.data[k]
+                                                                              data_update[k] = [...existing, ...addition]
+                                                                          }
+                                                                          this.data = data_update
+                                                                      }
+                                                                      return { result: 'success',
+                                                                               msg: casalib.reduce(
+                                                                                        (acc,key,value) => {
+                                                                                            if ( ! ( key in this.data ) )
+                                                                                                acc[key] = value
+                                                                                            return acc
+                                                                                        }, msg.data, { } ) }
+                                                                  } )
+
+                                              window.addEventListener(
+                                                  'beforeunload',
+                                                  (event) => {
+                                                      function send_shutdown(id,pipe) {
+                                                          return new Promise((resolve) =>
+                                                              pipe.send( id, { action: 'stop' },
+                                                                         (msg) => { resolve(msg) } ) )
+                                                      }
+                                                      send_shutdown(this.session_id,this.pipe).then(
+                                                          (result) => { console.log(`Shutdown Result: ${result}`) } )
+                                                  } )
+
+                                              if ( userinit != null ) {
+                                                  void userinit.execute( this )
+                                              }''' )
+
+        super( ).__init__( *args, **kwargs )
+        self.__callback = callback
+        self.__stop = None
+
+        async def manage_requests( msg, self=self ):
+            result = 'OK'
+            if self.__stop and 'action' in msg and msg['action'] == 'stop':
+                self.__stop( msg )
+            elif self.__callback and 'action' in msg and 'message' in msg and msg['action'] == 'callback':
+                result = await self.__callback( msg['message'] )
+            return { 'result': result }
+
+        self.pipe.register( self.__id, manage_requests )
+
+    async def update( self, data, callback=None ):
+        def default_callback( msg, self=self ):
+            if msg['result'] == 'error':
+                print( f'''UpdatableDataSource Error: {msg['msg']}''', file=stderr )
+        await self.pipe.send( self.__id, { 'action': 'append', 'data': data }, default_callback if callback is None else callback )
+
+    @asynccontextmanager
+    async def serve( self, stop_function ):
+        self.__stop = stop_function
+        if not self.__created_pipe:
+            raise RuntimeError( 'UpdatableDataSource.serve should only be called for when a "pipe" is NOT supplied as part of initialization' )
+
+        self._stop_serving_function = stop_function
+        async with websockets.serve( self.pipe.process_messages, self.pipe.address[0], self.pipe.address[1] ) as msgpipe:
+            yield { 'msgpipe': msgpipe }

cubevis/bokeh/state/__init__.py

@@ -0,0 +1,34 @@
+########################################################################
+#
+# Copyright (C) 2022
+# Associated Universities, Inc. Washington DC, USA.
+#
+# This script is free software; you can redistribute it and/or modify it
+# under the terms of the GNU Library General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or (at your
+# option) any later version.
+#
+# This library is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Library General Public License
+# along with this library; if not, write to the Free Software Foundation,
+# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
+#
+# Correspondence concerning AIPS++ should be adressed as follows:
+#        Internet email: casa-feedback@nrao.edu.
+#        Postal address: AIPS++ Project Office
+#                        National Radio Astronomy Observatory
+#                        520 Edgemont Road
+#                        Charlottesville, VA 22903-2475 USA
+#
+########################################################################
+'''Bokeh state management functions (both within the Bokeh distribution
+and with the Bokeh extensions found in ``cubevis.bokeh``.'''
+
+from ._initialize import initialize_bokeh
+from ._session import setup_session as initialize_session
+from ._palette import available_palettes, find_palette, default_palette
+from ._javascript import casalib_url, cubevisjs_url

cubevis/bokeh/state/_initialize.py

@@ -0,0 +1,164 @@
+########################################################################
+#
+# Copyright (C) 2021,2022,2023
+# Associated Universities, Inc. Washington DC, USA.
+#
+# This script is free software; you can redistribute it and/or modify it
+# under the terms of the GNU Library General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or (at your
+# option) any later version.
+#
+# This library is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Library General Public License
+# along with this library; if not, write to the Free Software Foundation,
+# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
+#
+# Correspondence concerning AIPS++ should be adressed as follows:
+#        Internet email: casa-feedback@nrao.edu.
+#        Postal address: AIPS++ Project Office
+#                        National Radio Astronomy Observatory
+#                        520 Edgemont Road
+#                        Charlottesville, VA 22903-2475 USA
+#
+########################################################################
+'''This contains functions to inject the ``cubevisjs`` library into the
+generated HTML that is used to display the Bokeh plots that ``casagui``'s
+applications produce'''
+import os
+import re
+from os import path
+from os.path import dirname, join, basename, abspath
+from urllib.parse import urlparse
+from bokeh import resources
+from ...utils import path_to_url, static_vars, have_network
+
+
+@static_vars( initialized=False,
+              do_local_subst=not have_network( ) )
+def initialize_bokeh( bokehjs_subst=None ):
+    """Initialize `bokeh` for use with the ``cubevisjs`` extensions.
+
+    The ``cubevisjs`` extensions for Bokeh are built into a stand-alone
+    external JavaScript file constructed for the specific version of
+    Bokeh that is being used. Previously the CASA minified JavaScript
+    libraries were loaded from the network. Now these libraries are
+    included in a ``__js__`` directory within the cubevis Python package.
+    If users need to debug JavaScript problems, non-minified versions
+    can be copied into the ``__js__`` directory to replace the existing
+    libraries. To debug within the bokehjs library, a URL or a path
+    can be supplied by the ``bokehjs_subst`` parameter and it will be
+    substituted for the standard Bokeh library.
+
+    Parameters
+    ----------
+    bokehjs_subst: None or str or list of str
+        Bokeh dependent javascript library which is loaded after all
+        other Bokeh libraries have been loaded. This path could be a
+        local path, a URL or None. None is the default in which case
+        it loads the published library for the current version of
+        ``cubevisjs`` and ``bokeh``
+
+    Example
+    -------
+    from cubevis.bokeh.state import initialize_bokeh
+    initialize_bokeh( bokehjs_subst="/tmp/bokeh-3.2.2.js" )
+    """
+
+    if initialize_bokeh.initialized:
+        ### only initialize once...
+        return
+
+    initialize_bokeh.initialized = True
+    resources.Resources._old_js_files = resources.Resources.js_files
+    def js_files( self ):
+        ########################################################################
+        ### Function that will replace the member function within Bokeh that ###
+        ### returns the URLs for Bokeh initialization...                     ###
+        ########################################################################
+        def expand_paths( replacement ):
+            ### turn all paths into URLs
+            ### turn a single string into a list with one string
+            if replacement is None:
+                return [ ]
+            if type(replacement) == str:
+                if path.isfile(replacement):
+                    return [ f'''file://{abspath(replacement)}''' ]
+                elif replacement.startswith('http'):
+                    return [ replacement ]
+                else:
+                    raise RuntimeError( f'''debugging bokehjs substitution ('{replacement}') does not exist''' )
+            if type(replacement) == list:
+                result = [ ]
+                for u in replacement:
+                    if path.isfile(u):
+                        result.append( f'''file://{abspath(u)}''' )
+                    elif u.startswith('http'):
+                        result.append( u )
+                    else:
+                        raise RuntimeError( f'''debugging bokehjs substitution ('{u}') does not exist''' )
+                return result
+            return [ ]
+        def cubevisjs_predicate( s ):
+            ### detect cubevisjs library URL
+            return basename(s).startswith('cubevisjs')
+        def replace_bokehjs( urls, replacement ):
+            ### substitute replacement list for the bokehjs library URL
+            result = [ ]
+            for url in urls:
+                if re.match( r'.*/bokeh-\d+\.\d+\.\d+(?:\.min)?\.js$', url ):
+                    result += replacement
+                else:
+                    result.append(url)
+            return result
+
+        def include_all_bokehjs( urls ):
+            result = urls.copy( )
+            bokeh_path=None
+            has_bokeh_widgets=False
+            has_bokeh_tables=False
+            for url in urls:
+                if re.match( r'.*/bokeh-\d+\.\d+\.\d+(?:\.min)?\.js$', url ):
+                    bokeh_path = url
+                if re.match( r'.*/bokeh-widgets-\d+\.\d+\.\d+(?:\.min)?\.js$', url ):
+                    has_bokeh_widgets = True
+                if re.match( r'.*/bokeh-tables-\d+\.\d+\.\d+(?:\.min)?\.js$', url ):
+                    has_bokeh_tables = True
+
+            if bokeh_path:
+                if not has_bokeh_widgets:
+                    result.append( bokeh_path.replace('/bokeh-','/bokeh-widgets-') )
+                if not has_bokeh_tables:
+                    result.append( bokeh_path.replace('/bokeh-','/bokeh-tables-') )
+
+            return result
+
+        user_bokehjs_replacement = expand_paths(bokehjs_subst)
+        sys_urls = include_all_bokehjs( resources.Resources._old_js_files.fget(self) )
+        if initialize_bokeh.do_local_subst:
+            local_urls = [ ]
+            for url in sys_urls:
+                pieces = urlparse(url)
+                if pieces.scheme != 'file':
+                    lib = basename(pieces.path)
+                    url = path_to_url(lib)
+                    if lib != url:
+                        local_urls.append(url)
+                    else:
+                        raise RuntimeError( '''Cannot confirm internet access and could not find local cached versions of Bokeh's libraries''' )
+                else:
+                    local_urls.append(url)
+            sys_urls = local_urls
+
+        if len(user_bokehjs_replacement) == 0:
+            ### move cubevisjs library after Bokeh libraries
+            return [x for x in sys_urls if not cubevisjs_predicate(x)] + [x for x in sys_urls if cubevisjs_predicate(x)]
+        else:
+            ### replace bokehjs library with bokehjs_subst and move cubevisjs library after Bokeh libraries
+            return replace_bokehjs( [x for x in sys_urls if not cubevisjs_predicate(x)], user_bokehjs_replacement ) + [x for x in sys_urls if cubevisjs_predicate(x)]
+
+    resources.Resources.js_files = property(js_files)
+    return

cubevis/bokeh/state/_javascript.py

@@ -0,0 +1,53 @@
+########################################################################
+#
+# Copyright (C) 2023
+# Associated Universities, Inc. Washington DC, USA.
+#
+# This script is free software; you can redistribute it and/or modify it
+# under the terms of the GNU Library General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or (at your
+# option) any later version.
+#
+# This library is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Library General Public License
+# along with this library; if not, write to the Free Software Foundation,
+# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
+#
+# Correspondence concerning AIPS++ should be adressed as follows:
+#        Internet email: casa-feedback@nrao.edu.
+#        Postal address: AIPS++ Project Office
+#                        National Radio Astronomy Observatory
+#                        520 Edgemont Road
+#                        Charlottesville, VA 22903-2475 USA
+#
+########################################################################
+'''This contains functions which return the URLs to the ``cubevis``
+JavaScript libraries. The ``casalib`` library has Bokeh independent
+functions while the `cubevisjs` library has the Bokeh extensions'''
+from ...utils import static_vars
+from ._initialize import initialize_bokeh
+from os import path
+
+@static_vars( library_path=None )
+def casalib_url( ):
+    if casalib_url.library_path is None:
+        casalib_url.library_path = path.join(path.dirname(path.dirname(path.dirname(__file__))), '__js__', 'casalib.min.js')
+    if not path.isfile(casalib_url.library_path):
+        raise RuntimeError( f''''casalib' JavaScript library not found at '{casalib_url.library_path}\'''' )
+    if not initialize_bokeh.initialized:
+        initialize_bokeh( )
+    return f'''file://{casalib_url.library_path}'''
+
+@static_vars( library_path=None )
+def cubevisjs_url( ):
+    if cubevisjs_url.library_path is None:
+        cubevisjs_url.library_path = path.join(path.dirname(path.dirname(path.dirname(__file__))), '__js__', 'cubevisjs.min.js')
+    if not path.isfile(cubevisjs_url.library_path):
+        raise RuntimeError( f''''cubevisjs' JavaScript library not found at '{cubevisjs_url.library_path}\'''' )
+    if not initialize_bokeh.initialized:
+        initialize_bokeh( )
+    return f'''file://{cubevisjs_url.library_path}'''

cubevis/bokeh/state/_palette.py

@@ -0,0 +1,58 @@
+########################################################################
+#
+# Copyright (C) 2022
+# Associated Universities, Inc. Washington DC, USA.
+#
+# This script is free software; you can redistribute it and/or modify it
+# under the terms of the GNU Library General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or (at your
+# option) any later version.
+#
+# This library is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Library General Public License
+# along with this library; if not, write to the Free Software Foundation,
+# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
+#
+# Correspondence concerning AIPS++ should be adressed as follows:
+#        Internet email: casa-feedback@nrao.edu.
+#        Postal address: AIPS++ Project Office
+#                        National Radio Astronomy Observatory
+#                        520 Edgemont Road
+#                        Charlottesville, VA 22903-2475 USA
+#
+########################################################################
+'''Functions for palette access.'''
+import re
+from bokeh import palettes as __palettes
+from ...utils import static_vars
+
+__palette_list = sorted( [ p for p in dir(__palettes) if isinstance(getattr(__palettes,p), tuple) if len(getattr( __palettes, p )) == 256 ] )
+__palette_names = [ re.sub(r'\d+$', '', p) for p in __palette_list ]
+
+__palette_map = dict( zip( __palette_names, __palette_list ) )
+
+def available_palettes ( ):
+    '''returns list of palette pretty names'''
+    return __palette_names
+
+def find_palette( name ):
+    '''fetches palette by the pretty name'''
+    if name not in __palette_map:
+        return None
+    return getattr( __palettes, __palette_map[name] )
+
+@static_vars( raw=None, pretty=None )
+def default_palette( raw=False ):
+    '''returns the full name (raw or pretty version)'''
+    if default_palette.pretty is None:
+        if 'Plasma' in __palette_map:
+            default_palette.pretty = 'Plasma'
+            default_palette.raw = __palette_map['Plasma']
+        else:
+            default_palette.pretty = __palette_names[0]
+            default_palette.raw = __palette_map[__palette_names[0]]
+    return default_palette.raw if raw else default_palette.pretty

cubevis/bokeh/state/_session.py

@@ -0,0 +1,44 @@
+########################################################################
+#
+# Copyright (C) 2022
+# Associated Universities, Inc. Washington DC, USA.
+#
+# This script is free software; you can redistribute it and/or modify it
+# under the terms of the GNU Library General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or (at your
+# option) any later version.
+#
+# This library is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Library General Public License
+# along with this library; if not, write to the Free Software Foundation,
+# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
+#
+# Correspondence concerning AIPS++ should be adressed as follows:
+#        Internet email: casa-feedback@nrao.edu.
+#        Postal address: AIPS++ Project Office
+#                        National Radio Astronomy Observatory
+#                        520 Edgemont Road
+#                        Charlottesville, VA 22903-2475 USA
+#
+########################################################################
+'''Functions for session management.'''
+from bokeh.io import output_notebook
+
+def setup_session():
+    '''Configure session for notebook or terminal'''
+
+    #session_settings = {
+    #    "ZMQInteractiveShell": "Running in a Jupyter notebook",
+    #    "TerminalInteractiveShell": "Running in a terminal",
+    #}
+    try:
+        session = get_ipython().__class__.__name__
+    except NameError:
+        session = "Unknown"
+
+    if session == "ZMQInteractiveShell":
+        output_notebook()