ciphers.enigma_machine2
=======================

.. py:module:: ciphers.enigma_machine2

.. autoapi-nested-parse::

   | Wikipedia: https://en.wikipedia.org/wiki/Enigma_machine
   | Video explanation: https://youtu.be/QwQVMqfoB2E
   | Also check out Numberphile's and Computerphile's videos on this topic

   This module contains function ``enigma`` which emulates
   the famous Enigma machine from WWII.

   Module includes:

   - ``enigma`` function
   - showcase of function usage
   - ``9`` randomly generated rotors
   - reflector (aka static rotor)
   - original alphabet

   Created by TrapinchO



Attributes
----------

.. autoapisummary::

   ciphers.enigma_machine2.RotorPositionT
   ciphers.enigma_machine2.RotorSelectionT
   ciphers.enigma_machine2.abc
   ciphers.enigma_machine2.message
   ciphers.enigma_machine2.reflector
   ciphers.enigma_machine2.rotor1
   ciphers.enigma_machine2.rotor2
   ciphers.enigma_machine2.rotor3
   ciphers.enigma_machine2.rotor4
   ciphers.enigma_machine2.rotor5
   ciphers.enigma_machine2.rotor6
   ciphers.enigma_machine2.rotor7
   ciphers.enigma_machine2.rotor8
   ciphers.enigma_machine2.rotor9


Functions
---------

.. autoapisummary::

   ciphers.enigma_machine2._plugboard
   ciphers.enigma_machine2._validator
   ciphers.enigma_machine2.enigma


Module Contents
---------------

.. py:function:: _plugboard(pbstring: str) -> dict[str, str]

   https://en.wikipedia.org/wiki/Enigma_machine#Plugboard

   >>> _plugboard('PICTURES')
   {'P': 'I', 'I': 'P', 'C': 'T', 'T': 'C', 'U': 'R', 'R': 'U', 'E': 'S', 'S': 'E'}
   >>> _plugboard('POLAND')
   {'P': 'O', 'O': 'P', 'L': 'A', 'A': 'L', 'N': 'D', 'D': 'N'}

   In the code, ``pb`` stands for ``plugboard``

   Pairs can be separated by spaces

   :param pbstring: string containing plugboard setting for the Enigma machine
   :return: dictionary containing converted pairs


.. py:function:: _validator(rotpos: RotorPositionT, rotsel: RotorSelectionT, pb: str) -> tuple[RotorPositionT, RotorSelectionT, dict[str, str]]

   Checks if the values can be used for the ``enigma`` function

   >>> _validator((1,1,1), (rotor1, rotor2, rotor3), 'POLAND')
   ((1, 1, 1), ('EGZWVONAHDCLFQMSIPJBYUKXTR', 'FOBHMDKEXQNRAULPGSJVTYICZW', 'ZJXESIUQLHAVRMDOYGTNFWPBKC'), {'P': 'O', 'O': 'P', 'L': 'A', 'A': 'L', 'N': 'D', 'D': 'N'})

   :param rotpos: rotor_positon
   :param rotsel: rotor_selection
   :param pb: plugb -> validated and transformed
   :return: (`rotpos`, `rotsel`, `pb`)


.. py:function:: enigma(text: str, rotor_position: RotorPositionT, rotor_selection: RotorSelectionT = (rotor1, rotor2, rotor3), plugb: str = '') -> str

   The only difference with real-world enigma is that ``I`` allowed string input.
   All characters are converted to uppercase. (non-letter symbol are ignored)

   | How it works:
   | (for every letter in the message)

   - Input letter goes into the plugboard.
     If it is connected to another one, switch it.

   - Letter goes through ``3`` rotors.
     Each rotor can be represented as ``2`` sets of symbol, where one is shuffled.
     Each symbol from the first set has corresponding symbol in
     the second set and vice versa.

     example::

     | ABCDEFGHIJKLMNOPQRSTUVWXYZ | e.g. F=D and D=F
     | VKLEPDBGRNWTFCJOHQAMUZYIXS |

   - Symbol then goes through reflector (static rotor).
     There it is switched with paired symbol.
     The reflector can be represented as ``2`` sets, each with half of the alphanet.
     There are usually ``10`` pairs of letters.

     Example::

     | ABCDEFGHIJKLM | e.g. E is paired to X
     | ZYXWVUTSRQPON | so when E goes in X goes out and vice versa

   - Letter then goes through the rotors again

   - If the letter is connected to plugboard, it is switched.

   - Return the letter

   >>> enigma('Hello World!', (1, 2, 1), plugb='pictures')
   'KORYH JUHHI!'
   >>> enigma('KORYH, juhhi!', (1, 2, 1), plugb='pictures')
   'HELLO, WORLD!'
   >>> enigma('hello world!', (1, 1, 1), plugb='pictures')
   'FPNCZ QWOBU!'
   >>> enigma('FPNCZ QWOBU', (1, 1, 1), plugb='pictures')
   'HELLO WORLD'


   :param text: input message
   :param rotor_position: tuple with ``3`` values in range ``1``.. ``26``
   :param rotor_selection: tuple with ``3`` rotors
   :param plugb: string containing plugboard configuration (default ``''``)
   :return: en/decrypted string


.. py:data:: RotorPositionT

.. py:data:: RotorSelectionT

.. py:data:: abc
   :value: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'


.. py:data:: message
   :value: 'This is my Python script that emulates the Enigma machine from WWII.'


.. py:data:: reflector

.. py:data:: rotor1
   :value: 'EGZWVONAHDCLFQMSIPJBYUKXTR'


.. py:data:: rotor2
   :value: 'FOBHMDKEXQNRAULPGSJVTYICZW'


.. py:data:: rotor3
   :value: 'ZJXESIUQLHAVRMDOYGTNFWPBKC'


.. py:data:: rotor4
   :value: 'RMDJXFUWGISLHVTCQNKYPBEZOA'


.. py:data:: rotor5
   :value: 'SGLCPQWZHKXAREONTFBVIYJUDM'


.. py:data:: rotor6
   :value: 'HVSICLTYKQUBXDWAJZOMFGPREN'


.. py:data:: rotor7
   :value: 'RZWQHFMVDBKICJLNTUXAGYPSOE'


.. py:data:: rotor8
   :value: 'LFKIJODBEGAMQPXVUHYSTCZRWN'


.. py:data:: rotor9
   :value: 'KOAEGVDHXPQZMLFTYWJNBRCIUS'