enigma-m4 0.4.0

A modern, fully tested Enigma machine simulator in Python.

🔐 Enigma Machine Simulator (M3 → M4)

A clean, modular, historically accurate simulation of the German Enigma M3 and Kriegsmarine M4 cipher machines — implemented in modern Python, with full test coverage and historically faithful mechanics.

This project emphasizes:

• correctness
• mechanical fidelity
• clean architecture
• testability
• extensibility

It is both a learning tool and a professional portfolio project demonstrating engineering discipline and historical accuracy.

📚 Documentation

• User Manual - Complete guide for using the simulator
• API Reference - Detailed API documentation

🚀 Quick Start

from enigma.core.machine import EnigmaMachine
from enigma.core.rotor import Rotor
from enigma.core.reflector import Reflector
from enigma.core.plugboard import Plugboard
from enigma.data.rotors import ROTOR_I, ROTOR_II, ROTOR_III
from enigma.data.reflectors import REFLECTOR_B

# Create components
rotors = [
    Rotor(*ROTOR_I, position="A"),
    Rotor(*ROTOR_II, position="A"),
    Rotor(*ROTOR_III, position="A")
]
reflector = Reflector(REFLECTOR_B)
plugboard = Plugboard()

# Create machine and encrypt
machine = EnigmaMachine(rotors, reflector, plugboard)
encrypted = machine.encode_letter("H")

📦 Installation

Install from PyPI:

pip install enigma-m4

Or install from source:

git clone https://github.com/wrogistefan/enigma_m4.git
cd enigma_m4
pip install -e .

---

✨ Features

🧠 Core Capabilities

• Full M3 support (rotors I–VIII, reflectors A/B/C)
• Full M4 support (III–II–I + Greek rotor)
• Greek rotors: Beta, Gamma
• Thin reflectors: Thin B, Thin C
• Historically accurate stepping and double‑stepping
• Ring settings (Ringstellung)
• Rotor positions (Grundstellung)
• Plugboard (Steckerbrett) with validation
• Full reversibility (Enigma property)

🔌 Historical Plugboard

Supports all historically used formats:

{"A": "B"}                     # dict
[("A", "B"), ("C", "D")]       # list of pairs
"PO ML IU KZ"                  # Kriegsmarine format
"A-B C-D"                      # dash format

Up to 10 pairs, matching real Enigma constraints.

---

🧩 Architecture Overview

The machine is composed of independent, testable components:

Plugboard
   ↓
Right Rotor → Middle Rotor → Left Rotor → Greek Rotor (M4)
   ↓             ↓              ↓             ↓
                     Reflector
   ↑             ↑              ↑             ↑
Right Rotor ← Middle Rotor ← Left Rotor ← Greek Rotor
   ↑
Plugboard

🔧 Components

🔌 Plugboard

• Bidirectional letter swapping
• Full validation
• Historical 10‑pair limit
• API: swap(char)

⚙ Rotors

• Forward & backward signal path
• Ring setting
• Rotor position
• Notch logic
• step() rotation
• Includes:
  • I, II, III, IV, V
  • VI, VII, VIII (Kriegsmarine)
  • Beta, Gamma (M4 static rotors)

🪞 Reflectors

• Involutive mapping
• No fixed points
• Includes:
  • A, B, C
  • Thin B, Thin C (M4)

🖥 EnigmaMachine

• Correct stepping logic (M3 + M4)
• Double‑stepping implemented
• Full signal path implemented
• Plugboard integration
• Reversible encryption

---

📁 Project Structure

enigma_m4/
├── pyproject.toml
├── README.md
├── LICENSE
├── docs/
│   ├── USER_MANUAL.md
│   └── API_REFERENCE.md
├── src/
│   └── enigma/
│       ├── __init__.py
│       ├── core/
│       │   ├── __init__.py
│       │   ├── rotor.py
│       │   ├── reflector.py
│       │   ├── plugboard.py
│       │   └── machine.py
│       ├── data/
│       │   ├── __init__.py
│       │   ├── rotors.py
│       │   └── reflectors.py
│       └── utils/
│           ├── __init__.py
│           ├── cli/
│           │   ├── __init__.py
│           │   └── main.py
│           └── gui/
│               ├── __init__.py
│               └── app.py
└── tests/
    ├── __init__.py
    ├── test_rotor.py
    ├── test_reflector.py
    ├── test_plugboard.py
    ├── test_machine.py
    ├── test_rotors.py
    ├── test_reflectors.py
    ├── test_integration.py
    ├── test_integration_m4.py
    ├── test_integration_m4_historical.py
    └── test_plugboard.py

---

📖 Documentation

For detailed usage instructions and API reference:

• 📋 User Manual - Complete guide including installation, configuration, and examples
• 🔧 API Reference - Detailed documentation of all classes and methods

---

🧪 Testing

Run all tests:

pytest -q

The test suite includes:

• unit tests for rotors, reflectors, plugboard
• M3 integration tests
• M4 integration tests
• historical canonical tests:
  • Beta + Thin B → A → B
  • Gamma + Thin C → A → P
• reversibility tests
• ring setting tests
• plugboard tests
• Kriegsmarine‑style configuration tests

---

🗺 Roadmap

✅ Completed (v0.4.0)

• Full M3 implementation
• Full M4 implementation
• Greek rotors (Beta/Gamma)
• Thin reflectors (Thin B/C)
• Historical plugboard formats
• Full stepping logic
• Comprehensive test suite

🔜 Next

• Add historical daily key sheets
• Add real U‑boat message examples
• Add CLI interface
• Add web demo
• Add visualization of rotor stepping

---

📜 License

This project is licensed under the MIT License.

---

👤 About the Author

Łukasz Perek — Python developer focused on clean architecture, cryptography, and historically inspired engineering.

Based in Syracuse, Sicily, transitioning into full‑time software engineering and AI‑driven development.

Specializes in:

• Python (OOP, CLI tools, packaging, testing)
• Clean, modular architecture
• Cryptographic systems & historical computing
• CI/CD (GitHub Actions, linting, coverage)
• Documentation & developer experience

This Enigma simulator is part of his public portfolio — a demonstration of engineering discipline, historical accuracy, and modern Python design.

If you find this project interesting or useful, feel free to ⭐ the repository.

---

🔗 Connect