retro-ciphers 1.0.0__tar.gz

retro_ciphers-1.0.0/.gitignore

@@ -0,0 +1,4 @@
+.venv
+.pytest_cache
+__pycache__
+src/retro_ciphers/run.py

retro_ciphers-1.0.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2026 Sarthak Patil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

retro_ciphers-1.0.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: retro-ciphers
+Version: 1.0.0
+Summary: Classical ciphers implementation in python
+Project-URL: Homepage, https://crypto.sarthak.co.in
+Project-URL: Documentation, https://github.com/sarthac/retro-ciphers
+Project-URL: Repository, https://github.com/sarthac/retro-ciphers.git
+Project-URL: Issues, https://github.com/sarthac/retro-ciphers/issues
+Author-email: Sarthak Patil <mail@sarthak.co.in>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: caesar,ciphers,classical ciphers,cryptography,historical ciphers,retro ciphers,vigenere
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Retro Ciphers
+
+**Retro Ciphers** is implementations of classical and historical ciphers. It is intended for educational purposes, cryptography enthusiasts, or anyone interested in the history of hidden messages.
+
+This package encompasses both **Monoalphabetic** and **Polyalphabetic** substitution ciphers,to include modern interpretations as well as strict, historically accurate 15th-century variants.
+
+## Installation
+
+You can easily install `retro-ciphers` via pip:
+
+```bash
+pip install retro-ciphers
+```
+
+*(Requires Python 3.12 or higher)*
+
+## Features
+
+`retro-ciphers` provides clean, object-oriented API access to the following historical ciphers:
+
+### Monoalphabetic Ciphers
+- **Atbash**: The classic Hebrew reversal cipher.
+- **Caesar / Shift / ROT13**: Classical shift ciphers with custom shift lengths.
+- **Mixed Alphabet**: Key-based shift mechanisms mapping the standard alphabet.
+- **Simple Substitution**: Create completely custom scrambled mappings.
+- **Baconian Cipher**: Francis Bacon's steganographic, binary-like cipher (supports both classic 24-letter and modern 26-letter alphabets).
+- **Polybius Square**: The classical ancient Greek fractionating cipher (coordinates).
+
+### Polyalphabetic Ciphers
+- **Alberti Cipher**: The first polyalphabetic cipher! Supports both standard English 26-character modern modes AND the historically accurate 1467 Latin 24/24 Character Disks implementation seamlessly!
+- **Trithemius Cipher**: Johannes Trithemius's tabula recta system.
+- **Vigenère Cipher**: The famous, unbroken mathematical improvement using table offsets.
+- **Beaufort Cipher**: A variant of Vigenère using a reversed tabula recta mechanism.
+- **Autokey Cipher**: An extension where the plaintext itself becomes part of the key.
+
+## Quick Start
+
+The API is simple: initialize your chosen cipher, then use `.cipher()` to encrypt and `.decipher()` to decrypt text.
+
+### Monoalphabetic Examples
+
+```python
+from retro_ciphers.mono import Caesar, Atbash, Baconian
+
+# Caesar Cipher
+caesar = Caesar() # Default shift of 3
+encrypted = caesar.cipher("Hello World!")
+# >>> "Khoor Zruog!"
+
+# Atbash Cipher
+atbash = Atbash()
+print(atbash.cipher("Classical Cryptography"))
+# >>> "Xozhhzxzo Xibkgltizksb"
+
+# Baconian Cipher
+bacon = Baconian(modern_implementation=True)
+print(bacon.cipher("Hide"))
+# >>> "AABBBABAAAAABABAABAA"
+```
+
+### Polyalphabetic Examples
+
+```python
+from retro_ciphers.poly import Vigenere, Alberti
+
+# Vigenère Cipher
+vigenere = Vigenere("LEMON")
+encrypted = vigenere.cipher("ATTACK AT DAWN")
+print(encrypted)
+# >>> "LXFOPV EF RNHR"
+
+decrypted = vigenere.decipher(encrypted)
+print(decrypted)
+# >>> "ATTACK AT DAWN"
+
+# Alberti Cipher (Historical 1467 Mode)
+# Uses the original Latin outer ("ABCDEFGILMNOPQRSTVXZ1234") and inner mappings
+alberti = Alberti(key="a", modern_implementation=False)
+secret = alberti.cipher("ABCDEFGHI")
+print(secret)
+```
+
+## Extra arguments
+
+- `omit_non_alpha`: Available in the `cipher()` methods across ciphers (such as `Alberti` and `Autokey`). Accepts a boolean value (default: `False`). If `True`, it removes special symbols such as punctuation from the ciphertext. If `False`, it safely passes them through so they are kept intact.
+- `Alberti(key, frequency=50, modern_implementation=True)`: 
+  - `modern_implementation`: By default (`True`), the cipher uses the standard modern English A-Z alphabet. If you pass `False`, it enforces the historically accurate 1467 24-character Latin disks.
+  - `frequency`: By default (`50`), the Alberti cipher automatically changes its mapping disk (indicating via a new outer key) every 50 characters to improve security against cryptanalysis. You can increase or decrease this rate.
+- `Baconian(modern_implementation=True)`: By default (`True`), uses the full 26-letter alphabet. If `False`, it mimics Bacon's original 24-letter alphabet where 'I' & 'J' and 'U' & 'V' map to the same sequences. 
+
+## License
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

retro_ciphers-1.0.0/README.md

