pyprotectorx 5.5.0
PPX ENCRYPTION - Python 3.11/3.12/3.13 - Termux & Pydroid3
License: MIT
Requires Python: <3.14,>=3.11
Keywords: encryption obfuscation security protection code-protection termux pydroid3 android mobile

# 🔐 PyProtectorX v5.5.0

**Universal Python Code Protection**

[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/)
[![PyPI](https://img.shields.io/badge/pypi-v5.5.0-green.svg)](https://pypi.org/project/pyprotectorx/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Mobile](https://img.shields.io/badge/mobile-Termux%20%7C%20Pydroid3-orange.svg)](https://github.com/zainalkhalil/pyprotectorx)

## ✨ Features

- 🔒 **Military-grade encryption** (ChaCha20 + PBKDF2 150k iterations)
- 🐍 **Python 3.11, 3.12, 3.13** support
- 📱 **Mobile optimized** - Termux & Pydroid3
- 🚀 **Simple API** - 3 functions
- 💪 **Zero dependencies** - Pure Python
- ⚡ **Fast** - Optimized for all platforms

## 📦 Installation

```bash
# Desktop / PC / Mac
pip install pyprotectorx

# Termux (Android)
pkg install python
pip install pyprotectorx

# Pydroid3 (Android)
# Menu → Pip → Search: pyprotectorx → Install
```

## 🎯 Quick Start

### Command Line (Easiest)
```bash
# Protect any Python file
pyprotectorx script.py

# Run protected file
python script.protected.py
```

### Python API
```python
from pyprotectorx import protect

# Protect file
protect("script.py")
# Output: script.protected.py
```

### Advanced API
```python
from pyprotectorx import encrypt, run

# Encrypt code
source = 'print("Hello, World!")'
encrypted = encrypt(source)

# Run encrypted code
run(encrypted)
```

## 📖 Complete Examples

### Example 1: Basic Usage
```bash
# Create test script
echo 'print("Secret Code!")' > test.py

# Protect it
pyprotectorx test.py

# Run protected version
python test.protected.py
# Output: Secret Code!
```

### Example 2: Termux
```bash
# Install
pkg install python -y
pip install pyprotectorx

# Protect your script
cd ~/storage/shared
pyprotectorx myapp.py

# Share the protected file
python myapp.protected.py
```

### Example 3: Pydroid3
```python
from pyprotectorx import protect

# Protect file
protect("/sdcard/Download/script.py")

# Output: /sdcard/Download/script.protected.py
```

## 🔥 API Reference

### `protect(input_file, output_file=None)`
**Easiest method** - Protect a Python file

```python
from pyprotectorx import protect

protect("app.py")  # → app.protected.py
protect("app.py", "secure.py")  # → secure.py
```

### `encrypt(source_code)`
Encrypt Python source code

```python
from pyprotectorx import encrypt

encrypted = encrypt('print("Hi")')
# Returns: bytes
```

### `run(encrypted_data)`
Execute encrypted code

```python
from pyprotectorx import run

namespace = run(encrypted_data)
# Returns: dict with execution namespace
```

### `info()`
Show version information

```python
from pyprotectorx import info

print(info())
# {'version': '5.5.0', 'python': '3.12.0', ...}
```

## 🛡️ Security Features

| Layer | Technology |
|-------|-----------|
| 1 | ChaCha20 stream cipher |
| 2 | PBKDF2 (150,000 iterations) |
| 3 | HMAC-SHA256 authentication |
| 4 | Blake2b cryptographic hashing |
| 5 | SHA3-256 additional hashing |
| 6 | CRC32 integrity checking |
| 7 | Zlib compression layer |
| 8 | Custom obfuscation layers |
| 9 | Bundle sealing |

## ⚙️ How It Works

```
Python Source Code
       ↓
[1] Syntax validation
       ↓
[2] Compile to bytecode
       ↓
[3] Marshal serialization
       ↓
[4] Custom compression + encryption
       ↓
[5] ChaCha20 encryption
       ↓
[6] HMAC authentication
       ↓
[7] Bundle sealing with metadata
       ↓
[8] Base64 encoding
       ↓
Protected Python File
```

## 📱 Mobile Development Tips

### Termux Best Practices
```bash
# Storage access
termux-setup-storage

# Work in shared storage
cd ~/storage/shared

# Protect scripts
pyprotectorx script.py
```

### Pydroid3 Tips
```python
# Use full paths
from pyprotectorx import protect

# Protect file in Downloads
protect("/sdcard/Download/app.py")

# Protect file in Documents
protect("/sdcard/Documents/script.py")
```

## ⚠️ Requirements & Limitations

### Requirements
- **Python 3.11, 3.12, or 3.13**
- No additional dependencies

### Limitations
- Maximum file size: 100 MB
- Source code must have valid syntax
- Python 3.14+ not yet supported

### Compatibility
✅ Linux, macOS, Windows  
✅ Termux (Android)  
✅ Pydroid3 (Android)  
✅ Raspberry Pi  
✅ Cloud environments

## 🐛 Troubleshooting

### Error: "Python 3.11+ required"
```bash
# Check Python version
python --version

# Termux: Install Python 3.11+
pkg install python

# Pydroid3: Update app to latest version
```

### Error: "Failed to load core"
```bash
# Reinstall package
pip uninstall pyprotectorx -y
pip install --no-cache-dir pyprotectorx
```

### Error: "Syntax error in source"
```bash
# Validate your script first
python -m py_compile script.py
```

### Protected file too large
```python
# Use direct encryption API
from pyprotectorx import encrypt
import base64

encrypted = encrypt(source_code)
# Store encrypted bytes separately
with open('data.bin', 'wb') as f:
    f.write(encrypted)
```

## 🔒 Security Notice

⚠️ **Important**: No encryption is unbreakable. PyProtectorX makes reverse engineering **significantly harder** but cannot guarantee absolute protection against determined attackers with unlimited resources.

**Good for:**
- ✅ Protecting proprietary algorithms
- ✅ Preventing casual code inspection
- ✅ Obfuscating business logic
- ✅ License key protection
- ✅ Anti-tampering measures

**Not a substitute for:**
- ❌ Proper authentication systems
- ❌ Secure password storage
- ❌ Network security
- ❌ Server-side validation

## 📊 Version History

### v5.5.0 (Latest)
- ✨ Added Python 3.13 support
- 🚀 Improved mobile performance
- 🐛 Bug fixes and optimizations
- 📱 Enhanced Termux compatibility

### v5.1.0
- ✨ Python 3.11 & 3.12 support
- 📱 Termux & Pydroid3 optimization
- 🔒 Enhanced encryption layers

## 🔗 Links

- **PyPI**: https://pypi.org/project/pyprotectorx/
- **GitHub**: https://github.com/zainalkhalil/pyprotectorx
- **Issues**: https://github.com/zainalkhalil/pyprotectorx/issues
- **Documentation**: https://github.com/zainalkhalil/pyprotectorx/wiki

## 📄 License

MIT License - Copyright (c) 2025 Zain Alkhalil

See [LICENSE](LICENSE) file for details.

## 👨‍💻 Author

**Zain Alkhalil**
- Specialized in Python security & cryptography
- Mobile development enthusiast
- Open source contributor

## 🌟 Support the Project

If you find PyProtectorX useful:
- ⭐ Star on GitHub
- 🐛 Report bugs
- 💡 Suggest features
- 📢 Share with others
- ☕ Buy me a coffee

## 🙏 Acknowledgments

Thanks to all contributors and users who helped improve PyProtectorX!

---

**Made with ❤️ for the Python community**

*Protect your code. Protect your work. Protect your future.*