Metadata-Version: 2.4
Name: enigma-m4
Version: 0.4.0
Summary: A modern, fully tested Enigma machine simulator in Python.
Author: Łukasz Perek
License: MIT License
        
        Copyright (c) 2025 Łukasz Perek
        
        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.
        
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

![Python](https://img.shields.io/badge/Python-3.12-blue)
![Tests](https://img.shields.io/badge/Tests-passing-brightgreen)
![License](https://img.shields.io/badge/License-MIT-yellow)
[![codecov](https://codecov.io/gh/wrogistefan/enigma_m4/branch/main/graph/badge.svg)](https://codecov.io/gh/wrogistefan/enigma_m4)

# 🔐 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](docs/USER_MANUAL.md)** - Complete guide for using the simulator
- **[API Reference](docs/API_REFERENCE.md)** - Detailed API documentation

## 🚀 Quick Start

```python
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:

```bash
pip install enigma-m4
```

Or install from source:

```bash
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:

```python
{"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](docs/USER_MANUAL.md)** - Complete guide including installation, configuration, and examples
- **[🔧 API Reference](docs/API_REFERENCE.md)** - 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](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

[![GitHub](https://img.shields.io/badge/GitHub-Profile-black?logo=github)](https://github.com/wrogistefan)
[![LinkedIn](https://img.shields.io/badge/LinkedIn-Profile-blue?logo=linkedin)](https://www.linkedin.com/in/lukaszperek)
