# 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`:
```bash
pip install spiral-cipher
```
---
## Usage
### Python API
The package provides a Python API for programmatic usage.
#### 1. **Encoding and Decoding Text**
```python
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**
```python
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**
```bash
# 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**
```bash
# 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
```python
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
```python
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
```bash
# 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**
```bash
git clone https://github.com/ishanoshada/spiral-cipher.git
cd spiral-cipher
```
### 2. **Install in Development Mode**
```bash
pip install -e .
```
### 3. **Run Tests**
```bash
python -m unittest discover tests
```
---
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
---
## Author
- **Ishan Oshada** - [GitHub Profile](https://github.com/ishanoshada)
---
## Links
- **GitHub Repository**: [https://github.com/ishanoshada/spiral-cipher](https://github.com/ishanoshada/spiral-cipher)
- **PyPI Package**: [https://pypi.org/project/spiral-cipher/](https://pypi.org/project/spiral-cipher/)
- **Bug Reports**: [https://github.com/ishanoshada/spiral-cipher/issues](https://github.com/ishanoshada/spiral-cipher/issues)
---
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
**Repository Views** 
Raw data
{
"_id": null,
"home_page": "https://github.com/ishanoshada/spiral-cipher",
"name": "spiral-cipher",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "cipher, encryption, spiral, cryptography, security",
"author": "Ishan Oshada",
"author_email": "ishan.kodithuwakku.offical@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/d0/f2/a2f1102989aba761ba3cc52a96c6e16b861808a819f553deb276f298810c/spiral_cipher-0.1.2.tar.gz",
"platform": "any",
"description": "# Spiral Cipher Documentation\n\n\n\nThe **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.\n\n---\n\n## Features\n\n- **Text Encryption/Decryption**: Encrypt and decrypt text using a spiral pattern.\n- **File Encryption/Decryption**: Encrypt and decrypt files.\n- **Customizable Key**: Use a key to shift characters for additional security.\n- **UTF-8 Support**: Works with Unicode characters.\n- **Command-Line Interface (CLI)**: Easy-to-use CLI for text and file operations.\n- **Python API**: Programmatic access to encryption/decryption functions.\n\n---\n\n## Installation\n\nInstall the package using `pip`:\n\n```bash\npip install spiral-cipher\n```\n\n---\n\n## Usage\n\n### Python API\n\nThe package provides a Python API for programmatic usage.\n\n#### 1. **Encoding and Decoding Text**\n\n```python\nfrom spiral_cipher import encode, decode\n\n# Encode text\nencoded_text = encode(\"Hello, World!\", key=1111) # any key : int , ex : 9999999\nprint(encoded_text) # Output: \"AxeeQQQhew!,khP\"\n\n# Decode text\ndecoded_text = decode(encoded_text, key=1111)\nprint(decoded_text) # Output: \"Hello, World!\"\n```\n\n#### 2. **Using the `SpiralCipher` Class**\n\n```python\nfrom spiral_cipher import SpiralCipher\n\n# Initialize the cipher with a key\ncipher = SpiralCipher(key=3)\n\n# Encode text\nencoded_text = cipher.encode(\"Hello, World!\")\nprint(encoded_text) # Output: \"KhooAAArog!,urZ\"\n\n# Decode text\ndecoded_text = cipher.decode(encoded_text)\nprint(decoded_text) # Output: \"Hello, World!\"\n\n# Encrypt a file\ncipher.encrypt_file(\"input.txt\", \"encrypted.txt\")\n\n# Decrypt a file\ncipher.decrypt_file(\"encrypted.txt\", \"decrypted.txt\")\n```\n\n---\n\n### Command-Line Interface (CLI)\n\nThe package provides a CLI for easy text and file processing.\n\n#### 1. **Text Processing**\n\n```bash\n# Encode text\nspiral-cipher encode \"Hello, World!\" -k 3\n\n# Decode text\nspiral-cipher decode \"KhooAAArog!,urZ \" -k 3 #don't miss space +_+\n```\n\n#### 2. **File Processing**\n\n```bash\n# Encrypt a file\nspiral-cipher encode input.txt -f -o encrypted.txt -k 3\n\n# Decrypt a file\nspiral-cipher decode encrypted.txt -f -o decrypted.txt -k 3\n```\n\n#### 3. **CLI Options**\n\n| Argument | Description |\n|----------|-------------|\n| `action` | Action to perform (`encode` or `decode`) |\n| `input` | Text to process or input file path |\n| `-k, --key` | Encryption key (default: `1`) |\n| `-f, --file` | Treat input as a file path |\n| `-o, --output` | Output file path (required for file operations) |\n| `-h, --help` | Show help message |\n\n---\n\n## How It Works\n\n### Encryption Process\n\n1. **Create a Square Matrix**:\n - The input text is padded (if necessary) to fit into the smallest square matrix.\n\n2. **Write Text in Spiral Pattern**:\n - The text is written in a spiral pattern (clockwise or counterclockwise) within the matrix.\n\n3. **Shift Characters**:\n - Each character is shifted by the key value for additional security.\n\n4. **Read Row by Row**:\n - The matrix is read row by row to generate the encrypted text.\n\n### Decryption Process\n\n1. **Create a Square Matrix**:\n - The encrypted text is placed into a square matrix.\n\n2. **Read Text in Spiral Pattern**:\n - The text is read in the reverse spiral pattern.\n\n3. **Unshift Characters**:\n - Each character is unshifted by the key value.\n\n4. **Remove Padding**:\n - Padding characters are removed to retrieve the original text.\n\n---\n\n## Examples\n\n### Example 1: Encoding and Decoding Text\n\n```python\nfrom spiral_cipher import encode, decode\n\n# Encode text\nencoded = encode(\"Hello, World!\", key=3)\nprint(encoded) # Output: \"Khoog$ro/urZ#\"\n\n# Decode text\ndecoded = decode(encoded, key=3)\nprint(decoded) # Output: \"Hello, World!\"\n```\n\n### Example 2: File Encryption and Decryption\n\n```python\nfrom spiral_cipher import SpiralCipher\n\n# Initialize the cipher\ncipher = SpiralCipher(key=3)\n\n# Encrypt a file\ncipher.encrypt_file(\"input.txt\", \"encrypted.txt\")\n\n# Decrypt a file\ncipher.decrypt_file(\"encrypted.txt\", \"decrypted.txt\")\n```\n\n### Example 3: CLI Usage\n\n```bash\n# Encode text\nspiral-cipher encode \"hellow\" -k 3\n\n# Decode text\nspiral-cipher decode \"khoAAoAzr\" -k 3\n\n# Encrypt a file\nspiral-cipher encode input.txt -f -o encrypted.txt -k 3\n\n# Decrypt a file\nspiral-cipher decode encrypted.txt -f -o decrypted.txt -k 3\n```\n\n---\n\n## Development\n\n### 1. **Clone the Repository**\n\n```bash\ngit clone https://github.com/ishanoshada/spiral-cipher.git\ncd spiral-cipher\n```\n\n### 2. **Install in Development Mode**\n\n```bash\npip install -e .\n```\n\n### 3. **Run Tests**\n\n```bash\npython -m unittest discover tests\n```\n\n---\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n---\n\n## Author\n\n- **Ishan Oshada** - [GitHub Profile](https://github.com/ishanoshada)\n\n---\n\n## Links\n\n- **GitHub Repository**: [https://github.com/ishanoshada/spiral-cipher](https://github.com/ishanoshada/spiral-cipher)\n- **PyPI Package**: [https://pypi.org/project/spiral-cipher/](https://pypi.org/project/spiral-cipher/)\n- **Bug Reports**: [https://github.com/ishanoshada/spiral-cipher/issues](https://github.com/ishanoshada/spiral-cipher/issues)\n\n---\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n**Repository Views** \n",
"bugtrack_url": null,
"license": null,
"summary": "A spiral cipher implementation for text encryption and decryption",
"version": "0.1.2",
"project_urls": {
"Bug Tracker": "https://github.com/ishanoshada/spiral-cipher/issues",
"Documentation": "https://github.com/ishanoshada/spiral-cipher#readme",
"Homepage": "https://github.com/ishanoshada/spiral-cipher",
"Source Code": "https://github.com/ishanoshada/spiral-cipher"
},
"split_keywords": [
"cipher",
" encryption",
" spiral",
" cryptography",
" security"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2a49fbe37ce30d8b7bdd265979e2c79b8b1e02e5abeeec4b0d491f9e28b4e19c",
"md5": "415e4ab862207a32b3cb226d2964d664",
"sha256": "971f44262f16ebb1c3eda70cd6a1eb521b6d53ebc5785b7441d0f63b57045332"
},
"downloads": -1,
"filename": "spiral_cipher-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "415e4ab862207a32b3cb226d2964d664",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 5980,
"upload_time": "2025-01-27T17:07:34",
"upload_time_iso_8601": "2025-01-27T17:07:34.845403Z",
"url": "https://files.pythonhosted.org/packages/2a/49/fbe37ce30d8b7bdd265979e2c79b8b1e02e5abeeec4b0d491f9e28b4e19c/spiral_cipher-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d0f2a2f1102989aba761ba3cc52a96c6e16b861808a819f553deb276f298810c",
"md5": "763762ff420a4db7e748f1a5a27a6a8c",
"sha256": "db1aad5c5d25a5dddf69b166b0d0dc03014f846ddaeaedf70b6fcca6b9fda43d"
},
"downloads": -1,
"filename": "spiral_cipher-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "763762ff420a4db7e748f1a5a27a6a8c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 6061,
"upload_time": "2025-01-27T17:07:36",
"upload_time_iso_8601": "2025-01-27T17:07:36.996304Z",
"url": "https://files.pythonhosted.org/packages/d0/f2/a2f1102989aba761ba3cc52a96c6e16b861808a819f553deb276f298810c/spiral_cipher-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-27 17:07:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ishanoshada",
"github_project": "spiral-cipher",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "spiral-cipher"
}
JSON
