sierra-research 1.3.11__py3-none-any.whl → 1.5.0__py3-none-any.whl

sierra/core/ros1/variables/exp_setup.py

@@ -2,9 +2,9 @@
 #
 #  SPDX-License-Identifier: MIT
 
-"""Classes for the ``--exp-setup`` cmdline option for ROS1 platforms.
+"""Classes for the ``--exp-setup`` cmdline option for ROS1 engines.
 
-See :ref:`ln-sierra-vars-expsetup` for usage documentation.
+See :ref:`usage/vars/expsetup` for usage documentation.
 
 """
 
@@ -16,106 +16,115 @@ import implements
 
 # Project packages
 from sierra.core.variables.base_variable import IBaseVariable
-from sierra.core.experiment import xml
+from sierra.core.experiment import definition
 from sierra.core import config
-from sierra.core.variables.exp_setup import Parser
+from sierra.core.variables import exp_setup
 
 
 @implements.implements(IBaseVariable)
-class ExpSetup():
+class ExpSetup:
     """
     Defines the experimental setup for ROS experiments.
 
     Attributes:
-
         n_secs_per_run: The :term:`Experimental Run` duration in seconds, NOT
                         :term:`Ticks <Tick>` or timesteps.
 
-        n_datapoints: How many datapoints to capture during the experimental
-                      run.
-
         n_ticks_per_sec: How many times per second robot controllers will be
                          run.
 
     """
 
-    def __init__(self,
-                 n_secs_per_run: int,
-                 n_datapoints: int,
-                 n_ticks_per_sec: int,
-                 barrier_start: bool,
-                 robots_need_timekeeper: bool) -> None:
+    def __init__(
+        self,
+        n_secs_per_run: int,
+        n_ticks_per_sec: int,
+        barrier_start: bool,
+        robots_need_timekeeper: bool,
+    ) -> None:
         self.n_secs_per_run = n_secs_per_run
-        self.n_datapoints = n_datapoints
         self.n_ticks_per_sec = n_ticks_per_sec
         self.barrier_start = barrier_start
         self.robots_need_timekeeper = robots_need_timekeeper
 
-        self.tag_adds = None
+        self.element_adds = None
 
-    def gen_attr_changelist(self) -> tp.List[xml.AttrChangeSet]:
+    def gen_attr_changelist(self) -> tp.List[definition.AttrChangeSet]:
         return []
 
-    def gen_tag_rmlist(self) -> tp.List[xml.TagRmList]:
+    def gen_tag_rmlist(self) -> tp.List[definition.ElementRmList]:
         return []
 
-    def gen_tag_addlist(self) -> tp.List[xml.TagAddList]:
-        if not self.tag_adds:
-            adds = xml.TagAddList(
-                xml.TagAdd("./master/group/[@ns='sierra']",
-                           "param",
-                           {
-                               "name": "experiment/length",
-                               "value": str(self.n_secs_per_run),
-                           },
-                           True),
-                xml.TagAdd("./master/group/[@ns='sierra']",
-                           "param",
-                           {
-                               "name": "experiment/ticks_per_sec",
-                               "value": str(self.n_ticks_per_sec),
-                           },
-                           True),
-                xml.TagAdd("./master/group/[@ns='sierra']",
-                           "param",
-                           {
-                               "name": "experiment/barrier_start",
-                               "value": str(self.barrier_start).lower(),
-                           },
-                           True),
-                xml.TagAdd("./master/group/[@ns='sierra']",
-                           "node",
-                           {
-                               "name": "sierra_timekeeper",
-                               "pkg": "sierra_rosbridge",
-                               "type": "sierra_timekeeper.py",
-                               "required": "true",
-                               # Otherwise rospy prints nothing
-                               "output": "screen"
-                           },
-                           True),
-
-                xml.TagAdd("./robot/group/[@ns='sierra']",
-                           "param",
-                           {
-                               "name": "experiment/length",
-                               "value": str(self.n_secs_per_run),
-                           },
-                           True),
-                xml.TagAdd("./robot/group/[@ns='sierra']",
-                           "param",
-                           {
-                               "name": "experiment/ticks_per_sec",
-                               "value": str(self.n_ticks_per_sec),
-                           },
-                           True),
-                xml.TagAdd("./robot/group/[@ns='sierra']",
-                           "param",
-                           {
-                               "name": "experiment/barrier_start",
-                               "value": str(self.barrier_start).lower()
-                           },
-                           True)
+    def gen_element_addlist(self) -> tp.List[definition.ElementAddList]:
+        if not self.element_adds:
+            adds = definition.ElementAddList(
+                definition.ElementAdd(
+                    "./master/group/[@ns='sierra']",
+                    "param",
+                    {
+                        "name": "experiment/length",
+                        "value": str(self.n_secs_per_run),
+                    },
+                    True,
+                ),
+                definition.ElementAdd(
+                    "./master/group/[@ns='sierra']",
+                    "param",
+                    {
+                        "name": "experiment/ticks_per_sec",
+                        "value": str(self.n_ticks_per_sec),
+                    },
+                    True,
+                ),
+                definition.ElementAdd(
+                    "./master/group/[@ns='sierra']",
+                    "param",
+                    {
+                        "name": "experiment/barrier_start",
+                        "value": str(self.barrier_start).lower(),
+                    },
+                    True,
+                ),
+                definition.ElementAdd(
+                    "./master/group/[@ns='sierra']",
+                    "node",
+                    {
+                        "name": "sierra_timekeeper",
+                        "pkg": "sierra_rosbridge",
+                        "type": "sierra_timekeeper.py",
+                        "required": "true",
+                        # Otherwise rospy prints nothing
+                        "output": "screen",
+                    },
+                    True,
+                ),
+                definition.ElementAdd(
+                    "./robot/group/[@ns='sierra']",
+                    "param",
+                    {
+                        "name": "experiment/length",
+                        "value": str(self.n_secs_per_run),
+                    },
+                    True,
+                ),
+                definition.ElementAdd(
+                    "./robot/group/[@ns='sierra']",
+                    "param",
+                    {
+                        "name": "experiment/ticks_per_sec",
+                        "value": str(self.n_ticks_per_sec),
+                    },
+                    True,
+                ),
+                definition.ElementAdd(
+                    "./robot/group/[@ns='sierra']",
+                    "param",
+                    {
+                        "name": "experiment/barrier_start",
+                        "value": str(self.barrier_start).lower(),
+                    },
+                    True,
+                ),
             )
             if self.robots_need_timekeeper:
                 # Robots also need the timekeeper when they are real and not
@@ -133,29 +142,30 @@ class ExpSetup():
                 # most 1 dependent node will be active at a given time. Plus,
                 # it's just sloppy to leave that sort of thing hanging around
                 # after a run exits.
-                adds.append(xml.TagAdd("./robot/group/[@ns='sierra']",
-                                       "node",
-                                       {
-                                           "name": "sierra_timekeeper",
-                                           "pkg": "sierra_rosbridge",
-                                           "type": "sierra_timekeeper.py",
-                                           "required": "true",
-                                           # Otherwise rospy prints nothing
-                                           "output": "screen"
-                                       },
-                                       True)
-                            )
-            self.tag_adds = adds
-
-        return [self.tag_adds]
+                adds.append(
+                    definition.ElementAdd(
+                        "./robot/group/[@ns='sierra']",
+                        "node",
+                        {
+                            "name": "sierra_timekeeper",
+                            "pkg": "sierra_rosbridge",
+                            "type": "sierra_timekeeper.py",
+                            "required": "true",
+                            # Otherwise rospy prints nothing
+                            "output": "screen",
+                        },
+                        True,
+                    )
+                )
+            self.element_adds = adds
+
+        return [self.element_adds]
 
     def gen_files(self) -> None:
         pass
 
 
-def factory(arg: str,
-            barrier_start: bool,
-            robots_need_timekeeper: bool) -> ExpSetup:
+def factory(arg: str, barrier_start: bool, robots_need_timekeeper: bool) -> ExpSetup:
     """Create an :class:`ExpSetup` derived class from the command line definition.
 
     Arguments:
