Inconsistent API in nupic.engine

[oxtopus]

What follows is mostly mental notes re: specific implementation details of network api.

Contrary to nupic.engine.Network, which is a subclass and wrapper for the swig-generated nupic.bindings.engine_internal.Network, nupic.engine.Region is a standalone class with its own properties and behaviors independent of nupiclbindings.engine_internal.Region. Consider the following example:

region = network.addRegion("region1", "TestNode", "")
region1 = network.getRegions().getByName("region1")

You might infer from the signature of Network.addRegion() that region and region1 would be the very same instance. However, region is an instance of nupic.engine.Region whereas region1 is an instance of nupic.bindings.engine_internal.Region. The reason for this is Network.addRegion() as it is implemented at https://github.com/numenta/nupic/blob/bfa052f3d5740b3934c2dcefc566ab0906f9af2e/src/nupic/engine/__init__.py#L641-L646 calls addRegion() on the internal implementation, but then separately returns the result of self._getRegions()[name]. Network._getRegions() wraps the result of engine_internal.Network.getRegions() such that the return value is another wrapper that implements a dict-like interface.

It seems like some of the complexity can be mitigated by implementing Network.addRegion() as something like the following:

def addRegion(self, name, nodeType, nodeParams):
    """
    @doc:place_holder(Network.addRegion)
    """
    engine_internal.Network.addRegion(self, name, nodeType, nodeParams)
    return self.getRegions().getByName(name)

Or:

def addRegion(self, name, nodeType, nodeParams):
    """
    @doc:place_holder(Network.addRegion)
    """
    return engine_internal.Network.addRegion(self, name, nodeType, nodeParams)

[rhyolight]

👍

[scottpurdy]

Now that the Python classes in nupic are subclasses of the SWIG classes, we can probably safely integrate them so that the SWIG interface provides the API we want and there is only one Python class per component.