RF: update docs, remove unnecessary try:except (setattr accepts invalid identifiers)

fsl/wrappers/wrapperutils.py

@@ -447,19 +447,22 @@ class _FileOrThing(object):
 
     Functions decorated with a ``_FileOrThing`` decorator will always return a
     ``dict``-like object, where the function's actual return value is
-    accessible via an attribute called ``output``. All output arguments with a
+    accessible via an attribute called ``stdout``. All output arguments with a
     value of ``LOAD`` will be present as dictionary entries, with the keyword
-    argument names used as keys. Any ``LOAD`` output arguments which were not
-    generated by the function will not be present in the dictionary.
+    argument names used as keys; these values will also be accessible as
+    attributes of the results dict, when possible. Any ``LOAD`` output
+    arguments which were not generated by the function will not be present in
+    the dictionary.
 
 
     **Cluster submission**
 
 
     The above description holds in all situations, except when an argument
-    called ``submit`` is passed, and is set to ``True``. In this case, the
-    ``_FileOrThing`` decorator will pass all arguments straight through to the
-    decorated function, and will return its return value unchanged.
+    called ``submit`` is passed, and is set to a value which evaluates to
+    ``True``. In this case, the ``_FileOrThing`` decorator will pass all
+    arguments straight through to the decorated function, and will return its
+    return value unchanged.
 
 
     This is because most functions that are decorated with the
@@ -509,20 +512,23 @@ class _FileOrThing(object):
 
         # The function's return value
         # is accessed via an attribute called
-        # "output" on the dict
-        assert concat('atob.txt', 'btoc.txt', 'atoc.mat').output == 'Done'
+        # "stdout" on the dict
+        assert concat('atob.txt', 'btoc.txt', 'atoc.mat').stdout == 'Done'
 
         # Outputs to be loaded into memory
         # are returned in a dictionary,
-        # with argument names as keys.
+        # with argument names as keys. Values
+        # can be accessed as dict items, or
+        # as attributes.
         atoc = concat('atob.txt', 'btoc.txt', LOAD)['atoc']
+        atoc = concat('atob.txt', 'btoc.txt', LOAD).atoc
 
         # In-memory inputs are saved to
         # temporary files, and those file
         # names are passed to the concat
         # function.
         atoc = concat(np.diag([2, 2, 2, 0]),
-                      np.diag([3, 3, 3, 3]), LOAD)['atoc']
+                      np.diag([3, 3, 3, 3]), LOAD).atoc
 
 
     **Using with other decorators**
@@ -548,7 +554,7 @@ class _FileOrThing(object):
 
         Where possible (i.e. for outputs named with a valid Python
         identifier), the outputs are also made accessible as attributes of
-        this
+        the ``_Results`` object.
 
         The decorated function's actual return value is accessible via the
         :meth:`stdout` property.
@@ -567,18 +573,10 @@ class _FileOrThing(object):
 
 
         def __setitem__(self, key, val):
-            """Add an item to the dict. The item is also added as an attribute
-            if possible.
+            """Add an item to the dict. The item is also added as an attribute.
             """
             super().__setitem__(key, val)
-
-            # try and add as an attribute too,
-            # but don't bother if the key cannot
-            # be used as a python identifier
-            try:
-                setattr(self, key, val)
-            except AttributeError:
-                pass
+            setattr(self, key, val)
 
 
         @property