@@ -0,0 +1,92 @@
+# Retro Ciphers
+
+**Retro Ciphers** is implementations of classical and historical ciphers. It is intended for educational purposes, cryptography enthusiasts, or anyone interested in the history of hidden messages.
+
+This package encompasses both **Monoalphabetic** and **Polyalphabetic** substitution ciphers,to include modern interpretations as well as strict, historically accurate 15th-century variants.
+
+## Installation
+
+You can easily install `retro-ciphers` via pip:
+
+```bash
+pip install retro-ciphers
+```
+
+*(Requires Python 3.12 or higher)*
+
+## Features
+
+`retro-ciphers` provides clean, object-oriented API access to the following historical ciphers:
+
+### Monoalphabetic Ciphers
+- **Atbash**: The classic Hebrew reversal cipher.
+- **Caesar / Shift / ROT13**: Classical shift ciphers with custom shift lengths.
+- **Mixed Alphabet**: Key-based shift mechanisms mapping the standard alphabet.
+- **Simple Substitution**: Create completely custom scrambled mappings.
+- **Baconian Cipher**: Francis Bacon's steganographic, binary-like cipher (supports both classic 24-letter and modern 26-letter alphabets).
+- **Polybius Square**: The classical ancient Greek fractionating cipher (coordinates).
+
+### Polyalphabetic Ciphers
+- **Alberti Cipher**: The first polyalphabetic cipher! Supports both standard English 26-character modern modes AND the historically accurate 1467 Latin 24/24 Character Disks implementation seamlessly!
+- **Trithemius Cipher**: Johannes Trithemius's tabula recta system.
+- **Vigenère Cipher**: The famous, unbroken mathematical improvement using table offsets.
+- **Beaufort Cipher**: A variant of Vigenère using a reversed tabula recta mechanism.
+- **Autokey Cipher**: An extension where the plaintext itself becomes part of the key.
+
+## Quick Start
+
+The API is simple: initialize your chosen cipher, then use `.cipher()` to encrypt and `.decipher()` to decrypt text.
+
+### Monoalphabetic Examples
+
+```python
+from retro_ciphers.mono import Caesar, Atbash, Baconian
+
+# Caesar Cipher
+caesar = Caesar() # Default shift of 3
+encrypted = caesar.cipher("Hello World!")
+# >>> "Khoor Zruog!"
+
+# Atbash Cipher
+atbash = Atbash()
+print(atbash.cipher("Classical Cryptography"))
+# >>> "Xozhhzxzo Xibkgltizksb"
+
+# Baconian Cipher
+bacon = Baconian(modern_implementation=True)
+print(bacon.cipher("Hide"))
+# >>> "AABBBABAAAAABABAABAA"
+```
+
+### Polyalphabetic Examples
+
+```python
+from retro_ciphers.poly import Vigenere, Alberti
+
+# Vigenère Cipher
+vigenere = Vigenere("LEMON")
+encrypted = vigenere.cipher("ATTACK AT DAWN")
+print(encrypted)
+# >>> "LXFOPV EF RNHR"
+
+decrypted = vigenere.decipher(encrypted)
+print(decrypted)
+# >>> "ATTACK AT DAWN"
+
+# Alberti Cipher (Historical 1467 Mode)
+# Uses the original Latin outer ("ABCDEFGILMNOPQRSTVXZ1234") and inner mappings
+alberti = Alberti(key="a", modern_implementation=False)
+secret = alberti.cipher("ABCDEFGHI")
+print(secret)
+```
+
+## Extra arguments
+
+- `omit_non_alpha`: Available in the `cipher()` methods across ciphers (such as `Alberti` and `Autokey`). Accepts a boolean value (default: `False`). If `True`, it removes special symbols such as punctuation from the ciphertext. If `False`, it safely passes them through so they are kept intact.
+- `Alberti(key, frequency=50, modern_implementation=True)`: 
+  - `modern_implementation`: By default (`True`), the cipher uses the standard modern English A-Z alphabet. If you pass `False`, it enforces the historically accurate 1467 24-character Latin disks.
+  - `frequency`: By default (`50`), the Alberti cipher automatically changes its mapping disk (indicating via a new outer key) every 50 characters to improve security against cryptanalysis. You can increase or decrease this rate.
+- `Baconian(modern_implementation=True)`: By default (`True`), uses the full 26-letter alphabet. If `False`, it mimics Bacon's original 24-letter alphabet where 'I' & 'J' and 'U' & 'V' map to the same sequences. 
+
+## License
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

retro_ciphers-1.0.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling >= 1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "retro-ciphers"
+version = "1.0.0"
+authors = [
+  { name="Sarthak Patil", email="mail@sarthak.co.in" },
+]
+description = "Classical ciphers implementation in python"
+requires-python = ">=3.12"
+dependencies = []
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Security :: Cryptography",
+    "Intended Audience :: Developers",
+    "Development Status :: 4 - Beta",
+    "Natural Language :: English",
+    "Typing :: Typed",
+]
+license = "MIT"
+license-file = "LICENSE"
+readme = "README.md"
+keywords = ["retro ciphers", "ciphers", "cryptography", "caesar", "vigenere", "classical ciphers", "historical ciphers"]
+
+[project.urls]
+Homepage = "https://crypto.sarthak.co.in"
+Documentation = "https://github.com/sarthac/retro-ciphers"
+Repository = "https://github.com/sarthac/retro-ciphers.git"
+Issues = "https://github.com/sarthac/retro-ciphers/issues"

retro_ciphers-1.0.0/src/retro_ciphers/__init__.py

@@ -0,0 +1,3 @@
+# from .base import *
+from .mono import *
+from .poly import *

retro_ciphers-1.0.0/src/retro_ciphers/base.py

