added by_name loader with LRU cache

added lru_caching to by-name lookups

global accessor works, but namespaces still a problem

cache works for different namespaces, all tests pass

changed _helpers to helpers

Author: gegnew

README.md

@@ -17,4 +17,18 @@ experiments = client.experiments
 exp = cellengine.Experiment(name="160311-96plex-4dye")
 ```
 
+##Developer Notes
+- `id` is a python builtin, which causes some confusion. We use `_id` to indicate
+the ID of an API object, but the `attrs` package does not accept leading
+underscores as a keyword argument. In other words, an init arg `_id = attr.ib()` in a
+class must be passed to instantiate that class as `id`. In every other case,
+the variable `_id` should be used. Practically, this means:
+    - pass `_id` to functions that take an ID as an argument. This is the only
+      situation a user should encounter.
+    - pass `id` instead of `_id` to `attrs` classes when instantiating them.
+      This should only happen inside the SDK; a user should never have to pass
+      `id` instead of `_id`.
+    - pass `properties` instead of `_properties` to `attrs` classes when
+      instantiating them. A user should probably never have to pass
+      `_properties` at all; this should be managed behind the scenes.
 

cellengine/Gates/__init__.py

@@ -1,4 +1,4 @@
-from .gate_util import delete_gates, get_fcsfile
+from .gate_util import delete_gates
 from .rectangle_gate import create_rectangle_gate
 from .polygon_gate import create_polygon_gate
 from .ellipse_gate import create_ellipse_gate

cellengine/Gates/ellipse_gate.py

@@ -1,13 +1,29 @@
 from custom_inherit import doc_inherit
-from .gate_util import common_gate_create, gate_style
-from .. import _helpers
-
-@doc_inherit(common_gate_create, style=gate_style)
-def create_ellipse_gate(experiment_id, x_channel, y_channel, name,
-                        x, y, angle, major, minor, label=[], gid=None, locked=False,
-                        parent_population_id=None, parent_population=None,
-                        tailored_per_file=False, fcs_file_id=None,
-                        fcs_file=None, create_population=True):
+from .gate_util import create_common_gate, gate_style
+from .. import helpers
+
+
+@doc_inherit(create_common_gate, style=gate_style)
+def create_ellipse_gate(
+    experiment_id,
+    x_channel,
+    y_channel,
+    name,
+    x,
+    y,
+    angle,
+    major,
+    minor,
+    label=[],
+    gid=None,
+    locked=False,
+    parent_population_id=None,
+    parent_population=None,
+    tailored_per_file=False,
+    fcs_file_id=None,
+    fcs_file=None,
+    create_population=True,
+):
     """Creates an ellipse gate.
 
     Args:
@@ -30,25 +46,30 @@ def create_ellipse_gate(experiment_id, x_channel, y_channel, name,
     if label == []:
         label = [x, y]
     if gid is None:
-        gid = _helpers.generate_id()
+        gid = helpers.generate_id()
 
     model = {
-        'locked': locked,
-        'label': label,
-        'ellipse': {'angle': angle, 'major': major, 'minor': minor, 'center': [x, y]}
+        "locked": locked,
+        "label": label,
+        "ellipse": {"angle": angle, "major": major, "minor": minor, "center": [x, y]},
     }
 
     body = {
-        'experimentId': experiment_id,
-        'name': name,
-        'type': 'EllipseGate',
-        'gid': gid,
-        'xChannel': x_channel,
-        'yChannel': y_channel,
-        'parentPopulationId': parent_population_id,
-        'model': model
+        "experimentId": experiment_id,
+        "name": name,
+        "type": "EllipseGate",
+        "gid": gid,
+        "xChannel": x_channel,
+        "yChannel": y_channel,
+        "parentPopulationId": parent_population_id,
+        "model": model,
     }
 
-    return common_gate_create(experiment_id, body=body,
-            tailored_per_file=tailored_per_file, fcs_file_id=fcs_file_id,
-            fcs_file=fcs_file, create_population=create_population)
+    return create_common_gate(
+        experiment_id,
+        body=body,
+        tailored_per_file=tailored_per_file,
+        fcs_file_id=fcs_file_id,
+        fcs_file=fcs_file,
+        create_population=create_population,
+    )

cellengine/Gates/gate_util.py

@@ -1,11 +1,12 @@
+from cellengine import loader
 import re
-
-from ..fcsfile import FcsFile
 from .. import gate  # circular import here
-from .. import _helpers
+from .. import helpers
+
+cellengine = __import__(__name__.split(".")[0])
 
 
-def common_gate_create(
+def create_common_gate(
     experiment_id, body, tailored_per_file, fcs_file_id, fcs_file, create_population
 ):
     """
@@ -51,8 +52,8 @@ def common_gate_create(
         experiment_id, body, tailored_per_file, fcs_file_id, fcs_file
     )
 
-    body = _helpers.convert_dict(body, "snake_to_camel")
-    res = _helpers.base_create(
+    body = helpers.convert_dict(body, "snake_to_camel")
+    res = helpers.base_create(
         gate.Gate,
         url="experiments/{0}/gates".format(experiment_id),
         expected_status=201,
@@ -68,24 +69,13 @@ def parse_fcs_file_args(experiment_id, body, tailored_per_file, fcs_file_id, fcs
     if fcs_file is not None and fcs_file_id is not None:
         raise ValueError("Please specify only 'fcs_file' or 'fcs_file_id'.")
     if fcs_file is not None and tailored_per_file is True:  # lookup by name
-        _file = get_fcsfile(experiment_id, name=fcs_file)
+        _file = loader.get_fcsfile(experiment_id, name=fcs_file)
         fcs_file_id = _file._id
     body["tailoredPerFile"] = tailored_per_file
     body["fcsFileId"] = fcs_file_id
     return body
 
 
-def get_fcsfile(experiment_id, _id=None, name=None):
-    if _id:
-        content = _helpers.base_get(
-            "experiments/{0}/fcsfiles/{1}".format(experiment_id, _id)
-        )
-        content = FcsFile(properties=content)
-    else:
-        content = _helpers.load_fcsfile_by_name(experiment_id, name)
-    return content
-
-
 def create_gates(experiment_id=None, gates=None, create_all_populations=True):
     """Create multiple gates.
 
@@ -112,8 +102,10 @@ def create_gates(experiment_id=None, gates=None, create_all_populations=True):
                     ``help(cellengine.Gate.<Gate Type>)``.
             fcs_file_id (optional): ``str``: ID of FCS file, if tailored per file. Use
                 ``None`` for the global gate in the tailored gate group.
-            tailored_per_file (optional): ``bool``: Whether this gate is tailored per FCS file.
-            names (optional): ``list(str)``: For compound gates, a list of gate names.
+            tailored_per_file (optional): ``bool``: Whether this gate is
+                tailored per FCS file.
+                names (optional): ``list(str)``: For
+                compound gates, a list of gate names.
             create_population (optional): Whether to create populations for each gate.
         create_populations: Whether to create populations for all gates. If set
         to False, ``create_population`` may be specified for each gate.
@@ -123,9 +115,9 @@ def create_gates(experiment_id=None, gates=None, create_all_populations=True):
     """
     prepared_gates = []
     for g in gates:
-        g.update({"_id": _helpers.generate_id()})
+        g.update({"_id": helpers.generate_id()})
         if "gid" not in g.keys():
-            g.update({"gid": _helpers.generate_id()})
+            g.update({"gid": helpers.generate_id()})
         prepared_gates.append(g)
 
     new_gates = []
@@ -134,7 +126,7 @@ def create_gates(experiment_id=None, gates=None, create_all_populations=True):
             create_populations = each_gate.get("create_population", False)
         else:
             create_populations = create_all_populations
-        new_gate = common_gate_create(
+        new_gate = create_common_gate(
             experiment_id=each_gate.get("experiment_id", experiment_id),
             body=each_gate,
             tailored_per_file=each_gate.get("tailored_per_file", False),
@@ -177,7 +169,7 @@ def delete_gates(experiment_id, _id=None, gid=None, exclude=None):
         if exclude:
             url = "{0}%exclude={1}".format(url, exclude)
 
-    _helpers.base_delete(url)
+    helpers.base_delete(url)
 
 
 def gate_style(prnt_doc, child_doc):

cellengine/Gates/polygon_gate.py

@@ -1,10 +1,10 @@
 import numpy
 from custom_inherit import doc_inherit
-from .gate_util import common_gate_create, gate_style
-from .. import _helpers
+from .gate_util import create_common_gate, gate_style
+from .. import helpers
 
 
-@doc_inherit(common_gate_create, style=gate_style)
+@doc_inherit(create_common_gate, style=gate_style)
 def create_polygon_gate(experiment_id, x_channel, y_channel, name,
                         x_vertices,  y_vertices, label=[], gid=None, locked=False,
                         parent_population_id=None, parent_population=None,
@@ -29,7 +29,7 @@ def create_polygon_gate(experiment_id, x_channel, y_channel, name,
     if label == []:
         label = [numpy.mean(x_vertices), numpy.mean(y_vertices)]
     if gid is None:
-        gid = _helpers.generate_id()
+        gid = helpers.generate_id()
 
     model = {
         'locked': locked,
@@ -48,7 +48,7 @@ def create_polygon_gate(experiment_id, x_channel, y_channel, name,
         'model': model
     }
 
-    return common_gate_create(experiment_id, body=body,
+    return create_common_gate(experiment_id, body=body,
                               tailored_per_file=tailored_per_file,
                               fcs_file_id=fcs_file_id, fcs_file=fcs_file,
                               create_population=create_population)

cellengine/Gates/quadrant_gate.py

@@ -1,10 +1,10 @@
 from math import pi
 from custom_inherit import doc_inherit
-from .. import _helpers
-from .gate_util import common_gate_create, gate_style
+from .. import helpers
+from .gate_util import create_common_gate, gate_style
 
 
-@doc_inherit(common_gate_create, style=gate_style)
+@doc_inherit(create_common_gate, style=gate_style)
 def create_quadrant_gate(experiment_id, x_channel, y_channel, name,
                          x, y, labels=[], gid=None, gids=None, locked=False,
                          parent_population_id=None, parent_population=None,
@@ -38,7 +38,7 @@ def create_quadrant_gate(experiment_id, x_channel, y_channel, name,
     angles = [pi/2, pi, 3/2*pi, 0.000000]
 
     # set labels based on axis scale
-    r = _helpers.base_get(f'experiments/{experiment_id}/scalesets')[0]
+    r = helpers.base_get(f'experiments/{experiment_id}/scalesets')[0]
     scale_min = min(x['scale']['minimum'] for x in r['scales'])
     scale_max = max(x['scale']['minimum'] for x in r['scales'])
 
@@ -54,10 +54,10 @@ def create_quadrant_gate(experiment_id, x_channel, y_channel, name,
         raise ValueError('Labels must be a list of four length-2 lists.')
 
     if gid is None:
-        gid = _helpers.generate_id()
+        gid = helpers.generate_id()
         if gids is None:
-            gids = [_helpers.generate_id(), _helpers.generate_id(),
-                    _helpers.generate_id(), _helpers.generate_id()]
+            gids = [helpers.generate_id(), helpers.generate_id(),
+                    helpers.generate_id(), helpers.generate_id()]
 
     names = [name + append for append in [" (UR)", " (UL)", " (LL)", " (LR)"]]
 
@@ -80,7 +80,7 @@ def create_quadrant_gate(experiment_id, x_channel, y_channel, name,
         'model': model
     }
 
-    return common_gate_create(experiment_id, body=body,
+    return create_common_gate(experiment_id, body=body,
                               tailored_per_file=tailored_per_file,
                               fcs_file_id=fcs_file_id,
                               fcs_file=fcs_file, create_population=create_population)

cellengine/Gates/range_gate.py

@@ -1,10 +1,10 @@
 import numpy
 from custom_inherit import doc_inherit
-from .. import _helpers
-from .gate_util import common_gate_create, gate_style
+from .. import helpers
+from .gate_util import create_common_gate, gate_style
 
 
-@doc_inherit(common_gate_create, style=gate_style)
+@doc_inherit(create_common_gate, style=gate_style)
 def create_range_gate(experiment_id, x_channel, name,
                       x1, x2, y=0.5, label=[], gid=None, locked=False,
                       parent_population_id=None, parent_population=None,
@@ -32,7 +32,7 @@ def create_range_gate(experiment_id, x_channel, name,
     if label == []:
         label = [numpy.mean([x1, x2]), y]
     if gid is None:
-        gid = _helpers.generate_id()
+        gid = helpers.generate_id()
 
     model = {
         'locked': locked,
@@ -50,7 +50,7 @@ def create_range_gate(experiment_id, x_channel, name,
         'model': model
     }
 
-    return common_gate_create(experiment_id, body=body,
+    return create_common_gate(experiment_id, body=body,
                               tailored_per_file=tailored_per_file,
                               fcs_file_id=fcs_file_id,
                               fcs_file=fcs_file, create_population=create_population)

cellengine/Gates/rectangle_gate.py

@@ -1,10 +1,10 @@
 import numpy
 from custom_inherit import doc_inherit
-from .. import _helpers
-from .gate_util import common_gate_create, gate_style
+from .. import helpers
+from .gate_util import create_common_gate, gate_style
 
 
-@doc_inherit(common_gate_create, style=gate_style)
+@doc_inherit(create_common_gate, style=gate_style)
 def create_rectangle_gate(experiment_id, x_channel, y_channel, name,
                           x1, x2, y1, y2, label=[], gid=None, locked=False,
                           parent_population_id=None, parent_population=None,
@@ -33,7 +33,7 @@ def create_rectangle_gate(experiment_id, x_channel, y_channel, name,
     if label == []:
         label = [numpy.mean([x1, x2]), numpy.mean([y1, y2])]
     if gid is None:
-        gid = _helpers.generate_id()
+        gid = helpers.generate_id()
 
     model = {
         'locked': locked,
@@ -52,7 +52,7 @@ def create_rectangle_gate(experiment_id, x_channel, y_channel, name,
         'model': model
     }
 
-    return common_gate_create(experiment_id, body=body,
+    return create_common_gate(experiment_id, body=body,
                               tailored_per_file=tailored_per_file,
                               fcs_file_id=fcs_file_id,
                               fcs_file=fcs_file, create_population=create_population)

cellengine/Gates/split_gate.py

@@ -1,9 +1,9 @@
 from custom_inherit import doc_inherit
-from .. import _helpers
-from .gate_util import common_gate_create, gate_style
+from .. import helpers
+from .gate_util import create_common_gate, gate_style
 
 
-@doc_inherit(common_gate_create, style=gate_style)
+@doc_inherit(create_common_gate, style=gate_style)
 def create_split_gate(experiment_id, x_channel, name,
                       x, y, labels=[], gid=None, gids=None, locked=False,
                       parent_population_id=None, parent_population=None,
@@ -31,7 +31,7 @@ def create_split_gate(experiment_id, x_channel, name,
             y=100000)
         """
     # set labels based on axis scale
-    r = _helpers.base_get(f'experiments/{experiment_id}/scalesets')[0]
+    r = helpers.base_get(f'experiments/{experiment_id}/scalesets')[0]
     scale_min = min(x['scale']['minimum'] for x in r['scales'])
     scale_max = max(x['scale']['minimum'] for x in r['scales'])
 
@@ -44,9 +44,9 @@ def create_split_gate(experiment_id, x_channel, name,
         raise ValueError('Labels must be a list of two length-2 lists.')
 
     if gid is None:
-        gid = _helpers.generate_id()
+        gid = helpers.generate_id()
         if gids is None:
-            gids = [_helpers.generate_id(), _helpers.generate_id()]
+            gids = [helpers.generate_id(), helpers.generate_id()]
 
     names = [name + ' (L)', name + ' (R)']
 
@@ -67,7 +67,7 @@ def create_split_gate(experiment_id, x_channel, name,
         'model': model
     }
 
-    return common_gate_create(experiment_id, body=body,
+    return create_common_gate(experiment_id, body=body,
                               tailored_per_file=tailored_per_file,
                               fcs_file_id=fcs_file_id,
                               fcs_file=fcs_file, create_population=create_population)