Spiral Cipher Documentation

The Spiral Cipher is a Python package for text encryption and decryption using a spiral pattern. It writes text in a spiral pattern within a square matrix and reads it back row by row for encoding. The reverse process is used for decoding. The package also supports file-based encryption/decryption and customizable encryption keys.

---

Features

• Text Encryption/Decryption: Encrypt and decrypt text using a spiral pattern.
• File Encryption/Decryption: Encrypt and decrypt files.
• Customizable Key: Use a key to shift characters for additional security.
• UTF-8 Support: Works with Unicode characters.
• Command-Line Interface (CLI): Easy-to-use CLI for text and file operations.
• Python API: Programmatic access to encryption/decryption functions.

---

Installation

Install the package using pip:

pip install spiral-cipher

---

Usage

Python API

The package provides a Python API for programmatic usage.

1. Encoding and Decoding Text

from spiral_cipher import encode, decode

# Encode text
encoded_text = encode("Hello, World!", key=1111) # any key : int , ex : 9999999
print(encoded_text)  # Output: "AxeeQQQhew!,khP"

# Decode text
decoded_text = decode(encoded_text, key=1111)
print(decoded_text)  # Output: "Hello, World!"

2. Using the SpiralCipher Class

from spiral_cipher import SpiralCipher

# Initialize the cipher with a key
cipher = SpiralCipher(key=3)

# Encode text
encoded_text = cipher.encode("Hello, World!")
print(encoded_text)  # Output: "KhooAAArog!,urZ"

# Decode text
decoded_text = cipher.decode(encoded_text)
print(decoded_text)  # Output: "Hello, World!"

# Encrypt a file
cipher.encrypt_file("input.txt", "encrypted.txt")

# Decrypt a file
cipher.decrypt_file("encrypted.txt", "decrypted.txt")

---

Command-Line Interface (CLI)

The package provides a CLI for easy text and file processing.

1. Text Processing

# Encode text
spiral-cipher encode "Hello, World!" -k 3

# Decode text
spiral-cipher decode "KhooAAArog!,urZ " -k 3 #don't miss space +_+

2. File Processing

# Encrypt a file
spiral-cipher encode input.txt -f -o encrypted.txt -k 3

# Decrypt a file
spiral-cipher decode encrypted.txt -f -o decrypted.txt -k 3

3. CLI Options

Argument	Description
action	Action to perform (encode or decode)
input	Text to process or input file path
-k, --key	Encryption key (default: 1)
-f, --file	Treat input as a file path
-o, --output	Output file path (required for file operations)
-h, --help	Show help message

---

How It Works

Encryption Process

1. Create a Square Matrix:

   • The input text is padded (if necessary) to fit into the smallest square matrix.

2. Write Text in Spiral Pattern:

   • The text is written in a spiral pattern (clockwise or counterclockwise) within the matrix.

3. Shift Characters:

   • Each character is shifted by the key value for additional security.

4. Read Row by Row:

   • The matrix is read row by row to generate the encrypted text.

Decryption Process

1. Create a Square Matrix:

   • The encrypted text is placed into a square matrix.

2. Read Text in Spiral Pattern:

   • The text is read in the reverse spiral pattern.

3. Unshift Characters:

   • Each character is unshifted by the key value.

4. Remove Padding:

   • Padding characters are removed to retrieve the original text.

---

Examples

Example 1: Encoding and Decoding Text

from spiral_cipher import encode, decode

# Encode text
encoded = encode("Hello, World!", key=3)
print(encoded)  # Output: "Khoog$ro/urZ#"

# Decode text
decoded = decode(encoded, key=3)
print(decoded)  # Output: "Hello, World!"

Example 2: File Encryption and Decryption

from spiral_cipher import SpiralCipher

# Initialize the cipher
cipher = SpiralCipher(key=3)

# Encrypt a file
cipher.encrypt_file("input.txt", "encrypted.txt")

# Decrypt a file
cipher.decrypt_file("encrypted.txt", "decrypted.txt")

Example 3: CLI Usage

# Encode text
spiral-cipher encode "hellow" -k 3

# Decode text
spiral-cipher decode "khoAAoAzr" -k 3

# Encrypt a file
spiral-cipher encode input.txt -f -o encrypted.txt -k 3

# Decrypt a file
spiral-cipher decode encrypted.txt -f -o decrypted.txt -k 3

---

Development

1. Clone the Repository

git clone https://github.com/ishanoshada/spiral-cipher.git
cd spiral-cipher

2. Install in Development Mode

pip install -e .

3. Run Tests

python -m unittest discover tests

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

Author

• Ishan Oshada - GitHub Profile

---

Links

• GitHub Repository: https://github.com/ishanoshada/spiral-cipher
• PyPI Package: https://pypi.org/project/spiral-cipher/
• Bug Reports: https://github.com/ishanoshada/spiral-cipher/issues

---

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Repository Views