@@ -0,0 +1,142 @@
+from abc import ABC, abstractmethod
+import string
+from typing import override, Sequence
+from itertools import cycle
+
+
+class Substitution(ABC):
+    @abstractmethod
+    def cipher(self, text: str) -> str:
+        pass
+
+    @abstractmethod
+    def decipher(self, text: str) -> str:
+        pass
+
+    def __call__(self, text: str) -> str:
+        """Allows the cipher object to be called directly to encrypt text."""
+        return self.cipher(text)
+
+
+class MonoalphabeticSubstitution(Substitution):
+    """
+    A base class for creating monoalphabetic substitution ciphers.
+    """
+
+    def __init__(self, cipher_alphabet: Sequence[str]):
+        """
+        Takes a 26-character sequence and automatically builds
+        a dual-case mapping dictionary to preserve original formatting.
+        """
+        # 1. Build the lowercase mapping
+        lower_base = string.ascii_lowercase
+        lower_cipher = [char.lower() for char in cipher_alphabet]
+        lower_map = dict(zip(lower_base, lower_cipher))
+
+        # 2. Build the uppercase mapping
+        upper_base = string.ascii_uppercase
+        upper_cipher = [char.upper() for char in cipher_alphabet]
+        upper_map = dict(zip(upper_base, upper_cipher))
+
+        # 3. Merge them into a single 52-pair dictionary!
+        self.mapping: dict = lower_map | upper_map
+        self.reverse_mapping: dict = {v: k for k, v in self.mapping.items()}
+
+    @override
+    def cipher(self, text: str, omit_non_alpha: bool = False) -> str:
+        result: str = ""
+
+        for char in text:
+            if char.isalpha():
+                result += self.mapping[char]
+            elif not omit_non_alpha or (char in string.whitespace):
+                result += char
+
+        return result
+
+    @override
+    def decipher(self, text: str) -> str:
+        return "".join(self.reverse_mapping.get(char, char) for char in text)
+
+    def __str__(self) -> str:
+        base = string.ascii_letters
+        cipher_mapping = "".join(self.mapping.values())
+
+        return (
+            f"--- {self.__class__.__name__} Cipher ---\n"
+            f"Plain:  {base}\n"
+            f"Cipher: {cipher_mapping}\n"
+        )
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, MonoalphabeticSubstitution):
+            return NotImplemented
+        # Two ciphers are equal if their cipher_alphabet dictionaries are exactly the same
+        return self.mapping == other.mapping
+
+
+class PolyalphabeticSubstitution(Substitution):
+    def __init__(self, key: str):
+        # Call the generation method as a standard function
+        self.tabula_recta = self._generate_table()
+        if not key:
+            raise ValueError("Key must not be empty.")
+        self.key = key.upper()
+        if not any(char.isalpha() for char in self.key):
+            raise ValueError("Key must contain at least one letter.")
+
+    def _generate_table(self) -> list[list[str]]:
+        """Create a square table of alphabets (Vigenère by default)."""
+        tabula_recta: list[list[str]] = []
+        for i in range(26):
+            tabula_recta.append(
+                list(string.ascii_uppercase[i:] + string.ascii_uppercase[:i])
+            )
+        return tabula_recta
+
+    def _get_key_sequence(self) -> list[int]:
+        """Maps the keyword to a sequence of shifts."""
+        clean_key = [char.upper() for char in self.key if char.isalpha()]
+        if not clean_key:
+            raise ValueError("Key must contain at least one letter.")
+        return [ord(char) - 65 for char in clean_key]
+
+    @override
+    def cipher(self, text: str, omit_non_alpha: bool = False) -> str:
+        result: str = ""
+        key_cycle = cycle(self._get_key_sequence())
+
+        for char in text.upper():
+            if char.isalpha():
+                key_char = next(key_cycle)
+                row = key_char
+                # convert text_char to int then -65 as the ascii upper letters start at 65, to get the index of the column.
+                column = ord(char) - 65
+                result += self.tabula_recta[row][column]
+
+            elif not omit_non_alpha or (char in string.whitespace):
+                result += char
+
+        return result
+
+    @override
+    def decipher(self, text: str) -> str:
+        result: str = ""
+        key_cycle = cycle(self._get_key_sequence())
+
+        for char in text.upper():
+            if char.isalpha():
+                key_char = next(key_cycle)
+                column = self.tabula_recta[key_char].index(char)
+                result += self.tabula_recta[0][column]
+            else:
+                result += char
+        return result
+
+    def __str__(self) -> str:
+        key = self.key
+
+        return f"--- {self.__class__.__name__} Cipher ---\n" f"Key:  {key!r}\n"
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(key={self.key!r})"

retro_ciphers-1.0.0/src/retro_ciphers/mono.py

