Merge branch 'docfixes' into 'main'

Documentation conversion and pre-commit updates

Closes #28

See merge request !4

.gitlab-ci.yml

@@ -57,6 +57,10 @@ run-test-3.11:
   image: python:3.11
   extends: ".run-test"
 
+run-test-3.12:
+  image: python:3.12
+  extends: ".run-test"
+
 run-doc-test:
   image: python:3.10
   stage: test

.pre-commit-config.yaml

 repos:
-
-  - repo: https://github.com/charliermarsh/ruff-pre-commit
+  - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
-    rev: v0.0.272
+    rev: v0.4.7
     hooks:
+      # Run the linter.
       - id: ruff
         args: [ --fix, --exit-non-zero-on-fix ]
+      # Run the formatter.
+      # - id: ruff-format
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v4.6.0
     hooks:
       - id: mixed-line-ending
         exclude_types: [svg]
@@ -23,13 +25,13 @@ repos:
       - id: check-case-conflict
 
   - repo: https://github.com/pycqa/isort
-    rev: 5.12.0
+    rev: 5.13.2
     hooks:
       - id: isort
         name: isort (python)
 
   - repo: https://github.com/asottile/pyupgrade
-    rev: v3.6.0
+    rev: v3.15.2
     hooks:
       - id: pyupgrade
         args: [--py310-plus]

mia_uppg3.txt

@@ -245,16 +245,16 @@ f2: 0000
 f3: 0000
 f4: 0000
 f5: 0000
-f6: 0004 
-f7: cac0 
-f8: bbbb 
-f9: 0003 
-fa: 0200 
-fb: 6969 
-fc: abba 
-fd: ffff 
-fe: 1337 
-ff: 0001 
+f6: 0004
+f7: cac0
+f8: bbbb
+f9: 0003
+fa: 0200
+fb: 6969
+fc: abba
+fd: ffff
+fe: 1337
+ff: 0001
 
 uM:
 00: 00f8000
@@ -409,4 +409,3 @@ K2:
 01: 04
 02: 05
 03: 07
-

pyproject.toml

@@ -11,6 +11,7 @@ classifiers = [
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
 ]
 maintainers = [{ name = "Oscar Gustafsson", email = "oscar.gustafsson@liu.se" }]
 dependencies = ["qtpy"]

src/simudator/core/modules/memory.py

@@ -9,15 +9,17 @@ class Memory(Module):
     A general size memory module.
     """
 
-    def __init__(self,
-                 input_signal: Signal,
-                 output_signal: Signal,
-                 control_signal : Signal,
-                 adress_signal: Signal,
-                 size: int,
-                 value_padding: int = 2,
-                 adress_padding: int = 2,
-                 name="Memory") -> None:
+    def __init__(
+        self,
+        input_signal: Signal,
+        output_signal: Signal,
+        control_signal: Signal,
+        adress_signal: Signal,
+        size: int,
+        value_padding: int = 2,
+        adress_padding: int = 2,
+        name="Memory",
+    ) -> None:
         super().__init__(name)
 
         # Input signals
@@ -52,13 +54,14 @@ class Memory(Module):
         # in case the memory was written to in update_register()
 
     def update_logic(self) -> None:
-        if self.adress_s.get_value() is not None and \
-                self.control_s.get_value() is not None:
+        if (
+            self.adress_s.get_value() is not None
+            and self.control_s.get_value() is not None
+        ):
             self.is_write = self.control_s.get_value()
             self.current_adress = self.adress_s.get_value()
             self.output_s.update_value(self.memory[self.current_adress])
 
-
     def get_input_signal(self) -> Signal:
         return self.input_s
 

src/simudator/processor/mia/modules/alu.py

@@ -5,6 +5,7 @@ from simudator.core.signal import Signal
 class ALU(Module):
     """
     Module used for arithmetic logic calculations.
+
     Takes two input signals that are used to recive values
     for calculations.
     Takes one control signal to control what operand should
@@ -195,7 +196,7 @@ class ALU(Module):
 
     def ones_complement(self, number: int) -> int:
         """
-        Returns the ones complement of a int
+        Returns the ones complement of an int.
         """
         binary_number = self.int_to_bin(number)
         binary_complement = self.bitwise_not(binary_number)
@@ -205,6 +206,7 @@ class ALU(Module):
     def add_numbers(self, number_a: int, number_b: int, change_flags: bool) -> int:
         """
         Sum two numbers as binary numbers.
+
         Will update flags if asked to
         """
 
