ciphers.trifid_cipher
=====================

.. py:module:: ciphers.trifid_cipher

.. autoapi-nested-parse::

   The trifid cipher uses a table to fractionate each plaintext letter into a trigram,
   mixes the constituents of the trigrams, and then applies the table in reverse to turn
   these mixed trigrams into ciphertext letters.

   https://en.wikipedia.org/wiki/Trifid_cipher



Attributes
----------

.. autoapisummary::

   ciphers.trifid_cipher.TEST_CHARACTER_TO_NUMBER
   ciphers.trifid_cipher.TEST_NUMBER_TO_CHARACTER
   ciphers.trifid_cipher.msg


Functions
---------

.. autoapisummary::

   ciphers.trifid_cipher.__decrypt_part
   ciphers.trifid_cipher.__encrypt_part
   ciphers.trifid_cipher.__prepare
   ciphers.trifid_cipher.decrypt_message
   ciphers.trifid_cipher.encrypt_message


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

.. py:function:: __decrypt_part(message_part: str, character_to_number: dict[str, str]) -> tuple[str, str, str]

   Convert each letter of the input string into their respective trigram values, join
   them and split them into three equal groups of strings which are returned.

   >>> __decrypt_part('ABCDE', TEST_CHARACTER_TO_NUMBER)
   ('11111', '21131', '21122')


.. py:function:: __encrypt_part(message_part: str, character_to_number: dict[str, str]) -> str

   Arrange the triagram value of each letter of `message_part` vertically and join
   them horizontally.

   >>> __encrypt_part('ASK', TEST_CHARACTER_TO_NUMBER)
   '132111112'


.. py:function:: __prepare(message: str, alphabet: str) -> tuple[str, str, dict[str, str], dict[str, str]]

   A helper function that generates the triagrams and assigns each letter of the
   alphabet to its corresponding triagram and stores this in a dictionary
   (`character_to_number` and `number_to_character`) after confirming if the
   alphabet's length is ``27``.

   >>> test = __prepare('I aM a BOy','abCdeFghijkLmnopqrStuVwxYZ+')
   >>> expected = ('IAMABOY','ABCDEFGHIJKLMNOPQRSTUVWXYZ+',
   ... TEST_CHARACTER_TO_NUMBER, TEST_NUMBER_TO_CHARACTER)
   >>> test == expected
   True

   Testing with incomplete alphabet

   >>> __prepare('I aM a BOy','abCdeFghijkLmnopqrStuVw')
   Traceback (most recent call last):
       ...
   KeyError: 'Length of alphabet has to be 27.'

   Testing with extra long alphabets

   >>> __prepare('I aM a BOy','abCdeFghijkLmnopqrStuVwxyzzwwtyyujjgfd')
   Traceback (most recent call last):
       ...
   KeyError: 'Length of alphabet has to be 27.'

   Testing with punctuation not in the given alphabet

   >>> __prepare('am i a boy?','abCdeFghijkLmnopqrStuVwxYZ+')
   Traceback (most recent call last):
       ...
   ValueError: Each message character has to be included in alphabet!

   Testing with numbers

   >>> __prepare(500,'abCdeFghijkLmnopqrStuVwxYZ+')
   Traceback (most recent call last):
       ...
   AttributeError: 'int' object has no attribute 'replace'


.. py:function:: decrypt_message(message: str, alphabet: str = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ.', period: int = 5) -> str

   decrypt_message
   ===============

   Decrypts a trifid_cipher encrypted message.

   PARAMETERS
   ----------

   *   `message`: The message you want to decrypt.
   *   `alphabet` (optional): The characters used for the cipher.
   *   `period` (optional): The number of characters used in grouping when it
       was encrypted.

   >>> decrypt_message('BCDGBQY')
   'IAMABOY'

   Decrypting with your own alphabet and period

   >>> decrypt_message('FMJFVOISSUFTFPUFEQQC','FELIXMARDSTBCGHJKNOPQUVWYZ+',5)
   'AIDETOILECIELTAIDERA'


.. py:function:: encrypt_message(message: str, alphabet: str = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ.', period: int = 5) -> str

   encrypt_message
   ===============

   Encrypts a message using the trifid_cipher. Any punctuatuion chars that
   would be used should be added to the alphabet.

   PARAMETERS
   ----------

   *   `message`: The message you want to encrypt.
   *   `alphabet` (optional): The characters to be used for the cipher .
   *   `period` (optional): The number of characters you want in a group whilst
       encrypting.

   >>> encrypt_message('I am a boy')
   'BCDGBQY'

   >>> encrypt_message(' ')
   ''

   >>> encrypt_message('   aide toi le c  iel      ta id  era    ',
   ... 'FELIXMARDSTBCGHJKNOPQUVWYZ+',5)
   'FMJFVOISSUFTFPUFEQQC'



.. py:data:: TEST_CHARACTER_TO_NUMBER

.. py:data:: TEST_NUMBER_TO_CHARACTER

.. py:data:: msg
   :value: 'DEFEND THE EAST WALL OF THE CASTLE.'