@@ -0,0 +1,265 @@
+from .base import MonoalphabeticSubstitution
+import string
+from typing import override
+import random
+
+
+"""
+The following ciphers are implemented:
+- MixedAlphabet: A substitution cipher with a mixed alphabet generated from a keyword.
+- Atbash: A simple substitution cipher where the alphabet is reversed.
+- SimpleSubstitution: A substitution cipher with a randomly generated or user-defined cipher alphabet.
+- Rotate: A substitution cipher that rotates the alphabet by a given shift.
+- Caesar: A specific instance of the Rotate cipher with a shift of 3.
+- Rot13: A specific instance of the Rotate cipher with a shift of 13.
+- Baconian: A substitution cipher that uses a 5-character binary representation for each letter.
+- PolybiusSquare: A substitution cipher that uses a 5x5 grid to represent each letter.
+"""
+
+
+class Atbash(MonoalphabeticSubstitution):
+    def __init__(self):
+        super().__init__(string.ascii_lowercase[::-1])
+
+
+class Shift(MonoalphabeticSubstitution):
+    def __init__(self, shift: int):
+        # The modulo ensures shifts larger than 26 wrap around safely
+        base = string.ascii_lowercase
+        self.shift = shift % len(base)
+        cipher_alphabet: str = base[self.shift :] + base[: self.shift]
+        super().__init__(cipher_alphabet)
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(shift={self.shift})"
+
+
+class Caesar(Shift):
+    def __init__(self):
+        super().__init__(shift=3)
+
+
+class Rot13(Shift):
+    def __init__(self):
+        super().__init__(shift=13)
+
+
+class MixedAlphabet(MonoalphabeticSubstitution):
+    """
+    A substitution cipher with a mixed alphabet generated from a keyword.
+
+    The cipher alphabet is created by taking the unique letters of the keyword,
+    followed by the remaining letters of the alphabet in their normal order.
+    """
+
+    def __init__(self, keyword: str) -> None:
+        # removing duplicate letter in the keyword to make the cipher_alphanet 26 chars
+        self.keyword = "".join(filter(str.isalpha, keyword.lower()))
+        # make keyword unique so the cipher alphanet does not include dublicates and it should 26 exact
+        clean_keyword = list(dict.fromkeys(self.keyword))
+        cipher_alphabet = clean_keyword
+        for letter in string.ascii_lowercase:
+            if letter not in cipher_alphabet:
+                cipher_alphabet.append(letter)
+
+        super().__init__(cipher_alphabet)
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(keyword={self.keyword!r})"
+
+
+class SimpleSubstitution(MonoalphabeticSubstitution):
+    """
+    A substitution cipher with a randomly generated or user-defined cipher alphabet.
+    """
+
+    # user need to know the cipher_alphabet as it is a key to cipher and decipher.
+    # user provide one or generate one using a static method.
+    def __init__(self, cipher_alphabet: str) -> None:
+        if (
+            len(dict.fromkeys(c.lower() for c in cipher_alphabet)) != 26
+            or len(cipher_alphabet) != 26
+        ):
+            raise ValueError(
+                "cipher_alphabets must be unqiue and 26 char long OR generate one by executing 'SimpleSubstitution.generate_cipher_alphabet()'"
+            )
+        self.cipher_alphabet = cipher_alphabet
+        super().__init__(self.cipher_alphabet)
+
+    @staticmethod
+    def generate_cipher_alphabet() -> str:
+        """
+        Generates a random cipher alphabet.
+
+        Returns:
+            A string representing the random cipher alphabet.
+        """
+        return "".join(random.sample(string.ascii_lowercase, k=26))
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(cipher_alphabet={self.cipher_alphabet!r})"
+
+
+class Baconian(MonoalphabeticSubstitution):
+    """
+    A substitution cipher that uses a 5-character binary representation for each letter.
+    """
+
+    modern_baconian_cipher = [
+        "aaaaa",  # a
+        "aaaab",  # b
+        "aaaba",  # c
+        "aaabb",  # d
+        "aabaa",  # e
+        "aabab",  # f
+        "aabba",  # g
+        "aabbb",  # h
+        "abaaa",  # i
+        "abaab",  # j
+        "ababa",  # k
+        "ababb",  # l
+        "abbaa",  # m
+        "abbab",  # n
+        "abbba",  # o
+        "abbbb",  # p
+        "baaaa",  # q
+        "baaab",  # r
+        "baaba",  # s
+        "baabb",  # t
+        "babaa",  # u
+        "babab",  # v
+        "babba",  # w
+        "babbb",  # x
+        "bbaaa",  # y
+        "bbaab",  # z
+    ]
+
+    classic_baconian_cipher = [
+        "aaaaa",  # A
+        "aaaab",  # B
+        "aaaba",  # C
+        "aaabb",  # D
+        "aabaa",  # E
+        "aabab",  # F
+        "aabba",  # G
+        "aabbb",  # H
+        "abaaa",  # I / J
+        "abaaa",  # I / J
+        "abaab",  # K
+        "ababa",  # L
+        "ababb",  # M
+        "abbaa",  # N
+        "abbab",  # O
+        "abbba",  # P
+        "abbbb",  # Q
+        "baaaa",  # R
+        "baaab",  # S
+        "baaba",  # T
+        "baabb",  # U / V
+        "baabb",  # U / V
+        "babaa",  # W
+        "babab",  # X
+        "babba",  # Y
+        "babbb",  # Z
+    ]
+
+    def __init__(self, modern_implementation=True) -> None:
+        """
+        Initializes the Baconian cipher.
+
+        Args:
+            modern_implementation: Whether to use the modern or old implementation of the cipher.
+        """
+        self.modern_implementation = modern_implementation
+        self.cipher_alphabet = (
+            self.modern_baconian_cipher
+            if self.modern_implementation
+            else self.classic_baconian_cipher
+        )
+        super().__init__(self.cipher_alphabet)
+
+    @override
+    def decipher(self, text: str) -> str:
+        plain_text = ""
+        i = 0
+        # setting up the cipher word lenth
+        word_length = 5
+        while i < len(text):
+            if not text[i].isalpha():
+                plain_text += text[i]
+                i += 1
+            else:
+                # grabing next five chars
+                block = text[i : i + word_length]
+                # look into dictionary to decipher to single char
+                plain_text += self.reverse_mapping.get(block, block)
+                # switch index to next five chars
+                i += word_length
+        return plain_text
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(modern_implementation={self.modern_implementation})"
+
+
+class PolybiusSquare(MonoalphabeticSubstitution):
+    """
+    A substitution cipher that uses a 5x5 grid to represent each letter.
+
+    A Polybius Square is a 5x5 grid. 5 x 5 = 25 total coordinates (from "11" to "55").
+    However, your self.base_alphabet (the standard English alphabet) has 26 letters.
+
+    Ancient Greeks and classic cryptographers solved this by making two letters share the exact same cell in the grid. Usually, 'I' and 'J' share a spot (though sometimes 'C' and 'K' share one).
+
+    To fix this in your code without having to rewrite your beautiful parent class, you just need to pass a 26-item list where the coordinates for 'i' and 'j' are identical.
+    """
+
+    cipher_alphabets = [
+        "11",
+        "12",
+        "13",
+        "14",
+        "15",
+        "21",
+        "22",
+        "23",
+        "24",
+        "24",
+        "25",
+        "31",
+        "32",
+        "33",
+        "34",
+        "35",
+        "41",
+        "42",
+        "43",
+        "44",
+        "45",
+        "51",
+        "52",
+        "53",
+        "54",
+        "55",
+    ]
+
+    def __init__(self) -> None:
+        super().__init__(self.cipher_alphabets)
+
+    @override
+    def decipher(self, text: str) -> str:
+        plain_text = ""
+        i = 0
+        # setting up the cipher word lenth
+        word_length = 2
+        while i < len(text):
+            if not text[i].isnumeric():
+                plain_text += text[i]
+                i += 1
+            else:
+                # grabing next two chars
+                block = text[i : i + word_length]
+                # look into dictionary to decipher to single char
+                plain_text += self.reverse_mapping.get(block, block)
+                # switch index to next two chars
+                i += word_length
+        return plain_text