@@ -226,6 +228,7 @@ class ALU(Module):
     def subtract_numbers(self, number_a: int, number_b: int, change_flags: bool) -> int:
         """
         Calculates difference between to two numbers as binary numbers.
+
         Will update flags if asked to.
         """
 
@@ -248,6 +251,7 @@ class ALU(Module):
     def and_numbers(self, number_a: int, number_b: int) -> int:
         """
         Bitwise and two int's and return the result.
+
         Will update flags.
         """
 
@@ -269,6 +273,7 @@ class ALU(Module):
     def or_numbers(self, number_a: int, number_b: int) -> int:
         """
         Bitwise or two int's and return the result.
+
         Will update flags.
         """
         # Convert to binary
@@ -288,7 +293,8 @@ class ALU(Module):
 
     def logical_left_shift(self, number: int, hr_value: int = None) -> int:
         """
-        Left shifts given number as a binary with word
+        Left shifts given number as a binary with word.
+
         Fills right with 0's after shift.
         Will update carry with removed bit.
         """
@@ -334,7 +340,8 @@ class ALU(Module):
 
     def logical_right_shift(self, number: int) -> int:
         """
-        Left shifts given number as a binary
+        Left shifts given number as a binary.
+
         Fills right with 0's after shift.
         Will update carry with removed bit.
         """
@@ -354,8 +361,8 @@ class ALU(Module):
 
     def arithmetic_right_shift(self, number: int, hr_value: int = None) -> int:
         """
-        Right shifts given number as a binary with
-        word length WORD_LENGTH.
+        Right shifts given number as a binary with word length WORD_LENGTH.
+
         Fills right with most significant bit.
         Will update carry with removed bit.
         """
@@ -401,8 +408,8 @@ class ALU(Module):
 
     def left_rotate(self, number: int, hr_value: int = None) -> int:
         """
-        Rotates given number left as a binary with
-        word length WORD_LENGTH.
+        Rotates given number left as a binary with word length WORD_LENGTH.
+
         Fills right with 0's after shift.
         """
 
@@ -448,7 +455,8 @@ class ALU(Module):
 
     def bin_to_int(self, binary_number: [int], word_length: int = None) -> int:
         """
-        Converts from binary list representation to int
+        Converts from binary list representation to int.
+
         """
 
         # Set default word length if none is specified
@@ -467,6 +475,7 @@ class ALU(Module):
         """
         Converts an int to a list binary representation where
         each index in the list represents one bit of the word.
+
         This is done to more easily handle edge cases that occur
         when doing arithmetic with fixed word lenghts.
         This version can not handel negative numbers.
@@ -491,7 +500,7 @@ class ALU(Module):
 
     def int_to_negative_bin(self, number: int) -> [int]:
         """
-        Returns the negative of a given int as a binary list
+        Returns the negative of a given int as a binary list.
         """
 
         binary_number = self.int_to_bin(number)
@@ -505,6 +514,7 @@ class ALU(Module):
         """
         Converts an int to a list binary representation where
         each index in the list represents one bit of the word.
+
         This is done to more easily handle edge cases that occur
         when doing arithmetic with fixed word lenghts.
         """
@@ -533,7 +543,7 @@ class ALU(Module):
 
     def bin_to_int_twocomp(self, binary_number: [int]) -> int:
         """
-        Converts from two's complement binary list representation to int
+        Converts from two's complement binary list representation to int.
         """
         number = 0
 

src/simudator/processor/mia/modules/lc.py

@@ -7,8 +7,7 @@ from simudator.core.signal import Signal
 
 
 class LC(Module):
-    """
-    A class representing the loop counter. It is controlled by the
+    """A class representing the loop counter. It is controlled by the
     signal uM_control which determines if it should read from bus,
     increase by one or read from mM_uADR.
     """
