More doc-strings.

Paebbels · Paebbels · commit a2041f697b0e · 2026-02-05T00:56:04.000+01:00
diff --git a/pyEDAA/OutputFilter/Xilinx/Common2.py b/pyEDAA/OutputFilter/Xilinx/Common2.py
@@ -189,35 +189,84 @@ def Processor(self) -> "Processor":
 
 @export
 class Preamble(Parser):
-	_toolVersion:   Nullable[YearReleaseVersion]
-	_startDatetime: Nullable[datetime]
+	"""
+	A parser for the preamble emitted by Vivado at session start.
 
+	.. rubric:: Extracted information
+
+	* Vivado tool version. |br|
+	  See :data:`ToolVersion`
+	* Session start timestamp (date and time). |br|
+	  See :data:`StartDatetime`
+
+	.. rubric:: Example
+
+	.. code-block::
+
+	   #-----------------------------------------------------------
+	   # Vivado v2019.1 (64-bit)
+	   # SW Build 2552052 on Fri May 24 14:49:42 MDT 2019
+	   # IP Build 2548770 on Fri May 24 18:01:18 MDT 2019
+	   # Start of session at: Tue Sep  2 08:44:13 2025
+	   # Process ID: 35680
+	   # Current directory: C:/[...]/MercuryZX5_PE1.runs/synth_1
+	   # Command line: vivado.exe -log system_top.vds -product Vivado -mode batch -messageDb vivado.pb -notrace -source system_top.tcl
+	   # Log file: C:/[...]/MercuryZX5_PE1.runs/synth_1/system_top.vds
+	   # Journal file: C:/[...]/MercuryZX5_PE1.runs/synth_1/vivado.jou
+	   #-----------------------------------------------------------
+
+	"""
 	_VERSION:   ClassVar[Pattern] = re_compile(r"""# Vivado v(\d+\.\d(\.\d)?) \(64-bit\)""")
-	_STARTTIME: ClassVar[Pattern] = re_compile(r"""# Start of session at: (\w+ \w+ \d+ \d+:\d+:\d+ \d+)""")
+	_STARTTIME: ClassVar[Pattern] = re_compile(r"""# Start of session at: (\w+\s+\w+\s+\d+\s+\d+:\d+:\d+\s+\d+)""")
+
+	_toolVersion:   Nullable[YearReleaseVersion]  #: Used Vivado version.
+	_startDatetime: Nullable[datetime]            #: Session start timestamp.
 
 	def __init__(self, processor: "BaseProcessor") -> None:
+		"""
+		Initializes a Vivado preamble parser.
+
+		:param processor: Reference to the Vivado log processor.
+		"""
 		super().__init__(processor)
 
 		self._toolVersion =   None
 		self._startDatetime = None
 
 	@readonly
 	def ToolVersion(self) -> YearReleaseVersion:
+		"""
+		Read-only property to access the extracted Vivado tool version.
+
+		:returns: The used Vivado version as reported in the Vivado log messages.
+		"""
 		return self._toolVersion
 
 	@readonly
 	def StartDatetime(self) -> datetime:
+		"""
+		Read-only property to access the date and time when the Vivado session was started.
+
+		:returns: Datatime when the session was started.
+		"""
 		return self._startDatetime
 
 	def Generator(self, line: Line) -> Generator[Line, Line, Line]:
+		"""
+		A generator for processing the Vivado session preamble line-by-line.
+
+		:param line: First line to process.
+		:returns:    A generator processing log messages.
+		"""
 		if line.StartsWith("#----"):
 			line._kind = LineKind.SectionDelimiter
 		else:
-			line._kind |= LineKind.ProcessorError
+			line._kind |= LineKind.ProcessorError  # TODO: throw / return error
 
 		line = yield line
 
-		while True:
+		# a normal preamble has 11 lines including both delimiter lines.
+		for _ in range(15):
 			if (match := self._VERSION.match(line._message)) is not None:
 				self._toolVersion = YearReleaseVersion.Parse(match[1])
 				line._kind = LineKind.Normal
@@ -231,31 +280,68 @@ def Generator(self, line: Line) -> Generator[Line, Line, Line]:
 				line._kind = LineKind.Verbose
 
 			line = yield line
+		else:
+			line._kind |= LineKind.ProcessorError  # TODO: throw / return error
 
 		nextLine = yield line
 		return nextLine
 
 
 @export
 class Task(BaseParser, VivadoMessagesMixin, metaclass=ExtendedType, slots=True):
+	"""
+	A task's output emitted by a Vivado command.
+
+	.. rubric:: Extracted information
+
+	* Vivado messages (info, warning, critical warning, error).
+
+	.. rubric:: Example
+
+	.. code-block::
+
+	   Starting Cache Timing Information Task
+	   INFO: [Timing 38-35] 79-Done setting XDC timing constraints.
+	   Ending Cache Timing Information Task | Checksum: 19fe8cb97
+
+	   Time (s): cpu = 00:00:09 ; elapsed = 00:00:09 . Memory (MB): peak = 1370.594 ; gain = 493.266
+
+	"""
 	# _START:  ClassVar[str]
 	# _FINISH: ClassVar[str]
 	_TIME:   ClassVar[str] = "Time (s):"
 