retro_ciphers-1.0.0/src/retro_ciphers/poly.py

@@ -0,0 +1,324 @@
+from .base import Substitution, PolyalphabeticSubstitution
+import string
+from typing import override
+from itertools import cycle
+import random
+
+"""
+The history of the Polyalphabetci substitution cipher
+
+Alberti cipher
+	↓
+Trithemius cipher
+	↓
+Vigenere cipher
+	↓
+Beaufort cipher
+	↓
+Autokey cipher
+
+
+----------------------------------------------------------
+
+Alberti cipher 
+
+- was one of the first polyalphabetic ciphers.
+
+WIKI - https://en.wikipedia.org/wiki/Alberti_cipher
+
+----------------------------------------------------------
+
+Trithemius cipher
+
+- Grab the inspiration from the Alberti ciper but uses it own table, that make it uqnique. It creates it own key by the sequnce of the input text letters, first letter will be A, Second letter wil be B and so on, after the end of Z return to A.
+
+WIKI - https://en.wikipedia.org/wiki/Tabula_recta#Trithemius%20cipher
+
+----------------------------------------------------------
+
+Vigenera cipher 
+
+- an important extension to Trithemius's method, Need a key; not just a sequence of letter as a key, for example: LEMON.
+
+WIKI - https://en.wikipedia.org/wiki/Tabula_recta#Improvements and https://en.wikipedia.org/wiki/Vigen%C3%A8re_cipher
+
+----------------------------------------------------------
+
+Beaufort cipher
+
+- Similar to the Vigenère cipher, with a slightly modified enciphering mechanism and tableau.
+- The Beaufort cipher is based on the Beaufort square which is essentially the same as a Vigenère square but in reverse order starting with the letter "Z" in the first row,[3] where the first row and the last column serve the same purpose.
+
+WIKI - https://en.wikipedia.org/wiki/Beaufort_cipher
+
+----------------------------------------------------------
+
+Autokey cipher
+
+- starts with a relatively-short keyword, the primer, and appends the message to it. For example, if the keyword is QUEENLY and the message is attack at dawn, then the key would be QUEENLYATTACKATDAWN
+
+WIKI - https://en.wikipedia.org/wiki/Autokey_cipher
+
+"""
+
+
+class Alberti(Substitution):
+    """
+    Uses a disk that has two disk stack on each other to form a disk,
+
+    1. Outer disk is Capital lettes, not moveable
+    2. Inner disk is small letters, moveable (possible to rotate)
+
+    To cipher or decipher a text, both parties—the sender and reciver agree on the key that is respect to inner disk(smaller letter),
+
+    In Alberti's original design, the Outer Disk is the Plaintext and the Inner Disk is the Ciphertext.
+
+
+    1). How to Encrypt (Outer -> Inner)
+
+    Because the outer disk represents your readable English, you always start looking there when encrypting.
+
+    1.  Align: Map the inner 'g' to the outer 'D'.(here 'g' is the key, both sender and reciver need to know, 'D' is the outer disk only specify that the 'g' map to 'D', if reciver stumble upon next new capital letter, it is time to map the 'g' with new capital letter)
+    2.  Signal: Write down 'D' in your ciphertext so the receiver knows the starting position.
+    3.  Cipher: Look for your Plaintext letter on the Outer Disk. Find the letter directly below it on the Inner Disk and write that down.
+    4.  Switch: Decide to change the key. Map inner 'g' to outer 'M'.
+    5.  Signal & Cipher: Write down 'M' in your ciphertext, and then continue looking at the Outer Disk and writing down the new matching letters from the Inner Disk.
+
+    2). How to Decrypt (Inner -> Outer)
+
+    When you receive the scrambled message, you are looking at the ciphertext, so you have to read it in reverse.
+
+    1.  Read the Signal: You see the first letter is 'D'.
+    2.  Align: You map your inner 'g' to the outer 'D'.
+    3.  Decipher: Look for the scrambled Ciphertext letter on the Inner Disk. Find the letter directly above it on the Outer Disk and write that down to reveal the plain English.
+    4.  Read the Next Signal: You hit the letter 'M' in the ciphertext.
+    5.  Switch & Decipher: You rotate your inner 'g' to the outer 'M', and continue finding the ciphertext on the Inner Disk and translating it to the Outer Disk.
+
+    """
+
+    """
+    modern_implementation: Whether to use the modern or old implementation of the cipher.
+    if moder_imlemenation = False, you should only bring plaintext as in 15th century latin alphabets, this is for the historical purposes.
+    """
+
+    def __init__(
+        self, key: str, frequency: int = 50, modern_implementation: bool = True
+    ):
+        self.key = key
+        self.frequency = frequency
+        self.disk: dict[str, str] = {}
+        self.modern_implementation = modern_implementation
+
+        if self.modern_implementation:
+            # The Modern 26-Letter English Tool
+            self.outer_disk_alphabets = string.ascii_uppercase
+            self.inner_disk_alphabets = "qwertyuiopasdfghjklzxcvbnm"
+        else:
+            # The Historical 1467 Latin Replica
+            self.outer_disk_alphabets = "ABCDEFGILMNOPQRSTVXZ1234"
+            self.inner_disk_alphabets = "gklnprtuz&xysomqihfdbace"
+
+        if self.key not in self.inner_disk_alphabets:
+            raise ValueError(f"Key '{self.key}' must be in the inner disk alphabets")
+
+    @override
+    def cipher(self, text: str, omit_non_alpha: bool = False) -> str:
+        result: str = ""
+
+        # generate intial disk
+        gen = self.generate()
+        self.disk = gen["disk"]
+        outer_key = gen["outer_key"]
+
+        result += outer_key
+        for i, char in enumerate(text.upper()):
+            if char in self.disk:
+                result += self.disk[char]
+            elif not omit_non_alpha or (char in string.whitespace):
+                result += char
+
+            # time to produce new mapping, to make it harder for cryptanalysis
+            if i > 0 and i % self.frequency == 0:
+                gen = self.generate()
+                self.disk = gen["disk"]
+                outer_key = gen["outer_key"]
+                result += outer_key
+
+        return result
+
+    @override
+    def decipher(self, text: str) -> str:
+        result: str = ""
+        for char in text:
+            # Checks if the Capital char found, if found create a disk
+            if char in self.outer_disk_alphabets:
+                self.disk = self.create_disk(outer_key=char)
+
+            # If char is small letter, it mean use the existing disk to decipher it.
+            elif char in self.inner_disk_alphabets:
+                if not self.disk:
+                    raise KeyError(
+                        "Disk not initialized because ciphertext does not start with an outer key."
+                    )
+                result += self.disk[char]
+
+            # Dont omit non-alphabet chars
+            else:
+                result += char
+
+        return result
+
+    def generate(self):
+        """
+        Generate a disk, change the outer_key to produce new disk to make the cipher harder cryptanalysis.
+        """
+        # Safely pick a random outer key without IndexErrors
+        outer_key = random.choice(self.outer_disk_alphabets)
+        disk = self.create_disk(outer_key=outer_key)
+
+        return {
+            "outer_key": outer_key,
+            "disk": disk,
+        }
+
+    def create_disk(self, outer_key: str):
+        """
+        Utility method to produce disk based on the outer_key and inner_key that is self.key
+        """
+        inner_index = self.inner_disk_alphabets.index(self.key)
+        inner_disk_alphabets = (
+            self.inner_disk_alphabets[inner_index:]
+            + self.inner_disk_alphabets[:inner_index]
+        )
+
+        outer_key_index = self.outer_disk_alphabets.index(outer_key)
+        outer_disk_alphabets = (
+            self.outer_disk_alphabets[outer_key_index:]
+            + self.outer_disk_alphabets[:outer_key_index]
+        )
+
+        disk = dict(zip(outer_disk_alphabets, inner_disk_alphabets)) | dict(
+            zip(inner_disk_alphabets, outer_disk_alphabets)
+        )
+
+        return disk
+
+    def __str__(self) -> str:
+        mode = "Modern A-Z" if self.modern_implementation else "Historical 1467"
+        return (
+            f"--- {self.__class__.__name__} Cipher ---\n"
+            f"Key: {self.key!r}\n"
+            f"Spin Freq: {self.frequency}\n"
+            f"Mode: {mode}\n"
+        )
+
+    def __repr__(self) -> str:
+        return f"AlbertiCipher(key={self.key!r}, frequency={self.frequency}, modern_implementation={self.modern_implementation})"
+
+
+class Trithemius(PolyalphabeticSubstitution):
+    def __init__(self):
+        super().__init__(key=string.ascii_uppercase)
+
+    @override
+    def decipher(self, text: str) -> str:
+        result: str = ""
+        key_cycle = cycle(self._get_key_sequence())
+
+        for text_char in text.upper():
+            if text_char.isalpha():
+                key_char = next(key_cycle)
+                column = (ord(text_char) - 65) - key_char
+                result += self.tabula_recta[0][column]
+            else:
+                result += text_char
+        return result
+
+    @override
+    def __str__(self) -> str:
+        return f"{self.__class__.__name__}\n"
+
+    @override
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}()"
+
+
+class Vigenere(PolyalphabeticSubstitution):
+    def __init__(self, key: str):
+        super().__init__(key)
+
+
+class Beaufort(PolyalphabeticSubstitution):
+    def __init__(self, key: str):
+        super().__init__(key)
+
+    @override
+    def _generate_table(self) -> list[list[str]]:
+        """Create a square table of alphabets for beaufort cipher, as it uses it own table implmentation."""
+        tabula_recta: list[list[str]] = []
+        for i in range(26):
+            tabula_recta.append(
+                list(string.ascii_uppercase[i::-1] + string.ascii_uppercase[:i:-1])
+            )
+        return tabula_recta
+
+    @override
+    def decipher(self, text: str) -> str:
+        # self-reciprocal
+        return self.cipher(text)
+
+
+class Autokey(PolyalphabeticSubstitution):
+    def __init__(self, key: str):
+        super().__init__(key)
+
+    @override
+    def cipher(self, text: str, omit_non_alpha: bool = False) -> str:
+        result: str = ""
+        # We start with our primer (e.g., the shifts for 'LEMON')
+        key_sequence = self._get_key_sequence()
+        key_index = 0
+
+        for char in text.upper():
+            if char.isalpha():
+                # 1. Grab the current shift from our growing list
+                current_key_shift = key_sequence[key_index]
+
+                # 2. Encrypt the letter using the base class table
+                column = ord(char) - 65
+                result += self.tabula_recta[current_key_shift][column]
+
+                # 3. Append the PLAINTEXT letter to our key sequence!
+                key_sequence.append(column)
+                key_index += 1
+
+            elif not omit_non_alpha or (char in string.whitespace):
+                result += char
+
+        return result
+
+    @override
+    def decipher(self, text: str) -> str:
+        result: str = ""
+        # The receiver only starts with the primer ('LEMON')
+        key_sequence = self._get_key_sequence()
+        key_index = 0
+
+        for text_char in text.upper():
+            if text_char.isalpha():
+                # 1. Grab the current shift
+                current_key_shift = key_sequence[key_index]
+
+                # 2. Decrypt the ciphertext back to the original letter
+                column = self.tabula_recta[current_key_shift].index(text_char)
+                decrypted_char = self.tabula_recta[0][column]
+                result += decrypted_char
+
+                # 3. Append the DECRYPTED letter to our key sequence
+                # so we can use it to decrypt future letters!
+                key_sequence.append(column)
+                key_index += 1
+            else:
+                result += text_char
+
+        return result

