Merge branch 'doxygen-pep' into 'develop'

Doxygen and some PEP formatting

See merge request PUM_TDDD96/B-ASIC!3

b_asic/__init__.py

@@ -11,4 +11,4 @@ from b_asic.port import *
 from b_asic.schema import *
 from b_asic.signal_flow_graph import *
 from b_asic.signal import *
-from b_asic.simulation import *
+from b_asic.simulation import *
\ No newline at end of file

b_asic/basic_operation.py

-"""
+"""@package docstring
 B-ASIC Basic Operation Module.
 TODO: More info.
 """
 
+from abc import abstractmethod
+from typing import List, Dict, Optional, Any
+from numbers import Number
+
 from b_asic.port import InputPort, OutputPort
 from b_asic.signal import SignalSource, SignalDestination
 from b_asic.operation import Operation
 from b_asic.simulation import SimulationState, OperationState
-from abc import ABC, abstractmethod
-from typing import List, Dict, Optional, Any
-from numbers import Number
 
 
 class BasicOperation(Operation):
-	"""
-	Generic abstract operation class which most implementations will derive from.
+	"""Generic abstract operation class which most implementations will derive from.
 	TODO: More info.
 	"""
 
@@ -23,18 +23,14 @@ class BasicOperation(Operation):
 	_parameters: Dict[str, Optional[Any]]
 
 	def __init__(self):
-		"""
-		Construct a BasicOperation.
-		"""
+		"""Construct a BasicOperation."""
 		self._input_ports = []
 		self._output_ports = []
 		self._parameters = {}
 
 	@abstractmethod
 	def evaluate(self, inputs: list) -> list:
-		"""
-		Evaluate the operation and generate a list of output values given a list of input values.
-		"""
+		"""Evaluate the operation and generate a list of output values given a list of input values."""
 		pass
 
 	def inputs(self) -> List[InputPort]:

b_asic/core_operations.py

-"""
+"""@package docstring
 B-ASIC Core Operations Module.
 TODO: More info.
 """
 
+from numbers import Number
+
 from b_asic.port import InputPort, OutputPort
 from b_asic.operation import Operation
 from b_asic.basic_operation import BasicOperation
 from b_asic.graph_id import GraphIDType
-from numbers import Number
 
 
 class Input(Operation):
-	"""
-	Input operation.
+	"""Input operation.
 	TODO: More info.
 	"""
 
@@ -21,15 +21,12 @@ class Input(Operation):
 
 
 class Constant(BasicOperation):
-	"""
-	Constant value operation.
+	"""Constant value operation.
 	TODO: More info.
 	"""
 
 	def __init__(self, value: Number):
-		"""
-		Construct a Constant.
-		"""
+		"""Construct a Constant."""
 		super().__init__()
 		self._output_ports = [OutputPort(1)] # TODO: Generate appropriate ID for ports.
 		self._parameters["value"] = value
@@ -37,19 +34,16 @@ class Constant(BasicOperation):
 	def evaluate(self, inputs: list) -> list:
 		return [self.param("value")]
 
-	def get_op_name(self) -> GraphIDType:
+	def type_name(self) -> GraphIDType:
 		return "const"
 
 class Addition(BasicOperation):
-	"""
-	Binary addition operation.
+	"""Binary addition operation.
 	TODO: More info.
 	"""
 
 	def __init__(self):
-		"""
-		Construct an Addition.
-		"""
+		"""Construct an Addition."""
 		super().__init__()
 		self._input_ports = [InputPort(1), InputPort(1)] # TODO: Generate appropriate ID for ports.
 		self._output_ports = [OutputPort(1)] # TODO: Generate appropriate ID for ports.
@@ -57,20 +51,17 @@ class Addition(BasicOperation):
 	def evaluate(self, inputs: list) -> list:
 		return [inputs[0] + inputs[1]]
 
-	def get_op_name(self) -> GraphIDType:
+	def type_name(self) -> GraphIDType:
 		return "add"
 
 
 class ConstantMultiplication(BasicOperation):
