Docs/context/context (#757)

* • Context docstring: added for module and for Context class _get_context_string replaced with get_context_string (removed underscore) * • Context docstring: added for module and for Context class flags_string: added as an attribute
PrincetonUniversity · Apr 13, 2018 · 1e23c31 · 1e23c31
1 parent 3a6ab54
commit 1e23c31
Show file tree

Hide file tree

Showing 2 changed files with 147 additions and 4 deletions.
diff --git a/psyneulink/globals/context.py b/psyneulink/globals/context.py
@@ -8,6 +8,69 @@
 #
 # ********************************************  System Defaults ********************************************************
 
+"""
+.. _Context_Overview:
+
+Overview
+--------
+The Context class is used for the `context <Component.context>` attribute of all `Components <Component>`.  It is
+set when a Component is first instantiated, and updated under various operating conditions.  Its primary
+attribute is `flags <Context.flags>` - a binary vector, the individual flags of which are specified using the
+`ContextFlags` enum.  The `flags <Context.flags>` attribute is divided functionally into the three fields:
+
+  * `initialization_status <Context.initialization_status>` - state of initialization of the Component;
+
+  * `execution_phase <Context.execution_phase>` - phase of execution of the Component;
+
+  * `source <Context.source>` - source of a call to a method belonging to or operating on the Component.
+
+Each field can be addressed using the corresponding property of the class, and in general only one of the flags
+in a field is set (although see individual property documentation for exceptions).
+
+Context and Logging
+-------------------
+
+The `flags <Context.flags>` attribute is used by `Log` to identify conditions for logging (see).  Accordingly, the
+`LogCondition`\(s) used to specify such conditions in the `set_log_conditions <Log.set_log_conditions>` method of Log
+are a subset of (and are aliased to) the flags in `ContextFlags`.
+
+.. _Context_Additional_Attributes:
+
+Additional Attributes
+---------------------
+
+In addition to `flags <Context.flags>`, Context has four other attributes that record information relevant to the
+operating state of the Component:
+
+    `owner <Context.owner>`
+      the Component to which the Context belongs (assigned to its `context <Component.context>` attribute;
+    `flags_string <Context.flags_string>`
+      a string containing the names of the flags currently set in each of the fields of the `flags <Context.flags>`
+      attribute;
+    `composition <Context.composition>`
+      the `Composition <Composition>` in which the Component is currently being executed;
+    `execution_id <Context.execution_id>`
+      the `execution_id` assigned to the Component by the Composition in which it is currently being executed;
+    `execution_time <Context.execution_time>`
+      the current time of the scheduler running the Composition within which the Component is currently being executed;
+    `string <Context.string>`
+      contains message(s) relevant to a method of the Component currently invoked or that is referencing the Component.
+      In general, this contains a copy of the **context** argument passed to method of the Component or one that
+      references it, but it is possible that future uses will involve other messages.
+
+    .. _Context_String_Note:
+
+    .. note::
+       The `string <Context.string>` attribute of Context is not the same as, nor does it usually contain the same
+       information as the string returned by the `flags_string <Context.flags_string>` method of Context.
+
+.. _Context_Class_Reference:
+
+Class Reference
+---------------
+
+"""
+
 from uuid import UUID
 from enum import IntEnum
 from collections import namedtuple
@@ -36,8 +99,9 @@ def __init__(self, error_value):
 
 
 class ContextFlags(IntEnum):
-    """Used to identify the status of a `Component` when its value or one of its attributes is being accessed.
-    Also used to specify the context in which a value of the Component or its attribute is `logged <Log_Conditions>`.
+    """Used to identify the status of a `Component <Component>` when its value or one of its attributes is being
+    accessed. Also used to specify the context in which a value of the Component or its attribute is `logged
+    <Log_Conditions>`.
     """
 
     UNSET = 0
@@ -69,6 +133,8 @@ class ContextFlags(IntEnum):
     EXECUTION_PHASE_MASK = PROCESSING | LEARNING | CONTROL | SIMULATION
     EXECUTING = EXECUTION_PHASE_MASK
     IDLE = ~EXECUTION_PHASE_MASK
+    """Identifies condition in which no flags in the `execution_phase <Context.execution_phase>` are set.
+    """
 
     # source (source-of-call) flags
     CONSTRUCTOR =   1<<9  # 512
@@ -170,6 +236,77 @@ class ContextStatus(IntEnum):
 
 
 class Context():
+    """Used to indicate the state of initialization and phase of execution of a Component, as well as the source of
+    call of a method;  also used to specify and identify `conditions <Log_Conditions>` for `logging <Log>`.
+
+
+    Attributes
+    ----------
+
+    owner : Component
+        Component to which the Context belongs.
+
+    flags : binary vector
+        represents the current operating context of the `owner <Context.owner>`; contains three fields
+        `initialization_status <Context.initialization_status>`, `execution_phase <Context.initialization_status>`,
+        and `source <Context.source>` (described below).
+
+    initialization_status :  field of flags attribute
+        indicates the state of initialization of the Component;
+        one and only one of the following flags is always set:
+
+            * `DEFERRED_INIT <ContextFlags.DEFERRED_INIT>`
+            * `INITIALIZING <ContextFlags.INITIALIZING>`
+            * `VALIDATING <ContextFlags.VALIDATING>`
+            * `INITIALIZED <ContextFlags.INITIALIZED>`
+            * `REINITIALIZED <ContextFlags.REINITIALIZED>`
+
+    execution_phase :  field of flags attribute
+        indicates the phase of execution of the Component;
+        one or more of the following flags can be set:
+
+            * `PROCESSING <ContextFlags.PROCESSING>`
+            * `LEARNING <ContextFlags.LEARNING>`
+            * `CONTROL <ContextFlags.CONTROL>`
+            * `SIMULATION <ContextFlags.SIMULATION>`
+        If no flags are set, the Component is not being executed at the current time, and `flags_string
+        <Context.flags_string>` will include *IDLE* in the string.  In some circumstances all of the
+        `execution_phase <Context.execution_phase>` flags may be set, in which case `flags_string
+        <Context.flags_string>` will include *EXECUTING* in the string.
+
+    source :  field of the flags attribute
+        indicates the source of a call to a method belonging to or referencing the Component;
+        one of the following flags is always set:
+
+            * `CONSTRUCTOR <ContextFlags.CONSTRUCTOR>`
+            * `COMMAND_LINE <ContextFlags.COMMAND_LINE>`
+            * `COMPONENT <ContextFlags.COMPONENT>`
+            * `COMPOSITION <ContextFlags.COMPOSITION>`
+
+    COMMENT:
+       REINSTATE ONCE flags_string property IS SUPPRESSED IN Context.rst
+    flags_string : str
+        contains the names of the flags currently set in each of the fields of the `flags <Context.flags>` attribute;
+        note that this is *not* the same as the `string <Context.string>` attribute (see `note <Context_String_Note>`).
+    COMMENT
+
+    composition : Composition
+      the `Composition <Composition>` in which the `owner <Context.owner>` is currently being executed.
+
+    execution_id : UUID
+      the execution_id assigned to the Component by the Composition in which it is currently being executed.
+
+    execution_time : TimeScale
+      current time of the `Scheduler` running the Composition within which the Component is currently being executed.
+
+    string : str
+      contains message(s) relevant to a method of the Component currently invoked or that is referencing the Component.
+      In general, this contains a copy of the **context** argument passed to method of the Component or one that
+      references it, but it is possible that future uses will involve other messages.  Note that this is *not* the
+      same as the `flags_string <Context.flags_string>` attribute (see `note <Context_String_Note>`).
+
+    """
+
     __name__ = 'Context'
     def __init__(self,
                  owner,
@@ -321,6 +458,12 @@ def update_execution_time(self):
             raise ContextError("PROGRAM ERROR: attempt to call update_execution_time for {} "
                                "when 'EXECUTING' was not in its context".format(self.owner.name))
 
+    @property
+    def flags_string(self, string=None):
+        """String with names of flags currently set in the owner's `flags <Context.flags>` attribute,
+        possibly prepended by an additional string.
+        """
+        return ContextFlags._get_context_string(self.owner.context.flags, string)
 
 @tc.typecheck
 def _get_context(context:tc.any(ContextFlags, str)):

diff --git a/psyneulink/globals/log.py b/psyneulink/globals/log.py
@@ -686,7 +686,7 @@ def __init__(self, owner, entries=None):
             return
 
     def set_log_conditions(self, items, log_condition=LogCondition.EXECUTION):
-        """Specifies items to be logged at the specified `LogCondition`\\(s).
+        """Specifies items to be logged under the specified `LogCondition`\\(s).
 
         Arguments
         ---------
@@ -835,7 +835,7 @@ def _log_value(self, value, time=None, context=None):
                 context_flags = _get_context(context)
 
             context_flags_string = ContextFlags._get_context_string(context_flags)
-            context_status_string = ContextFlags._get_context_string(self.owner.context.flags)
+            context_status_string = self.owner.context.flags_string
             # assert context_flags_string == context_status_string
 
             log_pref = self.owner.prefs.logPref if self.owner.prefs else None