-	_command:  "Command"
-	_duration: float
+	_command:  "Command"  #: Reference to the command (parent).
+	_duration: float      #: Duration of a task according to reported times by Vivado.
 
 	def __init__(self, command: "Command") -> None:
+		"""
+		Initializes a task (without child elements).
+
+		:param command: Reference to the command.
+		"""
 		super().__init__()
 		VivadoMessagesMixin.__init__(self)
 
 		self._command = command
 
 	@readonly
 	def Command(self) -> "Command":
+		"""
+		Read-only property to access the command.
+
+		:returns: The command this task's output was logged for.
+		"""
 		return self._command
 
 	def _TaskStart(self, line: Line) -> Generator[Line, Line, Line]:
+		"""
+		A generator for processing a task start (single line).
+
+		:param line:                First line to process (task start).
+		:returns:                   A generator processing log messages.
+		:raises ProcessorException: If first line doesn't conform to the *task start* pattern.
+		"""
 		if not line.StartsWith(self._START):
 			raise ProcessorException(f"{self.__class__.__name__}._TaskStart(): Expected '{self._START}' at line {line._lineNumber}.")
 
@@ -264,12 +350,19 @@ def _TaskStart(self, line: Line) -> Generator[Line, Line, Line]:
 		return nextLine
 
 	def _TaskFinish(self, line: Line) -> Generator[Line, Line, Line]:
+		"""
+		A generator for processing a task finish line-by-line.
+
+		:param line:                First line to process (task finish).
+		:returns:                   A generator processing log messages.
+		:raises ProcessorException: If finish line doesn't conform to the *task finish* pattern.
+		"""
 		if not line.StartsWith(self._FINISH):
 			raise ProcessorException(f"{self.__class__.__name__}._TaskFinish(): Expected '{self._FINISH}' at line {line._lineNumber}.")
 
 		line._kind = LineKind.TaskEnd
 		line = yield line
-		while self._TIME is not None:
+		while self._TIME is not None:       # TODO: limit search for time pattern to XX lines
 			if line.StartsWith(self._TIME):
 				line._kind = LineKind.TaskTime
 				break
@@ -280,6 +373,23 @@ def _TaskFinish(self, line: Line) -> Generator[Line, Line, Line]:
 		return line
 
 	def Generator(self, line: Line) -> Generator[Line, Line, Line]:
+		"""
+		A generator for processing a task without child elements line-by-line.
+
+		.. rubric:: Algorithm
+
+		1. Send first line to :meth:`_TaskStart`.
+		2. Process body lines
+
+		   * Collect Vivado messages (info, warning, critical warning, error).
+		   * Check for *task finish* pattern.
+		   * Check for *time* pattern.
+
+		3. Send last lines to :meth:`_TaskFinish`.
+
+		:param line:                First line to process.
+		:returns:                   A generator processing log messages.
+		"""
 		line = yield from self._TaskStart(line)
 
 		while True:
@@ -306,13 +416,32 @@ def __str__(self) -> str:
 
 @export
 class TaskWithSubTasks(Task):
+	"""
+	A task's output emitted by a Vivado command.
+
+	.. rubric:: Extracted information
+
+	* Vivado messages (info, warning, critical warning, error).
+	* Subtasks
+
+	.. rubric:: Example
+
+	.. code-block::
+
+	   Starting Cache Timing Information Task
+	   INFO: [Timing 38-35] 79-Done setting XDC timing constraints.
+	   Ending Cache Timing Information Task | Checksum: 19fe8cb97
+
+	   Time (s): cpu = 00:00:09 ; elapsed = 00:00:09 . Memory (MB): peak = 1370.594 ; gain = 493.266
+
+	"""
 	# _START:  ClassVar[str]
 	# _FINISH: ClassVar[str]
 	# _TIME:   ClassVar[str] = "Time (s):"
 
-	_PARSERS: ClassVar[Dict[YearReleaseVersion,Tuple[Type["SubTask"], ...]]] = dict()
+	_PARSERS:  ClassVar[Dict[YearReleaseVersion,Tuple[Type["SubTask"], ...]]] = dict()
 
-	_subtasks:   Dict[Type["SubTask"], "SubTask"]
+	_subtasks: Dict[Type["SubTask"], "SubTask"]
 
 	def __init__(self, command: "Command") -> None:
 		super().__init__(command)
diff --git a/pyEDAA/OutputFilter/Xilinx/PlaceDesign.py b/pyEDAA/OutputFilter/Xilinx/PlaceDesign.py
@@ -93,7 +93,7 @@ class Phase_PlacerInitialization(PhaseWithChildren):
 	"""
 	*Placer Initialization* phase.
 
-	.. topic:: Uses
+	.. rubric:: Uses
 
 	* :class:`SubPhase_PlacerInitializationNetlistSorting`
 	* :class:`SubPhase_IOPlacement_ClockPlacement_BuildPlacerDevice`
@@ -230,7 +230,7 @@ class Phase_GlobalPlacement(PhaseWithChildren):
 	"""
 	*Global Placement* phase.
 
