From 71f1c87b05f93ecde4c830767fcda50e1028ac21 Mon Sep 17 00:00:00 2001
From: Jacob Wahlman <jacwa448@student.liu.se>
Date: Tue, 3 Mar 2020 11:33:03 +0100
Subject: [PATCH] doxygen docstrings and some pep stuff
---
b_asic/__init__.py | 2 +-
b_asic/basic_operation.py | 20 +++++-------
b_asic/core_operations.py | 35 ++++++++------------
b_asic/graph_id.py | 14 +++-----
b_asic/operation.py | 54 ++++++++++---------------------
b_asic/port.py | 64 ++++++++++++-------------------------
b_asic/precedence_chart.py | 8 ++---
b_asic/schema.py | 8 ++---
b_asic/signal.py | 22 +++----------
b_asic/signal_flow_graph.py | 29 +++++++----------
b_asic/simulation.py | 16 +++-------
b_asic/traverse_tree.py | 15 ++-------
12 files changed, 91 insertions(+), 196 deletions(-)
diff --git a/b_asic/__init__.py b/b_asic/__init__.py
index 8a84a945..752bac07 100644
--- a/b_asic/__init__.py
+++ b/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 *
\ No newline at end of file
+from b_asic.simulation import *
diff --git a/b_asic/basic_operation.py b/b_asic/basic_operation.py
index 4f7b426b..54aaaebe 100644
--- a/b_asic/basic_operation.py
+++ b/b_asic/basic_operation.py
@@ -1,20 +1,20 @@
-"""
+"""@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]:
diff --git a/b_asic/core_operations.py b/b_asic/core_operations.py
index bca344cf..513fe7cf 100644
--- a/b_asic/core_operations.py
+++ b/b_asic/core_operations.py
@@ -1,18 +1,18 @@
-"""
+"""@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.
diff --git a/b_asic/graph_id.py b/b_asic/graph_id.py
index 3f25f513..0fd1855b 100644
--- a/b_asic/graph_id.py
+++ b/b_asic/graph_id.py
@@ -1,19 +1,18 @@
-"""
+"""@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
-
diff --git a/b_asic/operation.py b/b_asic/operation.py
index f02cd700..923690aa 100644
--- a/b_asic/operation.py
+++ b/b_asic/operation.py
@@ -1,115 +1,95 @@
-"""
+"""@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.
-
diff --git a/b_asic/port.py b/b_asic/port.py
index 2d5405ed..f67defb7 100644
--- a/b_asic/port.py
+++ b/b_asic/port.py
@@ -1,120 +1,98 @@
-"""
+"""@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.
diff --git a/b_asic/precedence_chart.py b/b_asic/precedence_chart.py
index 329c78d2..93b86164 100644
--- a/b_asic/precedence_chart.py
+++ b/b_asic/precedence_chart.py
@@ -1,4 +1,4 @@
-"""
+"""@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.
diff --git a/b_asic/schema.py b/b_asic/schema.py
index 56eb47ff..41938263 100644
--- a/b_asic/schema.py
+++ b/b_asic/schema.py
@@ -1,4 +1,4 @@
-"""
+"""@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.
diff --git a/b_asic/signal.py b/b_asic/signal.py
index 6ef55c8d..7e63ebfb 100644
--- a/b_asic/signal.py
+++ b/b_asic/signal.py
@@ -1,23 +1,19 @@
-"""
+"""@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
diff --git a/b_asic/signal_flow_graph.py b/b_asic/signal_flow_graph.py
index 9d31b04b..914cf390 100644
--- a/b_asic/signal_flow_graph.py
+++ b/b_asic/signal_flow_graph.py
@@ -1,19 +1,18 @@
-"""
+"""@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
diff --git a/b_asic/simulation.py b/b_asic/simulation.py
index d3d3aaf6..c4f7f8f3 100644
--- a/b_asic/simulation.py
+++ b/b_asic/simulation.py
@@ -1,15 +1,14 @@
-"""
+"""@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
diff --git a/b_asic/traverse_tree.py b/b_asic/traverse_tree.py
index 024a542d..dc00371e 100644
--- a/b_asic/traverse_tree.py
+++ b/b_asic/traverse_tree.py
@@ -1,11 +1,5 @@
-"""
+"""@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."""
--
GitLab