@@ -24,35 +23,31 @@ class LC(Module):
         bit_length=8,
     ) -> None:
         """
-        :param mM_control: A signal connection from the micro memory
-        to the loop counter. This allows the micro memory to send bit
-        12 and 13 to the loop counter. Bit 12 and 13 decides the
-        loop counters behaviour.
-        :type mM_control: Signal
-
-        :param bus_input: A signal connection from the bus to the loop
-        counter. The loop counter reads from this signal when it reads
-        from the bus.
-        :type bus_input: Signal
-
-        :param l_flag: A signal connection from the loop counter to the
-        L flag. The loop counter writes to this signal when it needs to
-        update the L flag.
-        :type l_flag: Signal
-
-        :param mM_uADR: A signal connection from the micro memory to
-        the loop counter. This allows the loop counter to read the 7
-        least significant bits from the uADR field.
-        :type mM_uADR: Signal
-
-        :param name: Optional name of the loop counter.
-        :type name: str
-
-        :param value: Optional start value of the loop counter.
-        :type value: int
-
-        :param bit_length: Optional bit length of the loop counter.
-        :type bit_length: int
+        Parameters
+        ----------
+        mM_control : Signal
+            A signal connection from the micro memory
+            to the loop counter. This allows the micro memory to send bit
+            12 and 13 to the loop counter. Bit 12 and 13 decides the
+            loop counters behaviour.
+        bus_input : Signal
+            A signal connection from the bus to the loop
+            counter. The loop counter reads from this signal when it reads
+            from the bus.
+        l_flag : Signal
+            A signal connection from the loop counter to the
+            L flag. The loop counter writes to this signal when it needs to
+            update the L flag.
+        mM_uADR : Signal
+            A signal connection from the micro memory to
+            the loop counter. This allows the loop counter to read the 7
+            least significant bits from the uADR field.
+        name : str
+            Optional name of the loop counter.
+        value : int
+            Optional start value of the loop counter.
+        bit_length : int
+            Optional bit length of the loop counter.
         """
 
         # init the name
@@ -82,8 +77,7 @@ class LC(Module):
         self.mM_uADR_s.add_destination(self)
 
     def update_register(self) -> None:
-        """
-        Reads bit 12 and 13 from the micro memory and updates the
+        """Reads bit 12 and 13 from the micro memory and updates the
         loop counter.
         0 - does nothing.
         1 - decrements the loop counter by one.
@@ -128,15 +122,13 @@ class LC(Module):
                 self.value = self.mask
 
     def output_register(self) -> None:
-        """
-        The loop counter will only output to the L flag, this is
+        """The loop counter will only output to the L flag, this is
         handled in 'update_logic'.
         """
         pass
 
     def update_logic(self) -> None:
-        """
-        When the loop counter reaches zero, set the l flag to 1.
+        """When the loop counter reaches zero, set the l flag to 1.
         Otherwise set it to zero.
         """
         if self.value == 0:
@@ -145,12 +137,13 @@ class LC(Module):
             self.l_flag_s.update_value(0)
 
     def get_state(self) -> dict[str:Any]:
-        """
-        Returns a dict of the loop counter state.
+        """Returns a dict of the loop counter state.
         These states are changable via set_states.
 
-        :return: The state of the loop counter.
-        :rtype: dict[Any]
+        Returns
+        -------
+        dict[Any]
+            The state of the loop counter.
         """
         state = dict()
         state["name"] = self.name
@@ -163,9 +156,7 @@ class LC(Module):
         return state
 
     def set_state(self, state: dict[str:Any]) -> None:
-        """
-        Sets the loop counter state to one given in dict.
-        """
+        """Sets the loop counter state to one given in dict."""
         self.name = state["name"]
         self.value = state["value"]
         if "bit_length" in state:
@@ -180,9 +171,7 @@ class LC(Module):
             self.decrement_by_one = state["decrement_by_one"]
 
     def reset(self) -> None:
-        """
-        Resets the loop counter to 0.
-        """
+        """Resets the loop counter to 0."""
         super().reset()
         self.value = 0
         self.read_from_bus = False
@@ -190,9 +179,7 @@ class LC(Module):
         self.decrement_by_one = False
 
     def save_state_to_file(self, file_path: str) -> None:
-        """
-        Tries to save the modules state to a given file.
-        """
+        """Tries to save the modules state to a given file."""
         file = open(file_path, "a")
         file.write(self.name + ":\n")
         file.write("value: " + hex(self.value)[2:] + "\n\n")

src/simudator/processor/mia/modules/mia_memory.py

@@ -39,14 +39,14 @@ class MiaMemory(MiaBusConnector, Memory):
 
     def update_register(self) -> None:
         """
-        Updates the value of the current adress
+        Updates the value of the current adress.
         """
         if self.read_from_bus():
             self.memory[self.current_adress] = self.input_s.get_value()
 
     def output_register(self) -> None:
         """