retro_ciphers-1.0.0/tests/test_polyalphabetic_cipher.py

@@ -0,0 +1,122 @@
+import pytest
+from src.retro_ciphers.poly import (
+    PolyalphabeticSubstitution, Alberti, Trithemius,
+    Vigenere, Beaufort, Autokey
+)
+
+class TestPolyalphabeticSubstitution:
+    def test_empty_key(self):
+        with pytest.raises(ValueError, match="Key must not be empty."):
+            PolyalphabeticSubstitution("")
+            
+    def test_invalid_key(self):
+        with pytest.raises(ValueError, match="Key must contain at least one letter."):
+            Vigenere("123")
+
+    def test_generate_table(self):
+        # We need a dummy subclass since PolyalphabeticSubstitution cannot be initialized without a concrete cipher
+        # Wait, the base class can be initialized, it doesn't have abstract subclass barriers in python automatically unless ABC is used
+        cipher = PolyalphabeticSubstitution("KEY")
+        table = cipher._generate_table()
+        assert len(table) == 26
+        # Check first row is normal alphabet
+        assert "".join(table[0]) == "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+        # Check second row is shifted by 1
+        assert "".join(table[1]) == "BCDEFGHIJKLMNOPQRSTUVWXYZA"
+        # Check all rows have 26 cols
+        assert all(len(row) == 26 for row in table)
+
+class TestAlbertiCipher:
+    def test_invalid_key_initialization(self):
+        with pytest.raises(ValueError, match="must be in the inner disk alphabets"):
+            Alberti("A")  # 'A' is in outer disk, not inner disk
+
+    def test_crashing_uninitialized_decipher(self):
+        # By default, modern_implementation=True, so "a" is valid inner disk
+        cipher = Alberti("a")
+        # 'h' is in inner disk. Attempting to decipher without outer disk char first raises KeyError.
+        with pytest.raises(KeyError, match="Disk not initialized"):
+            cipher.decipher("hello")
+            
+    def test_missing_characters(self):
+        cipher = Alberti("a")
+        text = "HELLO WORLD ZEBRA! @#"
+        enc = cipher.cipher(text)
+        # H and W are not in the outer disk alphabets!
+        # They get dropped silently into the output, preserving them
+        dec = cipher.decipher(enc)
+        assert dec == text
+
+    def test_frequency_rotation(self):
+        cipher = Alberti("a", frequency=2)
+        # Text with spaces to trigger frequency rotation
+        text = "A B C D E F"
+        enc = cipher.cipher(text)
+        dec = cipher.decipher(enc)
+        assert dec == text
+
+    def test_historical_mode(self):
+        # In historical mode, inner disk is "gklnprtuz&xysomqihfdbace", 'a' is valid
+        cipher = Alberti("a", modern_implementation=False)
+        text = "ABCDEFGHI"
+        enc = cipher.cipher(text)
+        dec = cipher.decipher(enc)
+        assert dec == text
+
+    def test_historical_invalid_key(self):
+        with pytest.raises(ValueError, match="must be in the inner disk alphabets"):
+            Alberti("w", modern_implementation=False) # w is not in historical inner disk
+
+class TestVigenereCipher:
+    def test_basic_cipher(self):
+        cipher = Vigenere("LEMON")
+        text = "ATTACKATDAWN"
+        enc = cipher.cipher(text)
+        dec = cipher.decipher(enc)
+        assert dec == text
+
+    def test_non_alpha_characters(self):
+        cipher = Vigenere("LEMON")
+        text = "ATTACK AT DAWN!"
+        enc = cipher.cipher(text)
+        dec = cipher.decipher(enc)
+        assert dec == text
+
+    def test_long_mixed_case(self):
+        cipher = Vigenere("SeCrEt")
+        # Mixed cases are converted to uppercase internally by the cipher/decipher logic
+        text = "This is a really long text with mixed CASES and symbols 123 !@#"
+        enc = cipher.cipher(text)
+        dec = cipher.decipher(enc)
+        assert dec == text.upper()
+
+class TestTrithemiusCipher:
+    def test_basic_cipher(self):
+        cipher = Trithemius()
+        text = "HELLO WORLD"
+        enc = cipher.cipher(text)
+        dec = cipher.decipher(enc)
+        assert dec == text
+
+class TestBeaufortCipher:
+    def test_basic_cipher(self):
+        cipher = Beaufort("FORTIFICATION")
+        text = "DEFENDTHEEASTWALLOFTHECASTLE"
+        enc = cipher.cipher(text)
+        dec = cipher.decipher(enc)
+        assert dec == text
+
+class TestAutokeyCipher:
+    def test_basic_cipher(self):
+        cipher = Autokey("QUEENLY")
+        text = "ATTACKATDAWN"
+        enc = cipher.cipher(text)
+        dec = cipher.decipher(enc)
+        assert dec == text
+
+    def test_punctuation_continuity(self):
+        cipher = Autokey("KEY")
+        text = "HELLO, WORLD!"
+        enc = cipher.cipher(text)
+        dec = cipher.decipher(enc)
+        assert dec == text.upper()