-	"""
-	Unary constant multiplication operation.
+	"""Unary constant multiplication operation.
 	TODO: More info.
 	"""
 
 	def __init__(self, coefficient: Number):
-		"""
-		Construct a ConstantMultiplication.
-		"""
+		"""Construct a ConstantMultiplication."""
 		super().__init__()
 		self._input_ports = [InputPort(1)] # TODO: Generate appropriate ID for ports.
 		self._output_ports = [OutputPort(1)] # TODO: Generate appropriate ID for ports.
@@ -79,7 +70,7 @@ class ConstantMultiplication(BasicOperation):
 	def evaluate(self, inputs: list) -> list:
 		return [inputs[0] * self.param("coefficient")]
 
-	def get_op_name(self) -> GraphIDType:
+	def type_name(self) -> GraphIDType:
 		return "const_mul"
 
 # TODO: More operations.

b_asic/graph_id.py

-"""
+"""@package docstring
 B-ASIC Graph ID module for handling IDs of different objects in a graph.
 TODO: More info
 """
 
 from collections import defaultdict
-from typing import NewType, Union, DefaultDict
+from typing import NewType, DefaultDict
 
 GraphID = NewType("GraphID", str)
 GraphIDType = NewType("GraphIDType", str)
 GraphIDNumber = NewType("GraphIDNumber", int)
 
+
 class GraphIDGenerator:
-    """
-    A class that generates Graph IDs for objects.
-    """
+    """A class that generates Graph IDs for objects."""
 
     _next_id_number: DefaultDict[GraphIDType, GraphIDNumber]
 
@@ -21,10 +20,7 @@ class GraphIDGenerator:
         self._next_id_number = defaultdict(lambda: 1)       # Initalises every key element to 1
 
     def get_next_id(self, graph_id_type: GraphIDType) -> GraphID:
-        """
-        Returns the next graph id for a certain graph id type.
-        """
+        """Returns the next graph id for a certain graph id type."""
         graph_id = graph_id_type + str(self._next_id_number[graph_id_type])
         self._next_id_number[graph_id_type] += 1            # Increase the current id number
         return graph_id
-

b_asic/operation.py

-"""
+"""@package docstring
 B-ASIC Operation Module.
 TODO: More info.
 """
 
 from abc import ABC, abstractmethod
 from numbers import Number
-from typing import NewType, List, Dict, Optional, Any, TYPE_CHECKING
+from typing import List, Dict, Optional, Any, TYPE_CHECKING
 
 if TYPE_CHECKING:
 	from b_asic.port import InputPort, OutputPort
 	from b_asic.simulation import SimulationState
 	from b_asic.graph_id import GraphIDType
 
+
 class Operation(ABC):
-	"""
-	Operation interface.
+	"""Operation interface.
 	TODO: More info.
 	"""
 
 	@abstractmethod
 	def inputs(self) -> "List[InputPort]":
-		"""
-		Get a list of all input ports.
-		"""
+		"""Get a list of all input ports."""
 		pass
 
 	@abstractmethod
 	def outputs(self) -> "List[OutputPort]":
-		"""
-		Get a list of all output ports.
-		"""
+		"""Get a list of all output ports."""
 		pass
 
 	@abstractmethod
 	def input_count(self) -> int:
-		"""
-		Get the number of input ports.
-		"""
+		"""Get the number of input ports."""
 		pass
 
 	@abstractmethod
 	def output_count(self) -> int:
-		"""
-		Get the number of output ports.
-		"""
+		"""Get the number of output ports."""
 		pass
 
 	@abstractmethod
 	def input(self, i: int) -> "InputPort":
-		"""
-		Get the input port at index i.
-		"""
+		"""Get the input port at index i."""
 		pass
 
 	@abstractmethod
 	def output(self, i: int) -> "OutputPort":
-		"""
-		Get the output port at index i.
-		"""
+		"""Get the output port at index i."""
 		pass
 
 	@abstractmethod
 	def params(self) -> Dict[str, Optional[Any]]:
-		"""
-		Get a dictionary of all parameter values.
-		"""
+		"""Get a dictionary of all parameter values."""
 		pass
 
 	@abstractmethod
 	def param(self, name: str) -> Optional[Any]:
-		"""
-		Get the value of a parameter.
+		"""Get the value of a parameter.
 		Returns None if the parameter is not defined.
 		"""
 		pass
 
 	@abstractmethod
 	def set_param(self, name: str, value: Any) -> None:
-		"""
-		Set the value of a parameter.
+		"""Set the value of a parameter.
 		The parameter must be defined.
 		"""
 		pass
 
 	@abstractmethod
 	def evaluate_outputs(self, state: "SimulationState") -> List[Number]:
-		"""
-		Simulate the circuit until its iteration count matches that of the simulation state,
+		"""Simulate the circuit until its iteration count matches that of the simulation state,
 		then return the resulting output vector.
 		"""
 		pass
 
 	@abstractmethod
 	def split(self) -> "List[Operation]":
-		"""
-		Split the operation into multiple operations.
+		"""Split the operation into multiple operations.
 		If splitting is not possible, this may return a list containing only the operation itself.
 		"""
 		pass
 
 	@abstractmethod
-	def get_op_name(self) -> "GraphIDType":
+	def type_name(self) -> "GraphIDType":
 		"""Returns a string representing the operation name of the operation."""
 		pass
 
 	@abstractmethod
 	def neighbours(self) -> "List[Operation]":
-		"""
-		Return all operations that are connected by signals to this operation.
+		"""Return all operations that are connected by signals to this operation.
 		If no neighbours are found this returns an empty list
 		"""
 
 	# TODO: More stuff.
-

b_asic/port.py

-"""
+"""@package docstring
 B-ASIC Port Module.
 TODO: More info.
 """
 
-from b_asic.signal import Signal
 from abc import ABC, abstractmethod
-from typing import NewType, Optional, List, Dict
+from typing import NewType, Optional, List
+
+from b_asic.signal import Signal
 
 PortId = NewType("PortId", int)
 
 
 class Port(ABC):
-	"""
-	Abstract port class.
+	"""Abstract port class.
 	TODO: More info.
 	"""
 
 	_identifier: PortId
 
 	def __init__(self, identifier: PortId):
-		"""
-		Construct a Port.
-		"""
+		"""Construct a Port."""
 		self._identifier = identifier
 
 	def identifier(self) -> PortId:
-		"""
-		Get the unique identifier.
-		"""
+		"""Get the unique identifier."""
 		return self._identifier
 
 	@abstractmethod
 	def signals(self) -> List[Signal]:
-		"""
-		Get a list of all connected signals.
-		"""
+		"""Get a list of all connected signals."""
 		pass
 
 	@abstractmethod
 	def signal_count(self) -> int:
-		"""
-		Get the number of connected signals.
-		"""
+		"""Get the number of connected signals."""
 		pass
 
 	@abstractmethod
 	def signal(self, i: int = 0) -> Signal:
-		"""
-		Get the connected signal at index i.
-		"""
+		"""Get the connected signal at index i."""
 		pass
 
 	@abstractmethod
 	def connect(self, signal: Signal) -> None:
-		"""
-		Connect a signal.
-		"""
+		"""Connect a signal."""
 		pass
 
 	@abstractmethod
 	def disconnect(self, i: int = 0) -> None:
-		"""
-		Disconnect a signal.
-		"""
+		"""Disconnect a signal."""
 		pass
 
 	# TODO: More stuff.
 
 
 class InputPort(Port):
-	"""
-	Input port.
+	"""Input port.
 	TODO: More info.
 	"""
 	_source_signal: Optional[Signal]
 
 	def __init__(self, identifier: PortId):
-		"""
-		Construct an InputPort.
-		"""
 		super().__init__(identifier)
 		self._source_signal = None
 
 	def signals(self) -> List[Signal]:
-		return [] if self._source_signal == None else [self._source_signal]
+		return [] if self._source_signal is None else [self._source_signal]
 
 	def signal_count(self) -> int:
-		return 0 if self._source_signal == None else 1
+		return 0 if self._source_signal is None else 1
 
 	def signal(self, i: int = 0) -> Signal:
-		assert i >= 0 and i < self.signal_count() # TODO: Error message.
-		assert self._source_signal != None # TODO: Error message.
+		assert 0 <= i < self.signal_count() # TODO: Error message.
+		assert self._source_signal is not None # TODO: Error message.
 		return self._source_signal
 
 	def connect(self, signal: Signal) -> None:
 		self._source_signal = signal
 
 	def disconnect(self, i: int = 0) -> None:
-		assert i >= 0 and i < self.signal_count() # TODO: Error message.
+		assert 0 <= i < self.signal_count() # TODO: Error message.
 		self._source_signal = None
 
 	# TODO: More stuff.
 
 
 class OutputPort(Port):