-        Outputs the value of the current adress
+        Outputs the value of the current adress.
         """
         if self.write_to_bus():
             self.output_s.update_value(self.memory[self.current_adress])

src/simudator/processor/mia/modules/micro_memory.py

@@ -5,8 +5,7 @@ from simudator.core.signal import Signal
 
 
 class MicroMemory(Module):
-    """
-    An implementation of the micro memory from the MIA lab. The micro memory
+    """An implementation of the micro memory from the MIA lab. The micro memory
     has control signals for the ALU, bus transfer, the general registers GRx,
     the program counter PC, the loop counter LC and the micro program counter
     uPC. It also has signals for sending data to the bus, the LC and the uPC as
@@ -40,41 +39,46 @@ class MicroMemory(Module):
         value_padding: int = 7,
     ) -> None:
         """
-        :param alu: Control signal specifying the ALU operand.
-        :type alu: Signal
-        :param bus_control: Control signal for which modules should write to
-            and read from the bus.
-        :type bus_control: Signal
-        :param bus_constant: Signal for sending uADR instruction field to bus.
-        :type bus_constant: Signal
-        :param s: Control signal for [XXXXXXXXXX]
-        :type s: Signal
-        :param p: Control signal for program counter PC.
-        :type p: Signal
-        :param lc_control: Control signal for loop counter LC.
-        :type lc_control: Signal
-        :param lc_uadr: Signal for sending uADR instruction field to LC.
-        :type lc_uadr: Signal
-        :param upc: Signal carrying the value of the micro program counter uPC.
-        :type upc: Signal
-        :param upc_control: Control signal for uPC.
-        :type upc_control: Signal
-        :param upc_uadr: Signal for sending uADR instruction field to uPC.
-        :type upc_uadr: Signal
-        :param z_flag: Signal carrying the value of the z-flag.
-        :type z_flag: Signal
-        :param n_flag: Signal carrying the value of the n-flag.
-        :type n_flag: Signal
-        :param c_flag: Signal carrying the value of the c-flag.
-        :type c_flag: Signal
-        :param o_flag: Signal carrying the value of the o-flag.
-        :type o_flag: Signal
-        :param l_flag: Signal carrying the value of the l-flag.
-        :type l_flag: Signal
-        :param name: Optional name for the module. Defaults to 'uM'.
-        :type name: str
-
-        :return: None
+        Parameters
+        ----------
+        alu : Signal
+            Control signal specifying the ALU operand.
+        bus_control : Signal
+            Control signal for which modules should write to and read
+            from the bus.
+        bus_constant : Signal
+            Signal for sending uADR instruction field to bus.
+        s : Signal
+            Control signal for [XXXXXXXXXX]
+        p : Signal
+            Control signal for program counter PC.
+        lc_control : Signal
+            Control signal for loop counter LC.
+        lc_uadr : Signal
+            Signal for sending uADR instruction field to LC.
+        upc : Signal
+            Signal carrying the value of the micro program counter uPC.
+        upc_control : Signal
+            Control signal for uPC.
+        upc_uadr : Signal
+            Signal for sending uADR instruction field to uPC.
+        z_flag : Signal
+            Signal carrying the value of the z-flag.
+        n_flag : Signal
+            Signal carrying the value of the n-flag.
+        c_flag : Signal
+            Signal carrying the value of the c-flag.
+        o_flag : Signal
+            Signal carrying the value of the o-flag.
+        l_flag : Signal
+            Signal carrying the value of the l-flag.
+        name : str
+            Optional name for the module. Defaults to 'uM'.
+
+        Returns
+        -------
+        unknown
+            None
         """
 
         super().__init__(name)
@@ -124,7 +128,9 @@ class MicroMemory(Module):
 
     def update_logic(self) -> None:
         """
-        Update the micro controller with a new instruction index. The
+        Update the micro controller with a new instruction index.
+
+        The
         micro controller sets control signals to other modules in accordance
         with the micro instruction pointed to.
         """
@@ -238,8 +244,7 @@ class MicroMemory(Module):
                 self.halt = True
 
     def _conditional_jump(self, flag, cond_value, uadr):
-        """
-        Helper function for executing a conditional jump to the specified uadr
+        """Helper function for executing a conditional jump to the specified uadr
         if the specified flag has the specified value. If the condition is not
         true then uPC is increased by 1.
         """
@@ -250,8 +255,9 @@ class MicroMemory(Module):
         self.upc_control_s.update_value(0b000)
 
     def print_module(self) -> None:
-        """
-        Print the contents of the micro memory. Adresses which contain the
+        """Print the contents of the micro memory.
+
+        Adresses which contain the
         value 0 are not printed.
         """
         print("", self.name, "\n -----\n")
@@ -313,8 +319,7 @@ class MicroMemory(Module):
         self.halt = False  # Used for signalling a HALT
 
     def load_from_str(self, state_string) -> None:
-        """
-        Load the contents of the micro memory from a string consisting of a
+        """Load the contents of the micro memory from a string consisting of a
         row for every adress. Each row should be formatted as 'ADR: VALUE'.
         Both the adress and the value should be written in hex notation.
         Adresses which are not specified in the string will receive the value
@@ -341,9 +346,7 @@ class MicroMemory(Module):
                 self.memory[adress] = value
 
     def save_state_to_file(self, file_path: str) -> None:
-        """
-        Tries to save the modules state to a given file.
-        """
+        """Tries to save the modules state to a given file."""
         file = open(file_path, "a")
         file.write(self.name + ":\n")
         for index, value in enumerate(self.memory):
@@ -357,15 +360,13 @@ class MicroMemory(Module):
         file.close()
 
     def get_largest_mem_adr(self) -> int:
-        """
-        Helper function for pretty_print that returns the length of
+        """Helper function for pretty_print that returns the length of
         the largest adress in the memory to print for a module.
         """
         return len(str(len(self.memory)))
 
     def get_longest_line_len(self, ignore_keys=[]) -> int:
-        """
-        Helper function for pretty_print that returns the length of
+        """Helper function for pretty_print that returns the length of
         the longest value in the memory to print for a module.
         """
 

src/simudator/processor/mia/modules/pc.py

@@ -8,8 +8,9 @@ from simudator.processor.mia.modules.mia_bus_connect import MiaBusConnector
 
 
 class PC(Module, MiaBusConnector):
-    """
-    A program counter moduled after the mia lab. The module have two
+    """A program counter moduled after the mia lab.
+
+    The module have two
     control signals, p and bus_control. If the p signal is true the
     program counter increases its value by one, if the bus_control
     is true (the id to read from bus is the pc's id) the pc takes the
@@ -47,17 +48,14 @@ class PC(Module, MiaBusConnector):
         self.increase_by_one = False
 
     def output_register(self) -> None:
-        """
-        Output the value of the program counter to the bus.
-        """
+        """Output the value of the program counter to the bus."""
         if self.write_to_bus():
             self.bus_output_s.update_value(self.value)
         else:
             self.bus_output_s.update_value(None)
 
     def update_register(self) -> None:
-        """
-        Updates the value of the PC according to the signals sent
+        """Updates the value of the PC according to the signals sent
         by the micro memory. If the program counter recives
         'True' from both signals it should do nothing and wait for the
         next cycle.
@@ -79,12 +77,13 @@ class PC(Module, MiaBusConnector):
         self.output_register()
 
     def get_state(self) -> dict[str:Any]:
-        """
-        Returns a dict of the program counter state.
+        """Returns a dict of the program counter state.
         These states are changable via set_states.
 
-        :return: The state of the program counter.
-        :rtype: dict[Any]
+        Returns
+        -------
+        dict[Any]
+            The state of the program counter.
         """
         state = dict()
         state["name"] = self.name
@@ -101,25 +100,19 @@ class PC(Module, MiaBusConnector):
         return state
 
     def set_state(self, state: dict[str:Any]) -> None:
-        """
-        Sets the program counter state to one given in dict.
-        """
+        """Sets the program counter state to one given in dict."""
         self.name = state["name"]
         self.value = state["value"]
         if "increment" in state:
             self.increase_by_one = state["increment"]
 
     def reset(self) -> None:
-        """
-        Reset the program counter to 0.
-        """
+        """Reset the program counter to 0."""
         self.value = 0
         self.increase_by_one = False
 
     def save_state_to_file(self, file_path: str) -> None:
-        """
-        Tries to save the modules state to a given file.
-        """
+        """Tries to save the modules state to a given file."""
         file = open(file_path, "a")
         file.write(self.name + ":\n")
         file.write("value: " + hex(self.value)[2:] + "\n\n")

test/test_mia/mia_memory_data_test.txt

 PM1:
-0: 0a 
-2: 0f 
+0: 0a
+2: 0f
 
 PM2:
-1: 02 
-3: 00 
+1: 02
+3: 00