docstrings

Author: dwhswenson

paths_cli/parameters.py

@@ -1,11 +1,20 @@
 import click
 import os
 
-_UNNAMED_STORES = ['snapshots', 'trajectories', 'samples', 'sample_sets',
-                   'steps']
-
 
 class AbstractParameter(object):
+    """Abstract wrapper for click parameters.
+
+    Forbids use setting ``required``, because we do that for each command
+    individually.
+
+    Parameters
+    ----------
+    args :
+        args to pass to click parameters
+    kwargs :
+        kwargs to pass to click parameters
+    """
     def __init__(self, *args, **kwargs):
         self.args = args
         if 'required' in kwargs:
@@ -15,32 +24,57 @@ def __init__(self, *args, **kwargs):
     def clicked(self, required=False):
         raise NotImplementedError()
 
+
 HELP_MULTIPLE = "; may be used more than once"
 
+
 # we'll use tests of the -h option in the .travis.yml to ensure that the
 # .clicked methods work
 class Option(AbstractParameter):
+    """Wrapper for click.option decorators"""
     def clicked(self, required=False):  # no-cov
+        """Create the click decorator"""
         return click.option(*self.args, **self.kwargs, required=required)
 
+
 class Argument(AbstractParameter):
+    """Wrapper for click.argument decorators"""
     def clicked(self, required=False):  # no-cov
+        """Create the click decorator"""
         return click.argument(*self.args, **self.kwargs, required=required)
 
 
 class AbstractLoader(object):
+    """Abstract object for getting relevant OPS object from the CLI.
+
+    Parameters
+    ----------
+    param : :class:`.AbstractParameter`
+        the Option or Argument wrapping a click decorator
+    """
     def __init__(self, param):
         self.param = param
 
     @property
     def clicked(self):  # no-cov
+        """Create the click decorator"""
         return self.param.clicked
 
     def get(self, *args, **kwargs):
+        """Get the desired OPS object, based on the CLI input"""
         raise NotImplementedError()
 
 
 class StorageLoader(AbstractLoader):
+    """Open an OPS storage file
+
+    Parameters
+    ----------
+    param : :class:`.AbstractParameter`
+        the Option or Argument wrapping a click decorator
+    mode : 'r', 'w', or 'a'
+        the mode for the file
+    """
     def __init__(self, param, mode):
         super(StorageLoader, self).__init__(param)
         self.mode = mode
@@ -61,12 +95,34 @@ def get(self, name):
 
 class OPSStorageLoadNames(AbstractLoader):
     """Simple loader that expects its input to be a name or index.
+
+    Parameters
+    ----------
+    param : :class:`.AbstractParameter`
+        the Option or Argument wrapping a click decorator
+    store : Str
+        the name of the store to search
     """
     def __init__(self, param, store):
         super(OPSStorageLoadNames, self).__init__(param)
         self.store = store
 
     def get(self, storage, names):
+        """Get the names from the storage
+
+        Parameters
+        ----------
+        storage : :class:`openpathsampling.Storage`
+            storage file to search in
+        names : List[Str]
+            names or numbers (as string) to use as keys to load from
+            storage
+
+        Returns
+        -------
+        List[Any] :
+            the desired objects
+        """
         int_corrected = []
         for name in names:
             try:
@@ -80,6 +136,13 @@ def get(self, storage, names):
 
 
 class Getter(object):
+    """Abstract strategy for getting things from storage
+
+    Parameters
+    ----------
+    store_name : Str
+        the name of the storage to search
+    """
     def __init__(self, store_name):
         self.store_name = store_name
 
@@ -90,11 +153,15 @@ def _get(self, storage, name):
         except:
             return None
 
+
 class GetByName(Getter):
+    """Strategy using the CLI input as name for a stored item"""
     def __call__(self, storage, name):
         return self._get(storage, name)
 
+
 class GetByNumber(Getter):
+    """Strategy using the CLI input as numeric index of the stored item"""
     def __call__(self, storage, name):
         try:
             num = int(name)
@@ -103,28 +170,36 @@ def __call__(self, storage, name):
 
         return self._get(storage, num)
 
+
 class GetPredefinedName(Getter):
+    """Strategy predefining name and store, allow default names"""
     def __init__(self, store_name, name):
         super().__init__(store_name=store_name)
         self.name = name
 
     def __call__(self, storage):
         return self._get(storage, self.name)
 
+
 class GetOnly(Getter):
+    """Strategy getting item from store if it is the only one"""
     def __call__(self, storage):
         store = getattr(storage, self.store_name)
         if len(store) == 1:
             return store[0]
 
+
 class GetOnlyNamed(Getter):
+    """Strategy selecting item from store if it is the only named item"""
     def __call__(self, storage):
         store = getattr(storage, self.store_name)
         named_things = [o for o in store if o.is_named]
         if len(named_things) == 1:
             return named_things[0]
 
+
 class GetOnlySnapshot(Getter):
+    """Strategy selecting only snapshot from a snapshot store"""
     def __init__(self, store_name="snapshots"):
         super().__init__(store_name)
 
@@ -147,7 +222,24 @@ class OPSStorageLoadSingle(AbstractLoader):
     """Objects that expect to load a single object.
 
     These can sometimes include guesswork to figure out which object is
-    desired.
+    desired. The details of how that guesswork is performed is determined
+    by the strategy lists that are given.
+
+    Parameters
+    ----------
+    param : :class:`.AbstractParameter`
+        the Option or Argument wrapping a click decorator
+    store : Str
+        the name of the store to search
+    value_strategies : List[Callable[(:class:`.Storage`, Str), Any]]
+        The strategies to be used when the CLI provides a value for this
+        parameter. Each should be a callable taking a storage and the string
+        input from the CLI, and should return the desired object or None if
+        it cannot be found.
+    none_strategies : List[Callable[:class:`openpathsampling.Storage, Any]]
+        The strategies to be used when the CLI does not provide a value for
+        this parameter. Each should be a callable taking a storage, and
+        returning the desired object or None if it cannot be found.
     """
     def __init__(self, param, store, value_strategies=None,
                  none_strategies=None):
@@ -164,9 +256,16 @@ def __init__(self, param, store, value_strategies=None,
         self.none_strategies = none_strategies
 
     def get(self, storage, name):
-        store = getattr(storage, self.store)
-        # num_store = getattr(storage, self.num_store)
-
+        """Load desired object from storage.
+
+        Parameters
+        ----------
+        storage : openpathsampling.Storage
+            the input storage to search
+        name : Str or None
+            string from CLI providing the identifier (name or index) for
+            this object; None if not provided
+        """
         if name is not None:
             result = _try_strategies(self.value_strategies, storage,
                                      name=name)
@@ -178,6 +277,7 @@ def get(self, storage, name):
 
         return result
 
+
 ENGINE = OPSStorageLoadSingle(
     param=Option('-e', '--engine', help="identifer for the engine"),
     store='engines',
@@ -187,7 +287,6 @@ def get(self, storage, name):
 SCHEME = OPSStorageLoadSingle(
     param=Option('-m', '--scheme', help="identifier for the move scheme"),
     store='schemes',
-    # fallback=None
 )
 
 INIT_CONDS = OPSStorageLoadSingle(