-	"""
-	Output port.
+	"""Output port.
 	TODO: More info.
 	"""
 
 	_destination_signals: List[Signal]
 
 	def __init__(self, identifier: PortId):
-		"""
-		Construct an OutputPort.
-		"""
 		super().__init__(identifier)
 		self._destination_signals = []
 
@@ -125,7 +103,7 @@ class OutputPort(Port):
 		return len(self._destination_signals)
 
 	def signal(self, i: int = 0) -> Signal:
-		assert i >= 0 and i < self.signal_count() # TODO: Error message.
+		assert 0 <= i < self.signal_count() # TODO: Error message.
 		return self._destination_signals[i]
 
 	def connect(self, signal: Signal) -> None:
@@ -133,7 +111,7 @@ class OutputPort(Port):
 		self._destination_signals.append(signal)
 
 	def disconnect(self, i: int = 0) -> None:
-		assert i >= 0 and i < self.signal_count() # TODO: Error message.
+		assert 0 <= i < self.signal_count() # TODO: Error message.
 		del self._destination_signals[i]
 
 	# TODO: More stuff.

b_asic/precedence_chart.py

-"""
+"""@package docstring
 B-ASIC Precedence Chart Module.
 TODO: More info.
 """
@@ -7,8 +7,7 @@ from b_asic.signal_flow_graph import SFG
 
 
 class PrecedenceChart:
-	"""
-	Precedence chart constructed from a signal flow graph.
+	"""Precedence chart constructed from a signal flow graph.
 	TODO: More info.
 	"""
 
@@ -16,9 +15,6 @@ class PrecedenceChart:
 	# TODO: More members.
 
 	def __init__(self, sfg: SFG):
-		"""
-		Construct a PrecedenceChart.
-		"""
 		self.sfg = sfg
 		# TODO: Implement.
 

b_asic/schema.py

-"""
+"""@package docstring
 B-ASIC Schema Module.
 TODO: More info.
 """
@@ -7,8 +7,7 @@ from b_asic.precedence_chart import PrecedenceChart
 
 
 class Schema:
-	"""
-	Schema constructed from a precedence chart.
+	"""Schema constructed from a precedence chart.
 	TODO: More info.
 	"""
 
@@ -16,9 +15,6 @@ class Schema:
 	# TODO: More members.
 
 	def __init__(self, pc: PrecedenceChart):
-		"""
-		Construct a Schema.
-		"""
 		self.pc = pc
 		# TODO: Implement.
 

b_asic/signal.py

-"""
+"""@package docstring
 B-ASIC Signal Module.
 TODO: More info.
 """
 
 from b_asic.operation import Operation
-from typing import NewType
+
 
 class SignalSource:
-	"""
-	Handle to a signal source.
+	"""Handle to a signal source.
 	TODO: More info.
 	"""
 	operation: Operation
 	port_index: int
 
 	def __init__(self, operation: Operation, port_index: int):
-		"""
-		Construct a SignalSource.
-		"""
 		self.operation = operation
 		self.port_index = port_index
 
@@ -25,17 +21,13 @@ class SignalSource:
 
 
 class SignalDestination:
-	"""
-	Handle to a signal destination.
+	"""Handle to a signal destination.
 	TODO: More info.
 	"""
 	operation: Operation
 	port_index: int
 
 	def __init__(self, operation: Operation, port_index: int):
-		"""
-		Construct a SignalDestination.
-		"""
 		self.operation = operation
 		self.port_index = port_index
 
@@ -43,17 +35,13 @@ class SignalDestination:
 
 
 class Signal:
-	"""
-	A connection between two operations consisting of a source and destination handle.
+	"""A connection between two operations consisting of a source and destination handle.
 	TODO: More info.
 	"""
 	source: SignalSource
 	destination: SignalDestination
 
 	def __init__(self, source: SignalSource, destination: SignalDestination):
-		"""
-		Construct a Signal.
-		"""
 		self.source = source
 		self.destination = destination
 

b_asic/signal_flow_graph.py

-"""
+"""@package docstring
 B-ASIC Signal Flow Graph Module.
 TODO: More info.
 """
 
+from typing import List, Dict, Union, Optional
+
 from b_asic.operation import Operation
 from b_asic.basic_operation import BasicOperation
 from b_asic.signal import Signal, SignalSource, SignalDestination