-	.. topic:: Uses
+	.. rubric:: Uses
 
 	* :class:`SubPhase_Floorplanning`
 	* :class:`SubPhase_UpdateTimingBeforeSLRPathOpt`
@@ -411,7 +411,7 @@ class Phase_DetailPlacement(PhaseWithChildren):
 	"""
 	*Detail Placement* phase.
 
-	.. topic:: Uses
+	.. rubric:: Uses
 
 	* :class:`SubPhase_CommitMultiColumnMacros`
 	* :class:`SubPhase_CommitMostMacrosLUTRAMs`
@@ -539,7 +539,7 @@ class Phase_PostPlacementOptimizationAndCleanUp(PhaseWithChildren):
 	"""
 	*Post Placement Optimization and Clean-Up* phase.
 
-	.. topic:: Uses
+	.. rubric:: Uses
 
 	* :class:`SubPhase_PostCommitOptimization`
 	* :class:`SubPhase_PostPlacementCleanup`
@@ -566,7 +566,7 @@ class PlacerTask(TaskWithPhases):
 	"""
 	*Placer* task.
 
-	.. topic:: Uses
+	.. rubric:: Uses
 
 	* :class:`Phase_PlacerInitialization`
 	* :class:`Phase_GlobalPlacement`
diff --git a/pyEDAA/OutputFilter/Xilinx/RouteDesign.py b/pyEDAA/OutputFilter/Xilinx/RouteDesign.py
@@ -140,7 +140,7 @@ class SubPhase_UpdateTimingForBusSkew(SubPhaseWithChildren):
 	"""
 	*Update Timing for Bus Skew* subphase.
 
-	.. topic:: Uses
+	.. rubric:: Uses
 
 	* :class:`SubSubPhase_UpdateTiming`
 
@@ -160,7 +160,7 @@ class Phase_RouterInitialization(PhaseWithChildren):
 	"""
 	*Router Initialization* phase.
 
-	.. topic:: Uses
+	.. rubric:: Uses
 
 	* :class:`SubPhase_CreateTimer`
 	* :class:`SubPhase_FixTopologyConstraints`
@@ -216,7 +216,7 @@ class Phase_Initial_Routing(PhaseWithChildren):
 	"""
 	*Initial Routing* phase.
 
-	.. topic:: Uses
+	.. rubric:: Uses
 
 	* :class:`SubPhase_GlobalRouting`
 	* :class:`SubPhase_InitialNetRouting`
@@ -298,7 +298,7 @@ class Phase_RipUpAndReroute(PhaseWithChildren):
 	"""
 	*Rip-up And Reroute* phase.
 
-	.. topic:: Uses
+	.. rubric:: Uses
 
 	* :class:`SubPhase_GlobalIteration0`
 	* :class:`SubPhase_AdditionalIterationForHold`
@@ -336,7 +336,7 @@ class Phase_InitialRouting(PhaseWithChildren):
 	"""
 	*Initial Routing* phase.
 
-	.. topic:: Uses
+	.. rubric:: Uses
 
 	* :class:`SubPhase_InitialNetRoutingPass`
 	* :class:`SubPhase_GlobalRouting`
@@ -384,7 +384,7 @@ class Phase_DelayAndSkewOptimization(PhaseWithChildren):
 	"""
 	*Delay and Skew Optimization* phase.
 
-	.. topic:: Uses
+	.. rubric:: Uses
 
 	* :class:`SubPhase_DelayCleanUp`
 	* :class:`SubPhase_ClockSkewOptimization`
@@ -434,7 +434,7 @@ class Phase_DelayAndSkewOptimization(PhaseWithChildren):
 	"""
 	*Delay and Skew Optimization* phase.
 
-	.. topic:: Uses
+	.. rubric:: Uses
 
 	* :class:`SubPhase_DelayCleanUp`
 	* :class:`SubPhase_ClockSkewOptimization`
@@ -592,7 +592,7 @@ class RoutingTask(TaskWithPhases):
 	"""
 	*Routing* task.
 
-	.. topic:: Uses
+	.. rubric:: Uses
 
 	* :class:`Phase_BuildRTDesign`
 	* :class:`Phase_RouterInitialization`
diff --git a/pyEDAA/OutputFilter/Xilinx/SynthesizeDesign.py b/pyEDAA/OutputFilter/Xilinx/SynthesizeDesign.py
@@ -664,7 +664,7 @@ def _BlackboxesGenerator(self, line: Line) -> Generator[Line, Line, Line]:
 		:param line: First line to process.
 		:returns:    A generator to process multiple lines containing a table of blackboxes.
 
-		.. topic:: Example
+		.. rubric:: Example
 
 		.. code-block::
 
@@ -718,7 +718,7 @@ def _CellGenerator(self, line: Line) -> Generator[Line, Line, Line]:
 		:param line: First line to process.
 		:returns:    A generator to process multiple lines containing a table of cell statistics.
 
-		.. topic:: Example
+		.. rubric:: Example
 
 		.. code-block::
 
diff --git a/pyEDAA/OutputFilter/Xilinx/__init__.py b/pyEDAA/OutputFilter/Xilinx/__init__.py
