Base path mixin and other shared functionality (#138)

* Move version to shared file that docs and setup read from

* Add missing return_path option to get_value

* Move image's call_action, get_value and macro to mixin class which can be shared by all child objects with their own base paths in the frontend store tree

Author: confluence

VERSION.txt

@@ -0,0 +1 @@
+1.1.10

carta/image.py

@@ -3,13 +3,13 @@
 Image objects should not be instantiated directly, and should only be created through methods on the :obj:`carta.session.Session` object.
 """
 from .constants import Colormap, Scaling, SmoothingMode, ContourDashMode, Polarization, CoordinateSystem, SpatialAxis
-from .util import Macro, cached
+from .util import Macro, cached, BasePathMixin
 from .units import PixelValue, AngularSize, WorldCoordinate
 from .validation import validate, Number, Color, Constant, Boolean, NoneOr, IterableOf, Evaluate, Attr, Attrs, OneOf, Size, Coordinate, all_optional
 from .metadata import parse_header
 
 
-class Image:
+class Image(BasePathMixin):
     """This object corresponds to an image open in a CARTA frontend session.
 
     This class should not be instantiated directly. Instead, use the session object's methods for opening new images or retrieving existing images.
@@ -100,64 +100,6 @@ def from_list(cls, session, image_list):
     def __repr__(self):
         return f"{self.session.session_id}:{self.image_id}:{self.file_name}"
 
-    def call_action(self, path, *args, **kwargs):
-        """Convenience wrapper for the session object's generic action method.
-
-        This method calls :obj:`carta.session.Session.call_action` after prepending this image's base path to the path parameter.
-
-        Parameters
-        ----------
-        path : string
-            The path to an action relative to this image's frame store.
-        *args
-            A variable-length list of parameters. These are passed unmodified to the session method.
-        **kwargs
-            Arbitrary keyword parameters. These are passed unmodified to the session method.
-
-        Returns
-        -------
-        object or None
-            The unmodified return value of the session method.
-        """
-        return self.session.call_action(f"{self._base_path}.{path}", *args, **kwargs)
-
-    def get_value(self, path):
-        """Convenience wrapper for the session object's generic method for retrieving attribute values.
-
-        This method calls :obj:`carta.session.Session.get_value` after prepending this image's base path to the *path* parameter.
-
-        Parameters
-        ----------
-        path : string
-            The path to an attribute relative to this image's frame store.
-
-        Returns
-        -------
-        object
-            The unmodified return value of the session method.
-        """
-        return self.session.get_value(f"{self._base_path}.{path}")
-
-    def macro(self, target, variable):
-        """Convenience wrapper for creating a :obj:`carta.util.Macro` for an image property.
-
-        This method prepends this image's base path to the *target* parameter. If *target* is the empty string, the base path will be substituted.
-
-        Parameters
-        ----------
-        target : str
-            The target frontend object.
-        variable : str
-            The variable on the target object.
-
-        Returns
-        -------
-        :obj:carta.util.Macro
-            A placeholder for a variable which will be evaluated dynamically by the frontend.
-        """
-        target = f"{self._base_path}.{target}" if target else self._base_path
-        return Macro(target, variable)
-
     # METADATA
 
     @property

carta/session.py

@@ -254,7 +254,7 @@ def call_action(self, path, *args, **kwargs):
         """
         return self._protocol.request_scripting_action(self.session_id, path, *args, **kwargs)
 
-    def get_value(self, path):
+    def get_value(self, path, return_path=None):
         """Get the value of an attribute from a frontend store.
 
         Like the :obj:`carta.session.Session.call_action` method, this is exposed in the public API but is not intended to be used directly under normal circumstances.
@@ -263,6 +263,8 @@ def get_value(self, path):
         ----------
         path : string
             The full path to the attribute.
+        return_path : string, optional
+            Specifies a subobject of the attribute value which should be returned instead of the whole object.
 
         Returns
         -------
@@ -271,7 +273,12 @@ def get_value(self, path):
         """
         path, parameter = split_action_path(path)
         macro = Macro(path, parameter)
-        return self.call_action("fetchParameter", macro, response_expected=True)
+
+        kwargs = {"response_expected": True}
+        if return_path is not None:
+            kwargs["return_path"] = return_path
+
+        return self.call_action("fetchParameter", macro, **kwargs)
 
     # FILE BROWSING
 

carta/util.py

@@ -136,3 +136,72 @@ def split_action_path(path):
     """
     parts = path.split('.')
     return '.'.join(parts[:-1]), parts[-1]
+
+
+class BasePathMixin:
+    """A mixin which provides ``call_action`` and ``get_value`` methods which prepend the object's base path to the path before calling the corresponding :obj:`carta.session.Session` methods.
+
+    It also provides a ``macro`` method which prepends the path when creating a :obj:`carta.util.Macro`.
+
+    A class inheriting from this mixin must define a `_base_path` attribute (the string prefix) and a `session` attribute (a :obj:`carta.session.Session` object).
+    """
+
+    def call_action(self, path, *args, **kwargs):
+        """Convenience wrapper for the session object's generic action method.
+
+        This method calls :obj:`carta.session.Session.call_action` after prepending this object's base path to the path parameter.
+
+        Parameters
+        ----------
+        path : string
+            The path to an action relative to this object's store.
+        *args
+            A variable-length list of parameters. These are passed unmodified to the session method.
+        **kwargs
+            Arbitrary keyword parameters. These are passed unmodified to the session method.
+
+        Returns
+        -------
+        object or None
+            The unmodified return value of the session method.
+        """
+        return self.session.call_action(f"{self._base_path}.{path}", *args, **kwargs)
+
+    def get_value(self, path, return_path=None):
+        """Convenience wrapper for the session object's generic method for retrieving attribute values.
+
+        This method calls :obj:`carta.session.Session.get_value` after prepending this object's base path to the *path* parameter.
+
+        Parameters
+        ----------
+        path : string
+            The path to an attribute relative to this object's store.
+        return_path : string, optional
+            Specifies a subobject of the attribute value which should be returned instead of the whole object.
+
+        Returns
+        -------
+        object
+            The unmodified return value of the session method.
+        """
+        return self.session.get_value(f"{self._base_path}.{path}", return_path=return_path)
+
+    def macro(self, target, variable):
+        """Convenience wrapper for creating a :obj:`carta.util.Macro` for an object property.
+
+        This method prepends this object's base path to the *target* parameter. If *target* is the empty string, the base path will be substituted.
+
+        Parameters
+        ----------
+        target : str
+            The target frontend object.
+        variable : str
+            The variable on the target object.
+
+        Returns
+        -------
+        :obj:carta.util.Macro
+            A placeholder for a variable which will be evaluated dynamically by the frontend.
+        """
+        target = f"{self._base_path}.{target}" if target else self._base_path
+        return Macro(target, variable)

docs/source/conf.py

@@ -23,7 +23,11 @@
 author = 'Adrianna Pińska'
 
 # The full version, including alpha/beta/rc tags
-release = '1.0.0-beta'
+
+with open("../../VERSION.txt") as f:
+    version = f.read()
+
+release = version
 
 
 # -- General configuration ---------------------------------------------------

setup.py

@@ -1,11 +1,14 @@
 import setuptools
 
-with open("README.md", "r") as fh:
-    long_description = fh.read()
+with open("README.md") as f:
+    long_description = f.read()
+
+with open("VERSION.txt") as f:
+    version = f.read()
 
 setuptools.setup(
     name="carta",
-    version="1.1.10",
+    version=version,
     author="Adrianna Pińska",
     author_email="adrianna.pinska@gmail.com",
     description="CARTA scripting wrapper written in Python",