improved docstrings and removed parent dependency for LiveEntities

Author: dduric

example_live_parser.py

@@ -4,28 +4,26 @@
 from hslog.live.parser import LiveLogParser
 
 
-"""
-	----------------------------------------------------------------------
-	LiveLogParser assumes that you"ve configured Power.log to be a symlink
-
-	in "SOME_PATH/Hearthstone/Logs" folder:
-		ln -s Power.log /tmp/hearthstone-redirected.log
-
-	this will redirect all data coming into Power.log
-	so we can access it from a RAM disk
-	----------------------------------------------------------------------
-	For better performance make /tmp of type tmpfs (or another location)
+def main():
+	"""
+		----------------------------------------------------------------------
+		LiveLogParser assumes that you"ve configured Power.log to be a symlink.
 
-	in /etc/fstab add line:
-		tmpfs	/tmp	tmpfs	nodev,nosuid,size=1G	0	0
+		In "SOME_PATH/Hearthstone/Logs" folder:
+			ln -s Power.log /tmp/hearthstone-redirected.log
 
-	this will create in-memory storage which is faster then SSD
-	you need to restart the computer for this to take effect
-	----------------------------------------------------------------------
-"""
+		This will redirect all data coming into Power.log
+		so we can access it from a RAM disk.
+		----------------------------------------------------------------------
+		For better performance make /tmp of type tmpfs (or another location)
 
+		In /etc/fstab add line:
+			tmpfs	/tmp	tmpfs	nodev,nosuid,size=1G	0	0
 
-def main():
+		This will create in-memory storage which is faster then SSD.
+		You need to restart the computer for this to take effect.
+		----------------------------------------------------------------------
+	"""
 	try:
 		file = "/tmp/hearthstone-redirected.log"
 		liveParser = LiveLogParser(file)

hslog/live/entities.py

@@ -4,14 +4,20 @@
 
 class LiveEntity(Entity):
 
-	def __init__(self, entity_id, parent, **kwargs):
-		""" Entity requires an ID, store everything else in kwargs """
-		self.parent = parent
-		self.game_index = self.parent.parser.games.index(self.parent)
-		super(LiveEntity, self).__init__(entity_id, **kwargs)
+	def __init__(self, entity_id):
+		super(LiveEntity, self).__init__(entity_id)
+		self._game = None
 
-		# push data to an end-point
-		print(f"GAME {self.game_index} --- ENTITY CREATED:", self)
+	@property
+	def game(self):
+		return self._game
+
+	@game.setter
+	def game(self, value):
+		self._game = value
+		if value is not None:
+			# push data to an end-point
+			print(f"GAME {self.game} --- ENTITY CREATED:", self)
 
 	def tag_change(self, tag, value):
 		if tag == GameTag.CONTROLLER and not self._initial_controller:
@@ -23,26 +29,23 @@ def tag_change(self, tag, value):
 
 	def update_callback(self):
 		# push data to an end-point
-		print(f"GAME {self.game_index} --- ENTITY UPDATED:", self)
-
-
-"""
-	* Card is called on export from game
-	* LiveCard replaces Card and inserts update_callback
-	* The point is to become able to route update events towards an API end-point
-"""
+		print(f"GAME {self.game} --- ENTITY UPDATED:", self)
 
 
 class LiveCard(Card, LiveEntity):
-
-	def __init__(self, entity_id, card_id, parent):
-		super(LiveCard, self).__init__(
-			entity_id=entity_id,
-			card_id=card_id,
-			parent=parent)
-
-	""" if card_id doesn"t change, there"s no need to pass it as the argument.
-		we can use self.card_id instead as it is set by Card class """
+	"""
+		Card is called on export from game
+		LiveCard replaces Card and inserts update_callback
+		The point is to become able to route update events towards an API end-point
+	"""
+
+	def __init__(self, entity_id, card_id):
+		super(LiveCard, self).__init__(entity_id, card_id)
+
+	"""
+		if card_id doesn't change, there's no need to pass it as the argument.
+		we can use self.card_id instead as it is set by Card class
+	"""
 	def reveal(self, card_id, tags):
 		self.revealed = True
 		self.card_id = card_id

hslog/live/export.py

@@ -3,28 +3,13 @@
 
 
 class LiveEntityTreeExporter(EntityTreeExporter):
+	"""
+		Inherits EntityTreeExporter to provide Live entities
+	"""
+
+	# game_class = LiveGame
+	# player_class = LivePlayer
 	card_class = LiveCard
 
 	def __init__(self, packet_tree):
 		super(LiveEntityTreeExporter, self).__init__(packet_tree)
