Rename mentions of plugins to capsules in the API (#6)

velovix · web-flow · commit 4376dbf1bc55 · 2020-07-02T14:12:08.000-07:00
This brings the Python API up to speed with the naming we're using in the BrainFrame documentation. The server itself still calls them plugins in API endpoints and errors, so some mention of "plugins" still exists.
diff --git a/brainframe/api/bf_codecs/__init__.py b/brainframe/api/bf_codecs/__init__.py
@@ -10,9 +10,9 @@
 from .identity_codecs import Identity, Encoding
 from .detection_codecs import Attribute, Detection
 from .zone_codecs import Zone, ZoneStatus
-from .plugin_codecs import (
-    PluginOption,
-    Plugin,
+from .capsule_codecs import (
+    CapsuleOption,
+    Capsule,
     NodeDescription,
 )
 from .premises_codecs import Premises
diff --git a/brainframe/api/bf_codecs/capsule_codecs.py b/brainframe/api/bf_codecs/capsule_codecs.py
@@ -7,17 +7,17 @@
 
 
 @dataclass
-class PluginOption(Codec):
-    """A single configuration option for a plugin. Defines what type of option
+class CapsuleOption(Codec):
+    """A single configuration option for a capsule. Defines what type of option
     it is and its potential values.
 
-    There are two kinds of plugin options. Stream plugin options apply only to
-    the stream they are attached to. Global plugin options apply to all
-    streams, but are overridden by stream plugin options.
+    There are two kinds of capsule options. Stream capsule options apply only
+    to the stream they are attached to. Global capsule options apply to all
+    streams, but are overridden by stream capsule options.
     """
 
     class Type(Enum):
-        """The data type of a plugin option"""
+        """The data type of a capsule option"""
 
         FLOAT = "float"
         INT = "int"
@@ -57,7 +57,7 @@ def values(cls):
     """
 
     description: str
-    """A human-readable description of the plugin's capabilities"""
+    """A human-readable description of the capsule's capabilities"""
 
     def to_dict(self):
         d = dict(self.__dict__)
@@ -66,42 +66,42 @@ def to_dict(self):
 
     @staticmethod
     def from_dict(d):
-        type_ = PluginOption.Type(d["type"])
-        return PluginOption(type=type_,
-                            default=d["default"],
-                            constraints=d["constraints"],
-                            description=d["description"])
+        type_ = CapsuleOption.Type(d["type"])
+        return CapsuleOption(type=type_,
+                             default=d["default"],
+                             constraints=d["constraints"],
+                             description=d["description"])
 
 
 @dataclass
 class NodeDescription(Codec):
-    """A description of a DetectionNode, used by plugins to define what kinds
-    of inputs and outputs a plugin uses.
+    """A description of a DetectionNode, used by capsules to define what kinds
+    of inputs and outputs a capsule uses.
     """
 
     class Size(Enum):
-        """Describes the amount of DetectionNodes a plugin takes as input or
+        """Describes the amount of DetectionNodes a capsule takes as input or
         provides as output.
         """
 
         NONE = "none"
-        """Input: The plugin takes nothing as input, like for an object
+        """Input: The capsule takes nothing as input, like for an object
         detector.
 
-        Output: Plugins cannot have a NONE output.
+        Output: Capsules cannot have a NONE output.
         """
         SINGLE = "single"
-        """Input: The plugin takes a single DetectionNode as input, like for a
+        """Input: The capsule takes a single DetectionNode as input, like for a
         classifier.
 
-        Output: The plugin provides a single modified DetectionNode as output,
+        Output: The capsule provides a single modified DetectionNode as output,
         like for a classifier.
         """
         ALL = "all"
-        """Input: The plugin takes all instances of a class as input, like for
+        """Input: The capsule takes all instances of a class as input, like for
         a tracker.
 
-        Output: The plugin provides all instances of a class as output, like
+        Output: The capsule provides all instances of a class as output, like
         for a detector.
         """
 
@@ -159,34 +159,34 @@ def from_dict(d):
 
 
 @dataclass
-class Plugin(Codec):
-    """Metadata on a loaded plugin."""
+class Capsule(Codec):
+    """Metadata on a loaded capsule."""
 
     name: str
-    """The name of the plugin"""
+    """The name of the capsule"""
 
     version: int
-    """The plugin's version"""
+    """The capsule's version"""
 
     description: str
-    """A human-readable description of what the plugin does"""
+    """A human-readable description of what the capsule does"""
 
     input_type: NodeDescription
-    """Describes the type of inference data that this plugin takes as input
+    """Describes the type of inference data that this capsule takes as input
     """
 
     output_type: NodeDescription
-    """Describes the type of inference data that this plugin produces"""
+    """Describes the type of inference data that this capsule produces"""
 
     capability: NodeDescription
-    """A NodeDescription which describes what this plugin does to its
+    """A NodeDescription which describes what this capsule does to its
     input. It is the difference between the input and output
-    NodeDescriptions. This field is useful for inspecting a plugin to find
+    NodeDescriptions. This field is useful for inspecting a capsule to find
     what it can do.
     """
 
-    options: Dict[str, PluginOption]
-    """A dict describing the configurable options of this plugin"""
+    options: Dict[str, CapsuleOption]
+    """A dict describing the configurable options of this capsule"""
 
     def to_dict(self):
         return {
@@ -202,13 +202,13 @@ def to_dict(self):
 
     @staticmethod
     def from_dict(d):
-        return Plugin(
+        return Capsule(
             name=d["name"],
             version=d["version"],
             description=d["description"],
             input_type=NodeDescription.from_dict(d["input_type"]),
             output_type=NodeDescription.from_dict(d["output_type"]),
             capability=NodeDescription.from_dict(d["capability"]),
-            options={key: PluginOption.from_dict(val)
+            options={key: CapsuleOption.from_dict(val)
                      for key, val in d["options"].items()},
         )
diff --git a/brainframe/api/bf_errors.py b/brainframe/api/bf_errors.py
@@ -192,16 +192,16 @@ class FrameNotFoundForAlertError(BaseAPIError):
     """There was an attempt to get a frame for an alert that has no frame."""
 
 
-@_register_error()
-class PluginNotFoundError(BaseAPIError):
-    """There was an attempt to reference a plugin that does not exist."""
+@_register_error("PluginNotFoundError")
+class CapsuleNotFoundError(BaseAPIError):
+    """There was an attempt to reference a capsule that does not exist."""
 
 
-@_register_error()
-class InvalidPluginOptionError(BaseAPIError):
-    """The provided plugin options do not work for the given plugin. This could
-    be because the option does not exist or the value for that option doesn't
-    fit the constraints.
+@_register_error("InvalidPluginOptionError")
+class InvalidCapsuleOptionError(BaseAPIError):
+    """The provided capsule options do not work for the given capsule. This
+    could be because the option does not exist or the value for that option
+    doesn't fit the constraints.
     """
 
 
diff --git a/brainframe/api/stub.py b/brainframe/api/stub.py
@@ -11,7 +11,7 @@
 class BrainFrameAPI(stubs.AlertStubMixin,
                     stubs.AnalysisStubMixin,
                     stubs.IdentityStubMixin,
-                    stubs.PluginStubMixin,
+                    stubs.CapsuleStubMixin,
                     stubs.StreamStubMixin,
                     stubs.ZoneStatusStubMixin,
                     stubs.ZoneStubMixin,
diff --git a/brainframe/api/stubs/__init__.py b/brainframe/api/stubs/__init__.py
@@ -1,7 +1,7 @@
 from .alerts import AlertStubMixin
 from .analysis import AnalysisStubMixin
 from .identities import IdentityStubMixin
-from .plugins import PluginStubMixin
+from .capsules import CapsuleStubMixin
 from .streams import StreamStubMixin
 from .zone_statuses import ZoneStatusStubMixin
 from .zones import ZoneStubMixin
diff --git a/brainframe/api/stubs/capsules.py b/brainframe/api/stubs/capsules.py
@@ -0,0 +1,132 @@
+import json
+from typing import Dict, List, Optional
+
+from brainframe.api.bf_codecs import Capsule
+from .base_stub import BaseStub, DEFAULT_TIMEOUT
+
+
+class CapsuleStubMixin(BaseStub):
+    """Provides stubs to call APIs to inspect and configure capsules."""
+
+    def get_capsule(self, name,
+                    timeout=DEFAULT_TIMEOUT) -> Capsule:
+        """
+        :param name: The name of the capsule to get
+        :param timeout: The timeout to use for this request
+        :return: Capsule with the given name
+        """
+        req = f"/api/plugins/{name}"
+        capsule, _ = self._get_json(req, timeout)
+        return Capsule.from_dict(capsule)
+
+    def get_capsules(self, timeout=DEFAULT_TIMEOUT) -> List[Capsule]:
+        """
+        :param timeout: The timeout to use for this request
+        :return: All available capsules
+        """
+        req = "/api/plugins"
+        capsules, _ = self._get_json(req, timeout)
+        return [Capsule.from_dict(d) for d in capsules]
+
+    def get_capsule_option_vals(self, capsule_name, stream_id=None,
+                                timeout=DEFAULT_TIMEOUT) \
+            -> Dict[str, object]:
+        """Gets the current values for every capsule option. See the
+        documentation for the CapsuleOption codec for more info about global
+        and stream level options and how they interact.
+
+        :param capsule_name: The capsule to find options for
+        :param stream_id: The ID of the stream. If this value is None, then the
+            global options are returned for that capsule
+        :param timeout: The timeout to use for this request
+        :return: A dict where the key is the option name and the value is the
+            option's current value
+        """
+        if stream_id is None:
+            req = f"/api/plugins/{capsule_name}/options"
+        else:
+            req = f"/api/streams/{stream_id}/plugins/{capsule_name}/options"
+        capsule_option_vals, _ = self._get_json(req, timeout)
+
+        return capsule_option_vals
+
+    def set_capsule_option_vals(self, *, capsule_name, stream_id=None,
+                                option_vals: Dict[str, object],
+                                timeout=DEFAULT_TIMEOUT):
+        """Sets option values for a capsule.
+
+        :param capsule_name: The name of the capsule whose options to set
+        :param stream_id: The ID of the stream, if these are stream-level
+            options. If this value is None, then the global options are set
+        :param option_vals: A dict where the key is the name of the option to
+            set, and the value is the value to set that option to
+        :param timeout: The timeout to use for this request
+        """
+        if stream_id is None:
+            req = f"/api/plugins/{capsule_name}/options"
+        else:
+            req = f"/api/streams/{stream_id}/plugins/{capsule_name}/options"
+
+        option_values_json = json.dumps(option_vals)
+        self._put_json(req, timeout, option_values_json)
+
+    def patch_capsule_option_vals(self, *, capsule_name, stream_id=None,
+                                  option_vals: Dict[str, object],
+                                  timeout=DEFAULT_TIMEOUT):
+        """Patches option values for a capsule. Only the provided options are
+        changed. To unset an option, provide that option with a value of None.
+
+        :param capsule_name: The name of the capsule whose options to set
+        :param stream_id: The ID of the stream, if these are stream-level
+            options. If this value is None, then the global options are set
+        :param option_vals: A dict where the key is the name of the option to
+            set, and the value is the value to set that option to
+        :param timeout: The timeout to use for this request
+        """
+        if stream_id is None:
+            req = f"/api/plugins/{capsule_name}/options"
+        else:
+            req = f"/api/streams/{stream_id}/plugins/{capsule_name}/options"
+
+        option_values_json = json.dumps(option_vals)
+        self._patch_json(req, timeout, option_values_json)
+
+    def is_capsule_active(self, capsule_name, stream_id=None,
+                          timeout=DEFAULT_TIMEOUT) -> bool:
+        """Returns True if the capsule is active. If a capsule is not marked as
+        active, it will not run. Like capsule options, this can be configured
+        globally and on a per-stream level.
+
+        :param capsule_name: The name of the capsule to get activity for
+        :param stream_id: The ID of the stream, if you want the per-stream
+            active setting
+        :param timeout: The timeout to use for this request
+        :return: True if the capsule is active
+        """
+        if stream_id is None:
+            req = f"/api/plugins/{capsule_name}/active"
+        else:
+            req = f"/api/streams/{stream_id}/plugins/{capsule_name}/active"
+        capsules_active, _ = self._get_json(req, timeout)
+        return capsules_active
+
+    def set_capsule_active(self, *, capsule_name, stream_id=None,
+                           active: Optional[bool],
+                           timeout=DEFAULT_TIMEOUT):
+        """Sets whether or not the capsule is active. If a capsule is active, it
+        will be run on frames.
+
+        :param capsule_name: The name of the capsule to set activity for
+        :param stream_id: The ID of the stream, if you want to set the
+            per-stream active setting
+        :param active: True if the capsule should be set to active
+        :param timeout: The timeout to use for this request
+        """
+        if stream_id is None:
+            req = f"/api/plugins/{capsule_name}/active"
+        else:
+            req = f"/api/streams/{stream_id}/plugins/{capsule_name}/active"
+
+        active_json = json.dumps(active)
+
+        self._put_json(req, timeout, active_json)
diff --git a/brainframe/api/stubs/plugins.py b/brainframe/api/stubs/plugins.py
diff --git a/brainframe/api/stubs/process_image.py b/brainframe/api/stubs/process_image.py
diff --git a/docs/capsules.rst b/docs/capsules.rst