retro_ciphers-1.0.0/tests/test_substitution_cipher.py

@@ -0,0 +1,116 @@
+
+import pytest
+
+from src.retro_ciphers.mono import (
+    Atbash,
+    Shift,
+    Caesar,
+    Rot13,
+    MixedAlphabet,
+    SimpleSubstitution,
+    Baconian,
+    PolybiusSquare,
+)
+
+def test_atbash():
+    cipher = Atbash()
+    assert cipher.cipher("A") == "Z"
+    assert cipher.cipher("a") == "z"
+    assert cipher.cipher("Hello World!") == "Svool Dliow!"
+    assert cipher.decipher("Svool Dliow!") == "Hello World!"
+
+def test_shift():
+    cipher = Shift(1)
+    assert cipher.cipher("abc") == "bcd"
+    assert cipher.cipher("Z") == "A"
+    assert cipher.decipher("bcd") == "abc"
+
+    # Test shift larger than 26
+    cipher_wrap = Shift(27)
+    assert cipher_wrap.cipher("abc") == "bcd"
+
+def test_caesar():
+    cipher = Caesar()
+    assert cipher.cipher("aBc") == "dEf"
+    assert cipher.decipher("dEf") == "aBc"
+
+def test_rot13():
+    cipher = Rot13()
+    assert cipher.cipher("Hello!") == "Uryyb!"
+    assert cipher.decipher("Uryyb!") == "Hello!"
+
+def test_mixed_alphabet():
+    cipher = MixedAlphabet("ZEBRA")
+    # ZEBRAcdfghijklmnopqstuvwxy
+    # a->Z, b->E, c->B, d->R, e->A, f->c
+    assert cipher.cipher("abcde") == "zebra"
+    assert cipher.decipher("zebra") == "abcde"
+
+    # Test keyword normalization (ignoring non-alpha, handling upper/lower cases)
+    cipher2 = MixedAlphabet("Zz !eE bB Rr Aa!")
+    assert cipher2.cipher("abcde") == "zebra"
+    assert cipher2.decipher("zebra") == "abcde"
+
+def test_simple_substitution():
+    alphabet = "zyxwvutsrqponmlkjihgfedcba" # reversed
+    cipher = SimpleSubstitution(alphabet)
+    assert cipher.cipher("abc") == "zyx"
+    assert cipher.decipher("zyx") == "abc"
+
+    # Unique check
+    with pytest.raises(ValueError):
+        SimpleSubstitution("A" * 26)
+
+    # Length check
+    with pytest.raises(ValueError):
+        SimpleSubstitution("abc")
+
+    # Symbols allowed in cipher alphabet (casing might fail to preserve for decipher)
+    symbol_alphabet = "!@#$%^&*()_+{}|:\"<>?-=[]\\;',./"[:26]
+    cipher_sym = SimpleSubstitution(symbol_alphabet)
+    assert cipher_sym.cipher("a") == "!"
+
+    # Random generation
+    random_alphabet = SimpleSubstitution.generate_cipher_alphabet()
+    assert len(set(random_alphabet)) == 26
+    assert len(random_alphabet) == 26
+
+def test_baconian_modern():
+    cipher = Baconian(modern_implementation=True)
+    # H -> AABBB, e -> aabaa, l -> ababb, l -> ababb, o -> abbba
+    assert cipher.cipher("Hello") == "AABBBaabaaababbababbabbba"
+    assert cipher.decipher("AABBBaabaaababbababbabbba") == "Hello"
+
+    assert cipher.cipher("a B") == "aaaaa AAAAB"
+    assert cipher.decipher("aaaaa AAAAB") == "a B"
+
+    # Edge cases
+    assert cipher.decipher("aa!aa") == "aa!aa"     # incomplete blocks fall back
+    assert cipher.decipher("aaaaab") == "ab"       # remaining "b" falls back as is
+
+def test_baconian_classic():
+    cipher = Baconian(modern_implementation=False)
+    # I and J are both abaaa.
+    assert cipher.cipher("I") == "ABAAA"
+    assert cipher.cipher("J") == "ABAAA"
+    # Decipher defaults to 'J' or 'I' because it's mapping the same token. 
+    # With dictionary iteration either might be last, but it maps consistently.
+    deciphered_I = cipher.decipher("ABAAA").upper()
+    assert deciphered_I in ["I", "J"]
+
+def test_polybius_square():
+    cipher = PolybiusSquare()
+    assert cipher.cipher("aB") == "1112"
+    assert cipher.decipher("1112") == "AB" # Polybius deciphers to uppercase
+    assert cipher.cipher("I") == "24"
+    assert cipher.cipher("J") == "24"
+    assert cipher.decipher("24").upper() in ["I", "J"]
+    
+    # Test non-alphabetic/non-numeric correctly falls back
+    assert cipher.cipher("a1") == "111"
+    
+    deciphered_spaced = cipher.decipher("11 24")
+    assert deciphered_spaced == "A I" or deciphered_spaced == "A J"
+
+    # Odd length fallback
+    assert cipher.decipher("111") == "A1"