-
-	def handle_full_entity(self, packet):
-		entity_id = packet.entity
-
-		# Check if the entity already exists in the game first.
-		# This prevents creating it twice.
-		# This can legitimately happen in case of GAME_RESET
-		if entity_id <= len(self.game.entities):
-			# That first if check is an optimization to prevent always looping over all of
-			# the game"s entities every single FULL_ENTITY packet...
-			# FIXME: Switching to a dict for game.entities would simplify this.
-			existing_entity = self.game.find_entity_by_id(entity_id)
-			if existing_entity is not None:
-				existing_entity.card_id = packet.card_id
-				existing_entity.tags = dict(packet.tags)
-				return existing_entity
-
-		entity = self.card_class(entity_id, packet.card_id, self.packet_tree)
-		entity.tags = dict(packet.tags)
-		self.game.register_entity(entity)
-		return entity

hslog/live/packets.py

@@ -10,4 +10,8 @@ def __init__(self, ts, parser):
 		super(LivePacketTree, self).__init__(ts)
 
 	def live_export(self, packet):
+		"""
+			Triggers packet export which will run the proper handler for the packet.
+			This will also run update_callback for entity being updated by the packet.
+		"""
 		return self.liveExporter.export_packet(packet)

hslog/live/parser.py

@@ -10,6 +10,16 @@
 
 
 class LiveLogParser(LogParser):
+	"""
+		LiveLogParser adds live log translation into useful data.
+
+		Lines are read and pushed into a deque by a separate thread.
+		Deque is emptied by parse_worker which replaces the read()
+		function of LogParser and it's also in a separate thread.
+
+		This approach is non-blocking and allows for live parsing
+		of incoming lines.
+	"""
 
 	def __init__(self, filepath):
 		super(LiveLogParser, self).__init__()
@@ -18,13 +28,27 @@ def __init__(self, filepath):
 		self.lines_deque = deque([])
 
 	def new_packet_tree(self, ts):
+		"""
+			LivePacketTree is introduced here because it instantiates LiveEntityTreeExporter
+			and keeps track of the parser parent. It also contains a function that
+			utilizes the liveExporter instance across all the games.
+
+			self.parser = parser
+			self.liveExporter = LiveEntityTreeExporter(self)
+		"""
 		self._packets = LivePacketTree(ts, self)
 		self._packets.spectator_mode = self.spectator_mode
 		self._packets.manager = PlayerManager()
 		self.current_block = self._packets
 		self.games.append(self._packets)
 
-		""" why is this return important? """
+		"""
+			why is this return important?
+			it's called only here:
+
+				def create_game(self, ts):
+					self.new_packet_tree(ts)
+		"""
 		return self._packets
 
 	def tag_change(self, ts, e, tag, value, def_change):
@@ -47,26 +71,35 @@ def tag_change(self, ts, e, tag, value, def_change):
 		return packet
 
 	def register_packet(self, packet, node=None):
-		""" make sure we"re registering packets to the current game"""
+		"""
+			LogParser.register_packet override
+
+			This uses the live_export functionality introduces by LivePacketTree
+			It also keeps track of which LivePacketTree is being used when there
+			are multiple in parser.games
+
+			A better naming for a PacketTree/LivePacketTree would be HearthstoneGame?
+			Then parser.games would contain HearthstoneGame instances and would
+			be more obvious what the purpose is.
+		"""
+
+		# make sure we're registering packets to the current game
 		if not self._packets or self._packets != self.games[-1]:
 			self._packets = self.games[-1]
 
 		if node is None:
 			node = self.current_block.packets
 		node.append(packet)
-
-		""" line below triggers packet export which will
-			run update_callback for entity being
-			updated by the packet.
-
-			self._packets == EntityTreeExporter
-		"""
 		self._packets.live_export(packet)
-
 		self._packets._packet_counter += 1
 		packet.packet_id = self._packets._packet_counter
 
 	def file_worker(self):
+		"""
+			File reader thread. (Naive implementation)
+			Reads the log file continuously and appends to deque.
+		"""
+
 		file = open(self.filepath, "r")
 		while self.running:
 			line = file.readline()
@@ -76,6 +109,9 @@ def file_worker(self):
 				time.sleep(0.2)
 
 	def parse_worker(self):
+		"""
+			If deque contains lines, this initiates parsing.
+		"""
 		while self.running:
 			if len(self.lines_deque):
 				line = self.lines_deque.popleft()