Added new codec: polybius

Author: dhondta

README.md

@@ -285,7 +285,8 @@ This category also contains `ascii85`, `adobe`, `[x]btoa`, `zeromq` with the `ba
 - [X] `bacon`: aka Baconian Cipher
 - [X] `barbie-N`: aka Barbie Typewriter (*N* belongs to [1, 4])
 - [X] `citrix`: aka Citrix CTX1 password encoding
-- [X] `railfence`: aka Rail Fence Cipher 
+- [X] `polybius`: aka Polybius Square Cipher
+- [X] `railfence`: aka Rail Fence Cipher
 - [X] `rotN`: aka Caesar cipher (*N* belongs to [1,25])
 - [X] `scytaleN`: encrypts using the number of letters on the rod (*N* belongs to [1,[)
 - [X] `shiftN`: shift ordinals (*N* belongs to [1,255])

docs/pages/enc/crypto.md

@@ -126,6 +126,25 @@ This implements the Citrix CTX1 password encoding algorithm.
 
 -----
 
+### Polybius Square Cipher
+
+This implements the well-known Polybius Square cipher, using the square with the alphabet in normal order as the default. It can be used dynamically with a custom alphabet.
+
+**Codec** | **Conversions** | **Aliases** | **Comment**
+:---: | :---: | --- | ---
+`polybius` | text <-> polybius square ciphertext | `polybius-square`, `polybius_BACDEFGHIKLMNOPQRSTUVWXYZ`, ... |
+
+```python
+>>> codext.encode("this is a test", "polybius")
+'44232443 2443 11 44154344'
+>>> codext.encode("this is a test", "polybius_BACDEFGHIKLMNOPQRSTUVWXYZ")
+'44232443 2443 12 44154344'
+>>> codext.decode("44232443 2443 11 441543445", "polybius-square", errors="replace")
+'THIS IS A TEST?'
+```
+
+-----
+
 ### Rail Fence Cipher
 
 This implements the Rail Fence encoding algorithm, using 3 rails and offset 0 as the default parameters. The encoding fence is built from the top ; the `up` flag can be used to build the fence from the bottom. Note that trying parameters that do not fit the input length will trigger a `ValueError` mentioning the bad value.

src/codext/crypto/__init__.py

@@ -4,6 +4,7 @@
 from .bacon import *
 from .barbie import *
 from .citrix import *
+from .polybius import *
 from .railfence import *
 from .rot import *
 from .scytale import *

src/codext/crypto/polybius.py

@@ -0,0 +1,77 @@
+# -*- coding: UTF-8 -*-
+"""Polybius Square Codec - polybius-square content encoding.
+
+This codec:
+- en/decodes strings from str to str
+- en/decodes strings from bytes to bytes
+- decodes file content to str (read)
+- encodes file content from str to bytes (write)
+"""
+from ..__common__ import *
+
+
+__examples__ = {
+    'enc(polybius|polybius-square|polybius_square)': {'this is a test': "44232443 2443 11 44154344"},
+    'enc(polybius-ABCDEFGHIKLMNOPQRSTUVWXYZ)':       {'this is a test': "44232443 2443 11 44154344"},
+    'dec(polybius)':                                 {'44232443 2443 11 44154344': "THIS IS A TEST"},
+}
+__guess__ = ["polybius"]
+
+
+# Standard 5×5 Polybius square (I and J share the same cell):
+#      1  2  3  4  5
+# 1    A  B  C  D  E
+# 2    F  G  H  I  K
+# 3    L  M  N  O  P
+# 4    Q  R  S  T  U
+# 5    V  W  X  Y  Z
+_DEFAULT_ALPHABET = "ABCDEFGHIKLMNOPQRSTUVWXYZ"
+
+
+def __make_maps(alphabet):
+    """ Build the encoding and decoding maps for the given 25-character alphabet. """
+    alph = alphabet.upper() if alphabet else _DEFAULT_ALPHABET
+    if len(alph) != 25 or len(set(alph)) != 25:
+        raise LookupError("Polybius square requires exactly 25 distinct characters; "
+                          f"got {len(alph)} character(s) with {len(set(alph))} unique: {alph}")
+    encmap = {alph[i]: str(i // 5 + 1) + str(i % 5 + 1) for i in range(25)}
+    decmap = {v: k for k, v in encmap.items()}
+    if 'J' not in encmap and 'I' in encmap:
+        encmap['J'] = encmap['I']
+    encmap[' '] = ' '
+    return encmap, decmap
+
+
+def polybius_encode(alphabet=_DEFAULT_ALPHABET):
+    encmap, _ = __make_maps(alphabet)
+    def encode(text, errors="strict"):
+        _h = handle_error("polybius", errors)
+        r = ""
+        for pos, c in enumerate(ensure_str(text).upper()):
+            r += encmap[c] if c in encmap else _h(c, pos, r)
+        return r, len(text)
+    return encode
+
+
+def polybius_decode(alphabet=_DEFAULT_ALPHABET):
+    _, decmap = __make_maps(alphabet)
+    def decode(text, errors="strict"):
+        _h = handle_error("polybius", errors, decode=True)
+        r, t, i = "", ensure_str(text), 0
+        while i < len(t):
+            if t[i] == " ":
+                r += " "
+                i += 1
+            elif i + 1 < len(t):
+                r += decmap.get(t[i:i+2]) or _h(t[i:i+2], i, r)
+                i += 2
+            else:
+                r += _h(t[i], i, r)
+                i += 1
+        return r, len(t)
+    return decode
+
+
+add("polybius", polybius_encode, polybius_decode, r"^polybius(?:[-_]square)?(?:[-_]([A-Za-z]{25}))?$",
+    printables_rate=1., expansion_factor=(1.7, .3))
+

tests/test_manual.py

@@ -8,12 +8,11 @@
 from unittest import TestCase
 
 from codext.__common__ import *
-from codext.binary.baudot import _check_alphabet
-from codext.checksums.crc import CRC
 
 
 class ComplementaryTestCase(TestCase):
     def test_codec_baudot(self):
+        from codext.binary.baudot import _check_alphabet
         self.assertRaises(ValueError, _check_alphabet, ["BAD_ALPHABET"])
 
     def test_codec_dna(self):
@@ -23,6 +22,13 @@ def test_codec_dna(self):
     def test_codec_morse(self):
         self.assertRaises(LookupError, codecs.encode, "test", "morse-AAB")
 
+    def test_codec_polybius(self):
+        from codext.crypto.polybius import polybius_encode, polybius_decode
+        self.assertRaises(LookupError, polybius_encode, "ABC")
+        self.assertRaises(ValueError, polybius_decode(), "BAD_")
+        self.assertRaises(ValueError, polybius_decode(), "441543441")
+        self.assertEqual(codecs.decode("441543445", "polybius", "ignore"), "TEST")
+    
     def test_codec_sms(self):
         self.assertEqual(codecs.decode("A-B-222-3-4-5", "sms", "leave"), "ABcdgj")
 
@@ -103,6 +109,7 @@ def test_codec_dummy_str_manips(self):
         self.assertRaises(LookupError, codecs.encode, STR, "tokenize-200")
 
     def test_codec_hash_functions(self):
+        from codext.checksums.crc import CRC
         STR = b"This is a test string!"
         for h in ["adler32", "md2", "md5", "sha1", "sha224", "sha256", "sha384", "sha512"]:
             self.assertIsNotNone(codecs.encode(STR, h))