INTU-1190 | Add comments everywhere and sanitize according to PEP-8 c…

…ompliance
watson-intu · Apr 11, 2017 · cd8bba2 · cd8bba2
1 parent c731c87
commit cd8bba2
Show file tree

Hide file tree

Showing 17 changed files with 1,087 additions and 950 deletions.
diff --git a/README.md b/README.md
@@ -1,8 +1,12 @@
 # self-python-sdk
 
+This is the Intu SDK written in Python. The SDK is a thin WebSocket-based client that lets users make
+WebSocket connections to a running Intu instance, as well as create their own custom gestures, sensors, and
+agents that they can then plug in into the system. The whole system follows the publish-subscribe pattern.
+
 1) Requirements
 
-Need ws4py installed (pip install wsp4)
+Need ws4py installed (pip install ws4py)
 
 2) How to test
 

diff --git a/self/agents/agent.py b/self/agents/agent.py
@@ -1,25 +1,32 @@
-# Copyright 2016 IBM All Rights Reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#      http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
+'''
+Copyright 2016 IBM All Rights Reserved.
 
-class Agent(object):
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
 
-	def __init__(self, agent_name, agent_id):
-		self.agent_name = agent_name
-		self.agent_id = agent_id
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+'''
+
+class Agent(object):
+    ''' An agent in the Intu universe is an entity that can subscribe to
+    the blackboard for objects it is interested in. Additionally, they
+    can subscribe to different levels of events for those objects
+    '''
+    def __init__(self, agent_name, agent_id):
+        self.agent_name = agent_name
+        self.agent_id = agent_id
 
-	def get_agent_name(self):
-		return self.agent_name
+    def get_agent_name(self):
+        ''' Return the name of the agent '''
+        return self.agent_name
 
-	def get_agent_id(self):
-		return self.agent_id
+    def get_agent_id(self):
+        ''' Return the ID of the agent '''
+        return self.agent_id
diff --git a/self/agents/agent_society.py b/self/agents/agent_society.py
@@ -1,75 +1,85 @@
-# Copyright 2016 IBM All Rights Reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#      http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
+'''
+Copyright 2016 IBM All Rights Reserved.
 
-from self.topics.topic_client import TopicClient
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+'''
 
 import collections
 import json
+from self.topics.topic_client import TopicClient
 
-class AgentSociety:
+class AgentSociety(object):
+    ''' Represents a collection of agents running at a given time '''
 
-	__instance = None
+    __instance = None
 
-	def __init__(self):		
-		self.agent_map = collections.defaultdict(set)
-		self.overrides_map = collections.defaultdict(set)
+    def __init__(self):
+        self.agent_map = collections.defaultdict(set)
+        self.overrides_map = collections.defaultdict(set)
 
-	@staticmethod
-	def get_instance():
-		if AgentSociety.__instance == None:
-			AgentSociety.__instance = AgentSociety()
-		return AgentSociety.__instance
+    @staticmethod
+    def get_instance():
+        ''' Return a singleton instance of the society '''
+        if AgentSociety.__instance is None:
+            AgentSociety.__instance = AgentSociety()
+        return AgentSociety.__instance
 
-	def on_event(self, data):
-		error = False
-		payload = json.loads(data)
-		if payload['agentId'] not in self.agent_map:
-			print "Could not find agent id: " + payload['agentId']
-			error = True
-		elif payload['event'] == 'start_agent':
-			self.agent_map[payload['agentId']].on_start()
-		elif payload['event'] == 'stop_agent':
-			self.agent_map[payload['agentId']].on_stop()
+    def on_event(self, data):
+        ''' Callback that can add or remove proxy agents to and from the
+        society '''
+        error = False
+        payload = json.loads(data)
+        if payload['agentId'] not in self.agent_map:
+            print "Could not find agent id: " + payload['agentId']
+            error = True
+        elif payload['event'] == 'start_agent':
+            self.agent_map[payload['agentId']].on_start()
+        elif payload['event'] == 'stop_agent':
+            self.agent_map[payload['agentId']].on_stop()
 
-		if error:
-			data = {}
-			data['failed_event'] = payload['event']
-			data['event'] = 'error'
-			TopicClient.get_instance().publish('agent-society', data, False)
+        if error:
+            data = {}
+            data['failed_event'] = payload['event']
+            data['event'] = 'error'
+            TopicClient.get_instance().publish('agent-society', data, False)
 
