Updating FileRecordStream docstrings

docs/README.md

@@ -14,6 +14,7 @@ sphinx-autobuild  ${NUPIC}/docs/source  ${NUPIC}/docs/_build_html  \
 List of NuPIC packages and their documentation status:
 * `TODO`: Package doc needs to be reviewed and potentially converted to RST
 * `OK`: Package RST doc reviewed and approved.
+* `DEFER`: Would be nice to document, but not necessary for 1.0
 
 ```
 nupic
@@ -27,10 +28,9 @@ nupic
 │   ├── sdr_classifier.py [OK]
 │   └── sdr_classifier_factory.py [OK]
 ├── data
-│   ├── CategoryFilter.py [TODO]
-│   ├── aggregator.py [TODO]
-│   ├── dictutils.py [TODO]
-│   ├── fieldmeta.py [TODO]
+│   ├── aggregator.py [DEFER]
+│   ├── dictutils.py [DEFER]
+│   ├── fieldmeta.py [OK]
 │   ├── file_record_stream.py [TODO]
 │   ├── filters.py [TODO]
 │   ├── functionsource.py [TODO]

docs/source/api/algorithms/encoders.rst

@@ -48,14 +48,3 @@ MultiEncoder
 .. autoclass:: nupic.encoders.multi.MultiEncoder
    :members:
    :show-inheritance:
-
-Data
-----
-
-FieldMetaType
-^^^^^^^^^^^^^
-
-.. autoclass:: nupic.data.fieldmeta.FieldMetaType
-   :members:
-   :private-members:
-   :undoc-members:

docs/source/api/data/field-meta.rst

@@ -0,0 +1,13 @@
+Field Meta
+^^^^^^^^^^
+
+.. automodule:: nupic.data.fieldmeta
+
+.. autoclass:: nupic.data.fieldmeta.FieldMetaInfo
+   :members:
+
+.. autoclass:: nupic.data.fieldmeta.FieldMetaType
+   :members:
+
+.. autoclass:: nupic.data.fieldmeta.FieldMetaSpecial
+   :members:

docs/source/api/data/index.rst

@@ -0,0 +1,14 @@
+Data
+====
+
+Data wrappers and helpers.
+
+.. include:: field-meta.rst
+
+FileRecordStream
+^^^^^^^^^^^^^^^^
+
+.. automodule:: nupic.data.file_record_stream
+
+.. autoclass:: nupic.data.file_record_stream.FileRecordStream
+   :members:

docs/source/api/index.rst

@@ -29,4 +29,4 @@ together your own system with encoders and classifiers.
     opf/index
     network/index
     algorithms/index
-    io
+    data/index

src/nupic/data/fieldmeta.py

@@ -19,10 +19,10 @@
 # http://numenta.org/licenses/
 # ----------------------------------------------------------------------
 
-
-# This script defines the structure of meta-data that describes the field name,
-# field type, special field attribute, etc. for a field in a dataset
-
+"""
+This module defines the structure of meta-data that describes the field name,
+field type, special field attribute, etc. for a field in a dataset.
+"""
 
 from collections import namedtuple
 
@@ -35,41 +35,36 @@
 class FieldMetaInfo(FieldMetaInfoBase):
   """
   This class acts as a container of meta-data for a single field (column) of
-  a dataset.
-
-  The layout is backward-compatible with the tuples exposed via the 'fields'
-  attribute of the legacy nupic.data.file.File class (in file.py). However, the
-  elements may be accessed in a less error-prone and more self-documenting way
-  using object attribute notation (e.g., fieldmeta.special instead of
-  fieldmeta[2]). Because namedtuple creates a subclass of tuple, the elements
-  can also be accessed using list access semantics and operations (i.e.,
-  fieldmeta[2])
+  a dataset. Each instance of this class has ``name``, ``type``, and ``special``
+  properties.
 
   Examples:
 
   1. Access a sub-element from an instance of FieldMetaInfo:
-        metainfo.name
-        metainfo.type
-        metainfo.special
 
-  2. Convert a single element from nupic.data.file.File.fields to FieldMetaInfo
+     - ``metainfo.name``
+     - ``metainfo.type``
+     - ``metainfo.special``
+
+  2. Create a single element of ``FieldMetaInfo`` from a tuple of ``name``,
+     ``type``, and ``special``:
+
+     .. code-block:: python
+
         e = ('pounds', FieldMetaType.float, FieldMetaSpecial.none)
         m = FieldMetaInfo.createFromFileFieldElement(e)
 
-  3.
+  :param str name: field name
+  :param str type: one of the values from FieldMetaType
+  :param str special: one of the values from FieldMetaSpecial
+  :raises ValueError: if type or special arg values are invalid
   """
 
 
   def __init__(self,
                name,
                type,  # pylint: disable=W0622
                special):
-    """
-    :param str name: field name
-    :param str type: one of the values from FieldMetaType
-    :param str special: one of the values from FieldMetaSpecial
-    :raises ValueError: if type or special arg values are invalid
-    """
 
     if not FieldMetaType.isValid(type):
       raise ValueError('Unexpected field type %r' % (type,))
@@ -82,38 +77,64 @@ def __init__(self,
 
   @staticmethod
   def createFromFileFieldElement(fieldInfoTuple):
-    """ Creates a FieldMetaInfo instance from an element of the File.fields list
-    of a nupic.data.file.File class instance.
+    """
+    Creates a :class:`.fieldmeta.FieldMetaInfo` instance from a tuple containing
+    ``name``, ``type``, and ``special``.
+
+    :param fieldInfoTuple: Must contain ``name``, ``type``, and ``special``
+    :return: :class:`~.fieldmeta.FieldMetaInfo` instance
     """
     return FieldMetaInfo._make(fieldInfoTuple)
 
 
   @classmethod
   def createListFromFileFieldList(cls, fields):
-    """ Creates a FieldMetaInfo list from the File.fields value of a
-    nupic.data.file.File class instance.
+    """
+    Creates a FieldMetaInfo list from the a list of tuples. Basically runs
+    :meth:`~.fieldmeta.FieldMetaInfo.createFromFileFieldElement` on each tuple.
+
+    *Example:*
 
-    fields: a sequence of field attribute tuples conforming to the format
-    of the File.fields attribute of a nupic.data.file.File class instance.
+    .. code-block:: python
 
-    Returns:  A list of FieldMetaInfo elements corresponding to the given
-              'fields' list.
+        # Create a list of FieldMetaInfo instances from a list of File meta-data
+        # tuples
+        el = [("pounds", FieldMetaType.float, FieldMetaSpecial.none),
+              ("price", FieldMetaType.float, FieldMetaSpecial.none),
+              ("id", FieldMetaType.string, FieldMetaSpecial.sequence),
+              ("date", FieldMetaType.datetime, FieldMetaSpecial.timestamp),
+             ]
+        ml = FieldMetaInfo.createListFromFileFieldList(el)
+
+    :param fields: a sequence of field attribute tuples conforming to the format
+                   of ``name``, ``type``, and ``special``
+
+    :return: A list of :class:`~.fieldmeta.FieldMetaInfo` elements corresponding
+             to the given 'fields' list.
     """
     return [cls.createFromFileFieldElement(f) for f in fields]
 
 
 
 class FieldMetaType(object):
   """
-  Public values for the field data types
+  Public values for the field data types. Valid types are:
+
+    - ``string``
+    - ``datetime``
+    - ``int``
+    - ``float``
+    - ``bool``
+    - ``list``
+    - ``sdr``
   """
   string = 'string'
   datetime = 'datetime'
   integer = 'int'
   float = 'float'
   boolean = 'bool'
   list = 'list'
-  sdr = 'sdr'  # sparse distributed representation
+  sdr = 'sdr'
 
   _ALL = (string, datetime, integer, float, boolean, list, sdr)
 
@@ -122,18 +143,23 @@ class FieldMetaType(object):
   def isValid(cls, fieldDataType):
     """Check a candidate value whether it's one of the valid field data types
 
-    :param str fieldDataType: candidate field data type
+    :param fieldDataType: (string) candidate field data type
     :returns: True if the candidate value is a legitimate field data type value;
-      False if not
-    :rtype: bool
+              False if not
     """
     return fieldDataType in cls._ALL
 
 
 
 class FieldMetaSpecial(object):
   """
-  Public values for the "special" field attribute
+  Public values for the "special" field attribute. Valid values are:
+
+    - ``R``: reset
+    - ``S``: sequence
+    - ``T``: timestamp
+    - ``C``: category
+    - ``L``: learning
   """
   none = ''
   reset = 'R'
@@ -149,9 +175,8 @@ class FieldMetaSpecial(object):
   def isValid(cls, attr):
     """Check a candidate value whether it's one of the valid attributes
 
-    :param str attr: candidate value
+    :param attr: (string) candidate value
     :returns: True if the candidate value is a legitimate "special" field
-      attribute; False if not
-    :rtype: bool
+              attribute; False if not
     """
     return attr in cls._ALL