-from b_asic.simulation import SimulationState, OperationState
 from b_asic.graph_id import GraphIDGenerator, GraphID
 
-from typing import List, Dict, Union, Optional
 
 class SFG(BasicOperation):
-	"""
-	Signal flow graph.
+	"""Signal flow graph.
 	TODO: More info.
 	"""
 
@@ -21,12 +20,11 @@ class SFG(BasicOperation):
 	_graph_id_generator: GraphIDGenerator
 
 	def __init__(self, input_destinations: List[SignalDestination], output_sources: List[SignalSource]):
-		"""Constructs an SFG."""
 		super().__init__()
 		# TODO: Allocate input/output ports with appropriate IDs.
-		
+
 		self._graph_objects_by_id = dict # Map Operation ID to Operation objects
-		self._graph_id_generator = GraphIDGenerator() 
+		self._graph_id_generator = GraphIDGenerator()
 
 		# TODO: Traverse the graph between the inputs/outputs and add to self._operations.
 		# TODO: Connect ports with signals with appropriate IDs.
@@ -37,23 +35,21 @@ class SFG(BasicOperation):
 	def add_operation(self, operation: Operation) -> GraphID:
 		"""Adds the entered operation to the SFG's dictionary of graph objects and
 	 	returns a generated GraphID for it.
-		
+
 		Keyword arguments:
 		operation: Operation to add to the graph.
 		"""
-		return self._add_graph_obj(operation, operation.get_op_name())
-
+		return self._add_graph_obj(operation, operation.type_name())
 
 	def add_signal(self, signal: Signal) -> GraphID:
 		"""Adds the entered signal to the SFG's dictionary of graph objects and returns
 		a generated GraphID for it.
-		
+
 		Keyword argumentst:
 		signal: Signal to add to the graph.
 		"""
 		return self._add_graph_obj(signal, 'sig')
 
-
 	def find_by_id(self, graph_id: GraphID) -> Optional[Operation]:
 		"""Finds a graph object based on the entered Graph ID and returns it. If no graph
 		object with the entered ID was found then returns None.
@@ -63,14 +59,11 @@ class SFG(BasicOperation):
 		"""
 		if graph_id in self._graph_objects_by_id:
 			return self._graph_objects_by_id[graph_id]
-		else:
-			return None
-			
 
+		return None
 
 	def _add_graph_obj(self, obj: Union[Operation, Signal], operation_id_type: str):
 		graph_id = self._graph_id_generator.get_next_id(operation_id_type)
 		self._graph_objects_by_id[graph_id] = obj
-		return graph_id 
-
+		return graph_id
 

b_asic/simulation.py

-"""
+"""@package docstring
 B-ASIC Simulation Module.
 TODO: More info.
 """
 
 from numbers import Number
-from typing import List, Dict
+from typing import List
 
 
 class OperationState:
-	"""
-	Simulation state of an operation.
+	"""Simulation state of an operation.
 	TODO: More info.
 	"""
 
@@ -17,16 +16,12 @@ class OperationState:
 	iteration: int
 
 	def __init__(self):
-		"""
-		Construct an OperationState.
-		"""
 		self.output_values = []
 		self.iteration = 0
 
 
 class SimulationState:
-	"""
-	Simulation state.
+	"""Simulation state.
 	TODO: More info.
 	"""
 
@@ -34,9 +29,6 @@ class SimulationState:
 	iteration: int
 
 	def __init__(self):
-		"""
-		Construct a SimulationState.
-		"""
 		self.operation_states = {}
 		self.iteration = 0
 

b_asic/traverse_tree.py

-"""
+"""@package docstring
 B-ASIC Operation Tree Traversing Module.
-TODO:
-    - Get a first operation or? an entire operation tree
-    - For each start point, follow it to the next operation from it's out port.
-    - If we are searching for a specific operation end.
-    - If we are searching for a specific type of operation add the operation to a list and continue.
-    - When we no more out ports can be traversed return results and end.
 """
 
 from typing import List, Optional
@@ -15,12 +9,7 @@ from b_asic.operation import Operation
 
 
 class Traverse:
-    """Traverse operation tree.
-    TODO:
-        - More info.
-        - Check if a datastructure other than list suits better as return value.
-        - Implement the type check for operation.
-    """
+    """Traverse operation tree."""
 
     def __init__(self, operation: Operation):
         """Construct a TraverseTree."""