-	def subscribe(self):
-		TopicClient.get_instance().subscribe('agent-society', self.on_event)
+    def subscribe(self):
+        ''' Subscribe to the agent-society topic '''
+        TopicClient.get_instance().subscribe('agent-society', self.on_event)
 
-	def add_agent(self, agent, override):
-		if agent.get_agent_id not in self.agent_map:
-			data = {}
-			data['event'] = 'add_agent_proxy'
-			data['agentId'] = agent.get_agent_id()
-			data['name'] = agent.get_agent_name()
-			data['override'] = override
-			TopicClient.get_instance().publish('agent-society', data, False)
-			self.agent_map[agent.get_agent_id()] = agent
-			self.overrides_map[agent.get_agent_id()] = override
+    def add_agent(self, agent, override):
+        ''' Add an agent to this society. The society takes ownership of the
+        agent '''
+        if agent.get_agent_id not in self.agent_map:
+            data = {}
+            data['event'] = 'add_agent_proxy'
+            data['agentId'] = agent.get_agent_id()
+            data['name'] = agent.get_agent_name()
+            data['override'] = override
+            TopicClient.get_instance().publish('agent-society', data, False)
+            self.agent_map[agent.get_agent_id()] = agent
+            self.overrides_map[agent.get_agent_id()] = override
 
-	def remove_agent(self, agent):
-		if agent.get_agent_id in self.agent_map:
-			self.overrides_map.remove(agent.get_agent_id())
-			self.agent_map.remove(agent.get_agent_id())
-			data = {}
-			data['event'] = 'remove_agent_proxy'
-			data['agentId'] = agent.get_agent_id()
-			TopicClient.get_instance().publish('agent-society', data, False)
+    def remove_agent(self, agent):
+        ''' Remove an agent from this society '''
+        if agent.get_agent_id in self.agent_map:
+            self.overrides_map.remove(agent.get_agent_id())
+            self.agent_map.remove(agent.get_agent_id())
+            data = {}
+            data['event'] = 'remove_agent_proxy'
+            data['agentId'] = agent.get_agent_id()
+            TopicClient.get_instance().publish('agent-society', data, False)
 
-	def shutdown(self):
-		TopicClient.get_instance().unsubscribe('agent-society')
+    def shutdown(self):
+        ''' Unsubscribe from the agent-society topic '''
+        TopicClient.get_instance().unsubscribe('agent-society')
diff --git a/self/agents/example_agent.py b/self/agents/example_agent.py
@@ -1,33 +1,40 @@
-# Copyright 2016 IBM All Rights Reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#      http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
+'''
+Copyright 2016 IBM All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+'''
 
 from self.agents.agent import Agent
 from self.blackboard.blackboard import Blackboard
 from self.blackboard.thing import ThingEventType
 
 class ExampleAgent(Agent):
-	def __init__(self, agent_name, agent_id):
-			super(self.__class__, self).__init__(agent_name, agent_id)
+    ''' An example agent implementation that can subscribe to Text objects on
+    the blackboard '''
+    def __init__(self, agent_name, agent_id):
+        super(self.__class__, self).__init__(agent_name, agent_id)
 
-	def on_text(self, payload):
-		print "ExampleAgent OnText(): " + payload['thing']['m_Text']
+    def on_text(self, payload):
+        ''' Handle a received Text object '''
+        print "ExampleAgent OnText(): " + payload['thing']['m_Text']
 
-	def on_start(self):
-		print "ExampleAgent has started!"
-		Blackboard.get_instance().subscribe_to_type("Text", ThingEventType.ADDED, "", self.on_text)
-		return True
+    def on_start(self):
+        ''' Start the agent and subscribe to the Text objects '''
+        print "ExampleAgent has started!"
+        Blackboard.get_instance().subscribe_to_type("Text", ThingEventType.ADDED, "", self.on_text)
+        return True
 
-	def on_stop(self):
-		print "ExampleAgent has stopped!"
-		return True
+    def on_stop(self):
+        ''' Put stopping logic here '''
+        print "ExampleAgent has stopped!"
+        return True