Merge pull request #3202 from openatv/IanSav-Element

[Element.py] Tidy up code

lib/python/Components/Element.py

@@ -1,39 +1,17 @@
-from Tools.CList import CList
 from functools import reduce
 
-
-# down                       up
-# Render Converter Converter Source
-
-# a bidirectional connection
-
-def cached(f):
-	name = f.__name__
-
-	def wrapper(self):
-		cache = self.cache
-		if cache is None:
-			return f(self)
-		if name not in cache:
-			cache[name] = (True, f(self))
-		return cache[name][1]
-	return wrapper
-
-
-class ElementError(Exception):
-	def __init__(self, message):
-		self.msg = message
-
-	def __str__(self):
-		return self.msg
+from Tools.CList import CList
 
 
+# Render (Down) - Converter - Converter - Source (Up)
+# A bidirectional connection.
+#
 class Element:
-	CHANGED_DEFAULT = 0   # initial "pull" state
-	CHANGED_ALL = 1       # really everything changed
-	CHANGED_CLEAR = 2     # we're expecting a real update soon. don't bother polling NOW, but clear data.
-	CHANGED_SPECIFIC = 3  # second tuple will specify what exactly changed
-	CHANGED_POLL = 4      # a timer expired
+	CHANGED_DEFAULT = 0  # Initial "pull" state.
+	CHANGED_ALL = 1  # Really everything changed.
+	CHANGED_CLEAR = 2  # We're expecting a real update soon, don't bother polling NOW, but clear data.
+	CHANGED_SPECIFIC = 3  # Second tuple will specify what exactly changed.
+	CHANGED_POLL = 4  # A timer has expired.
 
 	SINGLE_SOURCE = True
 
@@ -53,26 +31,20 @@ def connectDownstream(self, downstream):
 	def connectUpstream(self, upstream):
 		assert not self.SINGLE_SOURCE or self.source is None
 		self.sources.append(upstream)
-		# self.source always refers to the last recent source added.
-		self.source = upstream
+		self.source = upstream  # The self.source always refers to the last recent source added.
 		self.changed((self.CHANGED_DEFAULT,))
 
 	def connect(self, upstream):
 		self.connectUpstream(upstream)
 		upstream.connectDownstream(self)
 
-	# we disconnect from down to up
-	def disconnectAll(self):
-		# we should not disconnect from upstream if
-		# there are still elements depending on us.
+
+	def disconnectAll(self):  # We disconnect from down (Renderer) to up (Source).
+		# We should not disconnect from upstream if there are still elements depending on us.
 		assert len(self.downstream_elements) == 0, "there are still downstream elements left"
-
-		# Sources don't have a source themselves. don't do anything here.
-		for s in self.sources:
-			s.disconnectDownstream(self)
-
-		if self.source:
-			# sources are owned by the Screen, so don't destroy them here.
+		for source in self.sources:  # Sources don't have a source themselves. don't do anything here.
+			source.disconnectDownstream(self)
+		if self.source:  # Sources are owned by the Screen, so don't destroy them here.
 			self.destroy()
 		self.source = None
 		self.sources = []
@@ -81,12 +53,10 @@ def disconnectDownstream(self, downstream):
 		self.downstream_elements.remove(downstream)
 		if self.master == downstream:
 			self.master = None
-
 		if len(self.downstream_elements) == 0:
 			self.disconnectAll()
 
-	# default action: push downstream
-	def changed(self, *args, **kwargs):
+	def changed(self, *args, **kwargs):  # The default action is to push downstream.
 		self.cache = {}
 		self.downstream_elements.changed(*args, **kwargs)
 		self.cache = None
@@ -97,11 +67,10 @@ def setSuspend(self, suspended):
 			self.doSuspend(1)
 		elif self.__suspended and not suspended:
 			self.doSuspend(0)
-
 		self.__suspended = suspended
 		if changed:
-			for s in self.sources:
-				s.checkSuspend()
+			for source in self.sources:
+				source.checkSuspend()
 
 	suspended = property(lambda self: self.__suspended, setSuspend)
 
@@ -113,3 +82,24 @@ def doSuspend(self, suspend):
 
 	def destroy(self):
 		pass
+
+
+class ElementError(Exception):
+	def __init__(self, message):
+		self.msg = message
+
+	def __str__(self):
+		return self.msg
+
+
+def cached(item):
+	def wrapper(self):
+		cache = self.cache
+		if cache is None:
+			return item(self)
+		if name not in cache:
+			cache[name] = (True, item(self))
+		return cache[name][1]
+
+	name = item.__name__
+	return wrapper