Added codec: bifid

Author: dhondta

README.md

@@ -337,6 +337,7 @@ This category also contains `ascii85`, `adobe`, `[x]btoa`, `zeromq` with the `ba
 - [X] `barbie-N`: aka Barbie Typewriter (*N* belongs to [1, 4])
 - [X] `bazeries`: aka Bazeries Cipher (two Polybius grids and a transposition keyed by a number)
 - [X] `beaufort`: aka Beaufort Cipher (variant of Vigenere Cipher)
+- [X] `bifid`: aka Bifid Cipher (Delastelle's fractionation with a 5x5 Polybius square) ; `trifid` for its 3x3x3 cube variant
 - [X] `citrix`: aka Citrix CTX1 password encoding
 - [X] `playfair`: aka Playfair Cipher
 - [X] `phillips`: aka Phillips Cipher (polyalphabetic block cipher with 8 key squares)

docs/pages/enc/crypto.md

@@ -194,6 +194,32 @@ This is a variant of the [Vigenere Cipher](#vigenere-cipher). There is no defaul
 
 -----
 
+### Bifid/Trifid Cipher
+
+These ciphers were invented by Felix Delastelle. Each letter is replaced by its coordinates in a 5x5 Polybius square (Bifid) or in a 3x3x3 cube (Trifid). Within each block of letters, whose size is the period (the whole text by default), the coordinates are written in rows (all the rows, then all the columns, ...), then read again as groups of coordinates that give the new letters. The square or cube is filled with an optional keyword (without duplicates), then with the remaining characters of the alphabet.
+
+**Codec** | **Conversions** | **Aliases** | **Comment**
+:---: | :---: | --- | ---
+`bifid` | text <-> Bifid ciphertext | `bifid-keyword`, `bifid_cipher-keyword-5`, `bifid-7`, ... | 5x5 square ; `J` is normalized to `I` ; other characters and the case are kept
+`trifid` | text <-> Trifid ciphertext | `trifid-keyword`, `trifid_cipher-keyword-5`, `trifid-7`, ... | 3x3x3 cube with the 26 letters and `+` ; other characters are kept ; uppercase output (a letter can be substituted by `+`)
+
+The codec name holds the optional keyword, then the optional period. The period only counts the letters of the alphabet.
+
+```python
+>>> codext.encode("FLEEATONCE", "bifid-bgwkzqpndsioaxefclumthyvr")
+'UAEOLWRINS'
+>>> codext.encode("Flee at once!", "bifid-bgwkzqpndsioaxefclumthyvr")
+'Uaeo lw rins!'
+>>> codext.decode("UAEOLWRINS", "bifid-bgwkzqpndsioaxefclumthyvr")
+'FLEEATONCE'
+>>> codext.encode("aide-toi, le ciel t'aidera", "trifid-felixmariedelastelle-5")
+"FMJF-VOI, SS UFTF P'UFEQQC"
+>>> codext.decode("FMJFVOISSUFTFPUFEQQC", "trifid-felixmariedelastelle-5")
+'AIDETOILECIELTAIDERA'
+```
+
+-----
+
 ### Citrix CTX1
 
 This implements the Citrix CTX1 password encoding algorithm.

src/codext/crypto/__init__.py

@@ -5,6 +5,7 @@
 from .bacon import *
 from .barbie import *
 from .bazeries import *
+from .bifid import *
 from .citrix import *
 from .playfair import *
 from .phillips import *

src/codext/crypto/bifid.py

@@ -0,0 +1,87 @@
+# -*- coding: UTF-8 -*-
+"""Bifid/Trifid Cipher Codec - bifid/trifid content encoding.
+
+The Bifid and Trifid ciphers were invented by Felix Delastelle. Each letter is replaced by its coordinates in a 5x5
+ Polybius square (Bifid ; I and J sharing a cell) or in a 3x3x3 cube (Trifid ; 26 letters and "+"). Within each block of
+ letters (whose size is the period, the whole text by default), the coordinates are written in rows (all the rows, then
+ all the columns, ...), then read again as groups of coordinates that give the new letters. The square or cube is
+ filled with an optional keyword (without duplicates), then with the remaining characters of the alphabet.
+
+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)
+
+Reference: https://en.wikipedia.org/wiki/Bifid_cipher
+           https://en.wikipedia.org/wiki/Trifid_cipher
+"""
+from string import ascii_uppercase as UC
+
+from ..__common__ import *
+
+
+__examples1__ = {
+    'enc(bifid-bgwkzqpndsioaxefclumthyvr)':   {'FLEEATONCE': "UAEOLWRINS", 'Flee at once!': "Uaeo lw rins!"},
+    'dec(bifid_cipher-bgwkzqpndsioaxefclumthyvr)': {'UAEOLWRINS': "FLEEATONCE"},
+    'enc(bifid)':                             {'TEST': "QTUO", 'Jump': "Inuk"},
+    'enc-dec(bifid|bifid-keyword|bifid-keyword-5|bifid-7|bifid-0)': ["", "Hello, World!", "Test 1234!",
+                                                                     "Delastelle's ciphers"],
+}
+__examples2__ = {
+    'enc(trifid-felixmariedelastelle-5)':     {'AIDETOILECIELTAIDERA': "FMJFVOISSUFTFPUFEQQC",
+                                               "aide-toi, le ciel t'aidera": "FMJF-VOI, SS UFTF P'UFEQQC"},
+    'dec(trifid_cipher-felixmariedelastelle-5)': {'FMJFVOISSUFTFPUFEQQC': "AIDETOILECIELTAIDERA"},
+    'enc(trifid)':                            {'TEST': "UTBK"},
+    'enc-dec(trifid|trifid-keyword|trifid-keyword-5|trifid-7|trifid-0)': ["", "HELLO, WORLD!", "JUMP + 42"],
+}
+__guess1__, __guess2__ = ["bifid"], ["trifid"]
+
+
+# cipher: (alphabet, base of the coordinates, number of coordinates per letter)
+_PARAMS = {'bifid': (UC.replace("J", ""), 5, 2), 'trifid': (UC + "+", 3, 3)}
+
+
+def __fractionation(name, decode=False):
+    alphabet, base, n = _PARAMS[name]
+    def _wrapper(key=None, period=None):
+        key, square = str(key or "").upper(), []
+        for c in (key.replace("J", "I") if name == "bifid" else key) + alphabet:
+            if c in alphabet and c not in square:
+                square.append(c)
+        coords = {c: tuple(i // base ** (n - 1 - k) % base for k in range(n)) for i, c in enumerate(square)}
+        letters = {v: c for c, v in coords.items()}
+        period = int(str(period or 0))
+        def _code(text, errors="strict"):
+            text = ensure_str(text)
+            # only letters of the alphabet are fractionated ; other characters are kept in place
+            slots, chars = [], []
+            for i, c in enumerate(text):
+                if (u := c.upper()) == "J" and name == "bifid":
+                    u = "I"
+                if u in coords:
+                    slots.append(i)
+                    chars.append(u)
+            result, size = [], period or len(chars) or 1
+            for b in range(0, len(chars), size):
+                block = chars[b:b+size]
+                if decode:
+                    # the coordinates of the block, written in a row, hold the rows of the encoding matrix one by one
+                    digits, l = [d for c in block for d in coords[c]], len(block)
+                    result += [letters[tuple(digits[k*l+j] for k in range(n))] for j in range(l)]
+                else:
+                    digits = [coords[c][k] for k in range(n) for c in block]
+                    result += [letters[tuple(digits[j:j+n])] for j in range(0, len(digits), n)]
+            r = list(text)
+            for pos, c in zip(slots, result):
+                # with Trifid, a letter may be substituted by "+", which cannot hold its case ; hence, uppercase
+                r[pos] = c.lower() if name == "bifid" and text[pos].islower() else c
+            return (s := "".join(r)), len(s)
+        return _code
+    return _wrapper
+
+
+for _name, _ex, _gs in [("bifid", __examples1__, __guess1__), ("trifid", __examples2__, __guess2__)]:
+    add(_name, __fractionation(_name), __fractionation(_name, True),
+        rf"^{_name}(?:[-_]cipher)?(?:[-_]([a-zA-Z]+))?(?:[-_](\d+))?$",
+        examples=_ex, guess=_gs, printables_rate=1., penalty=.1)