@@ -163,26 +173,22 @@ def factory(arg: str,
        arg: The value of ``--exp-setup``.
 
     """
-    parser = Parser({'n_secs_per_run': config.kROS['n_secs_per_run'],
-                     'n_ticks_per_sec': config.kROS['n_ticks_per_sec'],
-                     'n_datapoints': config.kExperimentalRunData['n_datapoints_1D']})
-    attr = parser(arg)
-
-    def __init__(self: ExpSetup) -> None:
-        ExpSetup.__init__(self,
-                          attr["n_secs_per_run"],
-                          attr['n_datapoints'],
-                          attr['n_ticks_per_sec'],
-                          barrier_start,
-                          robots_need_timekeeper)
-
-    return type(attr['pretty_name'],
-                (ExpSetup,),
-                {"__init__": __init__})  # type: ignore
-
-
-__api__ = [
-    'ExpSetup',
-
-
+    attr = exp_setup.parse(
+        arg,
+        {
+            "n_secs_per_run": config.kROS["n_secs_per_run"],
+            "n_ticks_per_sec": config.kROS["n_ticks_per_sec"],
+        },
+    )
+
+    return ExpSetup(
+        attr["n_secs_per_run"],
+        attr["n_ticks_per_sec"],
+        barrier_start,
+        robots_need_timekeeper,
+    )
+
+
+__all__ = [
+    "ExpSetup",
 ]

sierra/core/startup.py

@@ -18,31 +18,31 @@ import subprocess
 from sierra.core import types
 
 
-kOSXPackages = types.OSPackagesSpec('darwin',
-                                    'OSX',
-                                    pkgs={
-                                        'parallel': True,
-                                        'mactex': True,
-                                        'xquartz': False,
-                                        'pssh': False
-                                    })
+kOSXPackages = types.OSPackagesSpec(
+    "darwin",
+    "OSX",
+    pkgs={"parallel": True, "mactex": False, "xquartz": False, "pssh": False},
+)
 """
 The required/optional Homebrew packages.
 """
 
-kDebianPackages = types.OSPackagesSpec('linux',
-                                       'debian',
-                                       pkgs={
-                                           'parallel': True,
-                                           'cm-super': True,
-                                           'texlive-fonts-recommended': True,
-                                           'texlive-latex-extra': True,
-                                           'dvipng': True,
-                                           'psmisc': True,
-                                           'pssh': False,
-                                           'ffmpeg': False,
-                                           'xvfb': False
-                                       })
+kDebianPackages = types.OSPackagesSpec(
+    "linux",
+    "debian",
+    pkgs={
+        "parallel": True,
+        "cm-super": False,
+        "texlive-fonts-recommended": False,
+        "texlive-latex-extra": False,
+        "dvipng": False,
+        "psmisc": True,
+        "pssh": False,
+        "ffmpeg": False,
+        "xvfb": False,
+        "iputils-ping": False,
+    },
+)
 """
 The required/optional .deb packages for debian-based distributions.
 """
@@ -52,14 +52,14 @@ def startup_checks(pkg_checks: bool) -> None:
     logging.debug("Performing startup checks")
 
     # Check python version
-    if sys.version_info < (3, 8):
-        raise RuntimeError("Python >= 3.8 must be used to run SIERRA!")
+    if sys.version_info < (3, 9):
+        raise RuntimeError("Python >= 3.9 must be used to run SIERRA!")
 
     # Check packages
     if sys.platform == "linux":
         if pkg_checks:
             _linux_pkg_checks()
-    elif sys.platform == 'darwin':
+    elif sys.platform == "darwin":
         if pkg_checks:
             _osx_pkg_checks()
     else:
@@ -67,33 +67,48 @@ def startup_checks(pkg_checks: bool) -> None:
 
 
 def _linux_pkg_checks() -> None:
-    """Check that all the packages required by SIERRA are installed on Linux.
-
-    """
-    import distro  # will fail on OSX
+    """Check that all the packages required by SIERRA are installed on Linux."""
+    # This will fail on OSX if at global scope
+    import distro  # pylint: disable=import-outside-toplevel
 
     dist = distro.id()
     os_info = distro.os_release_info()
-    if any(candidate in os_info['id'] for candidate in ['debian',
-                                                        'ubuntu']):
+    if any(
+        candidate in os_info["id"] for candidate in ["debian", "ubuntu", "linuxmint"]
+    ):
         _apt_pkg_checks(dist)
     else:
-        logging.warning(("Unknown Linux distro '%s' detected: skipping package "
-                         "check"),
-                        dist)
-        logging.warning(("If SIERRA crashes it might be because you don't have "
-                         "all the required packages installed"))
+        logging.warning(
+            "Unknown Linux distro '%s' detected: skipping package check", dist
+        )
+        logging.warning(
+            (
+                "If SIERRA crashes it might be because you don't have "
+                "all the required packages installed"
+            )
+        )
 
 
 def _apt_pkg_checks(dist: str) -> None:
+    if sys.prefix != sys.base_prefix:
+        logging.debug("Running in virtual environment")
     try:
-        import apt  # pytype: disable=import-error
+        # This will fail on OSX if at global scope
+        import apt  # pytype: disable=import-error # pylint: disable=import-outside-toplevel
 
     except ImportError:
-        logging.warning(("Cannot check for required .deb packages: 'apt' "
-                         "module not found. Maybe '%s' != OS python version, "
-                         "or in virtualenv?"),
-                        sys.version)
+        logging.warning(
+            "Failed to import apt python module: Cannot check for required .deb packages."
+        )
+        logging.warning(
+            (
+                "This can happen when:\n"
+                "- Running in a venv where the python version != system python "
+                "version.\n"
+                "- No apt python module is installed at the system/user level "
+                "outside the venv."
+            )
+        )
         return
 
     cache = apt.Cache()
@@ -104,50 +119,65 @@ def _apt_pkg_checks(dist: str) -> None:
         if pkg not in cache or not cache[pkg].is_installed:
             missing.append(pkg)
 
-    if missing:
-        if required:
-            raise RuntimeError((f"Required .deb packages {missing} missing on "
-                                f"Linux distribution '{dist}'. Install all "
-                                "required packages before running SIERRA! "
-                                "(Did you read the \"Getting Started\" docs?)"))
-
-        logging.debug(("Recommended .deb packages %s missing on Linux "
-                       "distribution '%s'. Some SIERRA functionality will "
-                       "not be available. "),
-                      missing,
-                      dist)
+        if missing:
+            if required:
+                raise RuntimeError(
+                    (
+                        f"Required .deb packages {missing} missing on "
+                        f"Linux distribution '{dist}'. Install all "
+                        "required packages before running SIERRA! "
+                        '(Did you read the "Getting Started" docs?)'
+                    )
+                )
+
+            logging.debug(
+                (
+                    "Recommended .deb packages %s missing on Linux "
+                    "distribution '%s'. Some SIERRA functionality will "
+                    "not be available. "
+                ),
+                missing,
+                dist,
+            )
 
 
 def _osx_pkg_checks() -> None:
-    """Check that all the packages required by SIERRA are installed on OSX.
-
-    """
+    """Check that all the packages required by SIERRA are installed on OSX."""
     missing = []
 
     for pkg, required in kOSXPackages.pkgs.items():
-        logging.trace("Checking for homebrew package '%s'",   # type: ignore
-                      pkg)
-        p1 = subprocess.Popen(f'brew list | grep {pkg}',
-                              shell=True,
-                              stderr=subprocess.DEVNULL,
-                              stdout=subprocess.DEVNULL)
-        p2 = subprocess.Popen(f'brew list --cask | grep {pkg}',
-                              shell=True,
-                              stderr=subprocess.DEVNULL,
-                              stdout=subprocess.DEVNULL)
+        logging.trace("Checking for homebrew package '%s'", pkg)  # type: ignore
+        p1 = subprocess.Popen(
+            f"brew list | grep {pkg}",
+            shell=True,
+            stderr=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+        )
+        p2 = subprocess.Popen(
+            f"brew list --cask | grep {pkg}",
+            shell=True,
+            stderr=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+        )
         p1.wait()
         p2.wait()
 
         if p1.returncode != 0 and p2.returncode != 0:
             missing.append(pkg)
-
-    if missing:
-        if required:
-            raise RuntimeError((f"Required brew package {missing} missing on "
-                                "OSX. Install all required packages before "
-                                "running SIERRA! (Did you read the \"Getting "
-                                "Started\" docs?)"))
-
-        logging.debug(("Recommended brew package %s missing on OSX. "
-                       "Some SIERRA functionality will not be available."),
-                      pkg)
+            if required:
+                raise RuntimeError(
+                    (
+                        f"Required brew package {missing} missing on "
+                        "OSX. Install all required packages before "
+                        'running SIERRA! (Did you read the "Getting '
+                        'Started" docs?)'
+                    )
+                )
+
+            logging.debug(
+                (
+                    "Recommended brew package %s missing on OSX. "
+                    "Some SIERRA functionality will not be available."
+                ),
+                pkg,
+            )

sierra/core/stat_kernels.py

@@ -21,8 +21,8 @@ class conf95:
 
     Applicable to:
 
-    - :class:`~sierra.core.graphs.stacked_line_graph.StackedLineGraph`
-    - :class:`~sierra.core.graphs.summary_line_graph.SummaryLineGraph`
+    - :func:`~sierra.core.graphs.stacked_line`
+    - :func:`~sierra.core.graphs.summary_line`
 
     """
     @staticmethod
@@ -65,8 +65,7 @@ class bw:
 
     Applicable to:
 
-    - :class:`~sierra.core.graphs.stacked_line_graph.StackedLineGraph`
-    - :class:`~sierra.core.graphs.summary_line_graph.SummaryLineGraph`
+    - :func:`~sierra.core.graphs.summary_line`
     """
     @staticmethod
     def from_groupby(groupby: pd.core.groupby.generic.DataFrameGroupBy) -> tp.Dict[str, pd.DataFrame]:
@@ -162,7 +161,7 @@ def _fillna(df_like: tp.Union[pd.DataFrame, np.float64, float]) -> tp.Union[pd.D
     raise TypeError(f"Unknown type={type(df_like)}, value={df_like}")
 
 
-__api__ = [
+__all__ = [
     'conf95',
     'mean',
     'bw'

sierra/core/storage.py

@@ -2,55 +2,36 @@
 #
 #  SPDX-License-Identifier: MIT
 """
-Terminal interfare for the various storage plugins that come with SIERRA.
+Trampoline bindings for the various storage plugins that come with SIERRA.
 
-See :ref:`ln-sierra-tutorials-plugin-storage` for more details.
+See :ref:`tutorials/plugin/storage` for more details.
 """
 
 # Core packages
 import pathlib
-import typing as tp
 
 # 3rd party packages
 import pandas as pd
 
 # Project packages
-import sierra.core.plugin_manager as pm
+import sierra.core.plugin as pm
+from sierra.core.trampoline import cmdline_parser  # noqa: F401
 
 
-class DataFrameWriter():
+def df_read(path: pathlib.Path, medium: str, **kwargs) -> pd.DataFrame:
     """
-    Dispatcher to write a dataframe to the filesystem.
+    Dispatch "read from storage" request to active ``--storage`` plugin.
     """
+    storage = pm.pipeline.get_plugin_module(medium)
+    return storage.df_read(path, **kwargs)  # type: ignore
 
-    def __init__(self, medium: str):
-        self.medium = medium
 
-    def __call__(self,
-                 df: pd.DataFrame,
-                 path: tp.Union[pathlib.Path, str],
-                 **kwargs) -> None:
-        storage = pm.pipeline.get_plugin_module(self.medium)
-        return storage.df_write(df, path, **kwargs)  # type: ignore
-
-
-class DataFrameReader():
+def df_write(df: pd.DataFrame, path: pathlib.Path, medium: str, **kwargs) -> None:
     """
-    Dispatcher to read a dataframe from the filesystem.
-
+    Dispatch "write to storage" request to active ``--storage`` plugin.
     """
-
-    def __init__(self, medium: str):
-        self.medium = medium
-
-    def __call__(self,
-                 path: tp.Union[pathlib.Path, str],
-                 **kwargs) -> pd.DataFrame:
-        storage = pm.pipeline.get_plugin_module(self.medium)
-        return storage.df_read(path, **kwargs)  # type: ignore
+    storage = pm.pipeline.get_plugin_module(medium)
+    return storage.df_write(df, path, **kwargs)  # type: ignore
 
 
-__api__ = [
-    'DataFrameWriter',
-    'DataFrameReader'
-]
+__all__ = ["df_read", "df_write"]