# pyobfus
**Modern Python Code Obfuscator**
[](LICENSE)
[](https://www.python.org/downloads/)
[](https://github.com/psf/black)
A Python code obfuscator built with AST-based transformations for Python 3.8+. Provides reliable name mangling, string encoding, and code protection features.
## Features
### Core Features
- **Name Mangling**: Rename variables, functions, and classes to obfuscated names (I0, I1, I2...)
- **Comment Removal**: Strip comments and docstrings
- **Multi-file Support**: Obfuscate entire projects with preserved import relationships
- **File Filtering**: Exclude files using glob patterns (test files, config files, etc.)
- **Configuration Files**: YAML-based configuration for repeatable builds
- **Selective Obfuscation**: Preserve specific names (builtins, magic methods, custom exclusions)
### Advanced Features (Experimental)
- **String Encryption**: AES-256 encryption for string literals
- **Anti-Debugging**: Runtime debugger detection
- **Control Flow Obfuscation**: Additional protection layers (planned)
## Quick Start
### Installation
**From PyPI** (recommended):
```bash
pip install pyobfus
```
**From source** (for development):
```bash
git clone https://github.com/zhurong2020/pyobfus.git
cd pyobfus
pip install -e .
```
### Basic Usage
```bash
# Obfuscate a single file
pyobfus input.py -o output.py
# Obfuscate a directory
pyobfus src/ -o dist/
# With configuration file
pyobfus src/ -o dist/ --config pyobfus.yaml
```
### Example
**Before obfuscation**:
```python
def calculate_risk(age, score):
"""Calculate risk factor."""
risk_factor = 0.1
if score > 100:
risk_factor = 0.5
return age * risk_factor
patient_age = 55
patient_score = 150
risk = calculate_risk(patient_age, patient_score)
print(f"Risk score: {risk}")
```
**After obfuscation**:
```python
def I0(I1, I2):
I3 = 0.1
if I2 > 100:
I3 = 0.5
return I1 * I3
I4 = 55
I5 = 150
I6 = I0(I4, I5)
print(f'Risk score: {I6}')
```
*Note: Variable names (I0, I1, etc.) may vary slightly depending on code structure, but functionality is preserved.*
## Configuration
Create `pyobfus.yaml`:
```yaml
obfuscation:
level: community
exclude_patterns:
- "test_*.py"
- "**/tests/**"
- "__init__.py"
exclude_names:
- "logger"
- "config"
- "main"
remove_docstrings: true
remove_comments: true
```
### File Filtering
Exclude patterns support glob syntax:
- `test_*.py` - Exclude files starting with "test_"
- `**/tests/**` - Exclude all files in "tests" directories
- `**/__init__.py` - Exclude all `__init__.py` files
- `setup.py` - Exclude specific files
See `pyobfus.yaml.example` for more configuration examples.
## Architecture
pyobfus uses Python's `ast` module for syntax-aware transformations:
1. **Parser**: Parse Python source to AST
2. **Analyzer**: Build symbol table with scope analysis
3. **Transformers**: Apply obfuscation techniques (name mangling, string encoding, etc.)
4. **Generator**: Generate obfuscated Python code
This approach ensures:
- Syntactically correct output
- Proper handling of Python scoping rules
- Support for modern Python features (f-strings, walrus operator, etc.)
## Development
### Setup
```bash
git clone https://github.com/zhurong2020/pyobfus.git
cd pyobfus
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -e ".[dev]"
```
### Testing
```bash
# Run tests
pytest tests/ -v
# With coverage
pytest tests/ -v --cov=pyobfus --cov-report=html
```
### Code Quality
```bash
# Format code
black pyobfus/
# Type checking
mypy pyobfus/
# Linting
ruff check pyobfus/
```
## Use Cases
### Protecting Proprietary Algorithms
Obfuscate sensitive business logic before distributing Python applications.
### Educational Purposes
Demonstrate code protection concepts and obfuscation techniques.
### Intellectual Property Protection
Add an additional layer of protection for commercial Python software.
## Limitations
### Current Limitations
- **Cross-file imports**: Name mapping across files is basic (improvements planned)
- **Dynamic code**: `eval()`, `exec()` with obfuscated code may require adjustments
- **Debugging**: Obfuscated code is harder to debug (by design)
- **Performance**: Some obfuscation techniques may impact runtime performance
### Recommendations
- Test obfuscated code thoroughly
- Keep original source in version control
- Use configuration files for reproducible builds
- Consider combining with other protection methods (compilation, etc.)
## Technical Details
- **Python Support**: 3.8, 3.9, 3.10, 3.11, 3.12
- **Naming Scheme**: Index-based (I0, I1, I2...) - simple and effective
- **Architecture**: Modular transformer pipeline
- **Testing**: 57 tests, 54% coverage, multi-OS CI/CD
## Documentation
### For Users
- **[Installation & Quick Start](#installation)** - Get started in minutes
- **[Configuration Guide](#configuration)** - YAML configuration and file filtering
- **[Examples](https://github.com/zhurong2020/pyobfus/tree/main/examples)** - Working code examples demonstrating features
- **[Use Cases](#use-cases)** - Real-world application scenarios
### For Developers
- **[Project Structure](https://github.com/zhurong2020/pyobfus/blob/main/docs/PROJECT_STRUCTURE.md)** - Codebase architecture and development workflow
- **[Contributing Guide](https://github.com/zhurong2020/pyobfus/blob/main/CONTRIBUTING.md)** - How to contribute code and documentation
- **[Development Roadmap](https://github.com/zhurong2020/pyobfus/blob/main/ROADMAP.md)** - Planned features and timeline
- **[Changelog](https://github.com/zhurong2020/pyobfus/blob/main/CHANGELOG.md)** - Version history and release notes
### Community & Support
- **[GitHub Issues](https://github.com/zhurong2020/pyobfus/issues)** - Bug reports and feature requests
- **[GitHub Discussions](https://github.com/zhurong2020/pyobfus/discussions)** - Questions, ideas, and community help
- **[Security Policy](https://github.com/zhurong2020/pyobfus/blob/main/SECURITY.md)** - How to report security vulnerabilities
### Legal & License
- **[Apache 2.0 License](https://github.com/zhurong2020/pyobfus/blob/main/LICENSE)** - Open source license terms
## Support the Project
If you find pyobfus helpful, consider supporting its development:
[Buy Me A Coffee](https://www.buymeacoffee.com/zhurong052Q)
<a href="https://www.buymeacoffee.com/zhurong052Q" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
Your support helps maintain and improve pyobfus. Thank you!
## Acknowledgments
- Inspired by [Opy](https://github.com/QQuick/Opy)'s AST-based approach
- Clean room implementation - no code copying
Raw data
{
"_id": null,
"home_page": null,
"name": "pyobfus",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Rong Zhu <zhurong2020@users.noreply.github.com>",
"keywords": "obfuscation, code-protection, security, python, ast, code-obfuscator, name-mangling",
"author": null,
"author_email": "Rong Zhu <zhurong2020@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/0b/74/bcc51ddfe6c84bea6da9d4df31bf662a56e81588ff6946769cfdb2d806a2/pyobfus-0.1.3.tar.gz",
"platform": null,
"description": "# pyobfus\r\n\r\n**Modern Python Code Obfuscator**\r\n\r\n[](LICENSE)\r\n[](https://www.python.org/downloads/)\r\n[](https://github.com/psf/black)\r\n\r\nA Python code obfuscator built with AST-based transformations for Python 3.8+. Provides reliable name mangling, string encoding, and code protection features.\r\n\r\n## Features\r\n\r\n### Core Features\r\n\r\n- **Name Mangling**: Rename variables, functions, and classes to obfuscated names (I0, I1, I2...)\r\n- **Comment Removal**: Strip comments and docstrings\r\n- **Multi-file Support**: Obfuscate entire projects with preserved import relationships\r\n- **File Filtering**: Exclude files using glob patterns (test files, config files, etc.)\r\n- **Configuration Files**: YAML-based configuration for repeatable builds\r\n- **Selective Obfuscation**: Preserve specific names (builtins, magic methods, custom exclusions)\r\n\r\n### Advanced Features (Experimental)\r\n\r\n- **String Encryption**: AES-256 encryption for string literals\r\n- **Anti-Debugging**: Runtime debugger detection\r\n- **Control Flow Obfuscation**: Additional protection layers (planned)\r\n\r\n## Quick Start\r\n\r\n### Installation\r\n\r\n**From PyPI** (recommended):\r\n\r\n```bash\r\npip install pyobfus\r\n```\r\n\r\n**From source** (for development):\r\n\r\n```bash\r\ngit clone https://github.com/zhurong2020/pyobfus.git\r\ncd pyobfus\r\npip install -e .\r\n```\r\n\r\n### Basic Usage\r\n\r\n```bash\r\n# Obfuscate a single file\r\npyobfus input.py -o output.py\r\n\r\n# Obfuscate a directory\r\npyobfus src/ -o dist/\r\n\r\n# With configuration file\r\npyobfus src/ -o dist/ --config pyobfus.yaml\r\n```\r\n\r\n### Example\r\n\r\n**Before obfuscation**:\r\n\r\n```python\r\ndef calculate_risk(age, score):\r\n \"\"\"Calculate risk factor.\"\"\"\r\n risk_factor = 0.1\r\n if score > 100:\r\n risk_factor = 0.5\r\n return age * risk_factor\r\n\r\npatient_age = 55\r\npatient_score = 150\r\nrisk = calculate_risk(patient_age, patient_score)\r\nprint(f\"Risk score: {risk}\")\r\n```\r\n\r\n**After obfuscation**:\r\n\r\n```python\r\ndef I0(I1, I2):\r\n I3 = 0.1\r\n if I2 > 100:\r\n I3 = 0.5\r\n return I1 * I3\r\nI4 = 55\r\nI5 = 150\r\nI6 = I0(I4, I5)\r\nprint(f'Risk score: {I6}')\r\n```\r\n\r\n*Note: Variable names (I0, I1, etc.) may vary slightly depending on code structure, but functionality is preserved.*\r\n\r\n## Configuration\r\n\r\nCreate `pyobfus.yaml`:\r\n\r\n```yaml\r\nobfuscation:\r\n level: community\r\n exclude_patterns:\r\n - \"test_*.py\"\r\n - \"**/tests/**\"\r\n - \"__init__.py\"\r\n exclude_names:\r\n - \"logger\"\r\n - \"config\"\r\n - \"main\"\r\n remove_docstrings: true\r\n remove_comments: true\r\n```\r\n\r\n### File Filtering\r\n\r\nExclude patterns support glob syntax:\r\n\r\n- `test_*.py` - Exclude files starting with \"test_\"\r\n- `**/tests/**` - Exclude all files in \"tests\" directories\r\n- `**/__init__.py` - Exclude all `__init__.py` files\r\n- `setup.py` - Exclude specific files\r\n\r\nSee `pyobfus.yaml.example` for more configuration examples.\r\n\r\n## Architecture\r\n\r\npyobfus uses Python's `ast` module for syntax-aware transformations:\r\n\r\n1. **Parser**: Parse Python source to AST\r\n2. **Analyzer**: Build symbol table with scope analysis\r\n3. **Transformers**: Apply obfuscation techniques (name mangling, string encoding, etc.)\r\n4. **Generator**: Generate obfuscated Python code\r\n\r\nThis approach ensures:\r\n- Syntactically correct output\r\n- Proper handling of Python scoping rules\r\n- Support for modern Python features (f-strings, walrus operator, etc.)\r\n\r\n## Development\r\n\r\n### Setup\r\n\r\n```bash\r\ngit clone https://github.com/zhurong2020/pyobfus.git\r\ncd pyobfus\r\npython -m venv venv\r\nsource venv/bin/activate # Windows: venv\\Scripts\\activate\r\npip install -e \".[dev]\"\r\n```\r\n\r\n### Testing\r\n\r\n```bash\r\n# Run tests\r\npytest tests/ -v\r\n\r\n# With coverage\r\npytest tests/ -v --cov=pyobfus --cov-report=html\r\n```\r\n\r\n### Code Quality\r\n\r\n```bash\r\n# Format code\r\nblack pyobfus/\r\n\r\n# Type checking\r\nmypy pyobfus/\r\n\r\n# Linting\r\nruff check pyobfus/\r\n```\r\n\r\n## Use Cases\r\n\r\n### Protecting Proprietary Algorithms\r\n\r\nObfuscate sensitive business logic before distributing Python applications.\r\n\r\n### Educational Purposes\r\n\r\nDemonstrate code protection concepts and obfuscation techniques.\r\n\r\n### Intellectual Property Protection\r\n\r\nAdd an additional layer of protection for commercial Python software.\r\n\r\n## Limitations\r\n\r\n### Current Limitations\r\n\r\n- **Cross-file imports**: Name mapping across files is basic (improvements planned)\r\n- **Dynamic code**: `eval()`, `exec()` with obfuscated code may require adjustments\r\n- **Debugging**: Obfuscated code is harder to debug (by design)\r\n- **Performance**: Some obfuscation techniques may impact runtime performance\r\n\r\n### Recommendations\r\n\r\n- Test obfuscated code thoroughly\r\n- Keep original source in version control\r\n- Use configuration files for reproducible builds\r\n- Consider combining with other protection methods (compilation, etc.)\r\n\r\n## Technical Details\r\n\r\n- **Python Support**: 3.8, 3.9, 3.10, 3.11, 3.12\r\n- **Naming Scheme**: Index-based (I0, I1, I2...) - simple and effective\r\n- **Architecture**: Modular transformer pipeline\r\n- **Testing**: 57 tests, 54% coverage, multi-OS CI/CD\r\n\r\n## Documentation\r\n\r\n### For Users\r\n- **[Installation & Quick Start](#installation)** - Get started in minutes\r\n- **[Configuration Guide](#configuration)** - YAML configuration and file filtering\r\n- **[Examples](https://github.com/zhurong2020/pyobfus/tree/main/examples)** - Working code examples demonstrating features\r\n- **[Use Cases](#use-cases)** - Real-world application scenarios\r\n\r\n### For Developers\r\n- **[Project Structure](https://github.com/zhurong2020/pyobfus/blob/main/docs/PROJECT_STRUCTURE.md)** - Codebase architecture and development workflow\r\n- **[Contributing Guide](https://github.com/zhurong2020/pyobfus/blob/main/CONTRIBUTING.md)** - How to contribute code and documentation\r\n- **[Development Roadmap](https://github.com/zhurong2020/pyobfus/blob/main/ROADMAP.md)** - Planned features and timeline\r\n- **[Changelog](https://github.com/zhurong2020/pyobfus/blob/main/CHANGELOG.md)** - Version history and release notes\r\n\r\n### Community & Support\r\n- **[GitHub Issues](https://github.com/zhurong2020/pyobfus/issues)** - Bug reports and feature requests\r\n- **[GitHub Discussions](https://github.com/zhurong2020/pyobfus/discussions)** - Questions, ideas, and community help\r\n- **[Security Policy](https://github.com/zhurong2020/pyobfus/blob/main/SECURITY.md)** - How to report security vulnerabilities\r\n\r\n### Legal & License\r\n- **[Apache 2.0 License](https://github.com/zhurong2020/pyobfus/blob/main/LICENSE)** - Open source license terms\r\n\r\n## Support the Project\r\n\r\nIf you find pyobfus helpful, consider supporting its development:\r\n\r\n[Buy Me A Coffee](https://www.buymeacoffee.com/zhurong052Q)\r\n\r\n<a href=\"https://www.buymeacoffee.com/zhurong052Q\" target=\"_blank\"><img src=\"https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png\" alt=\"Buy Me A Coffee\" style=\"height: 60px !important;width: 217px !important;\" ></a>\r\n\r\nYour support helps maintain and improve pyobfus. Thank you!\r\n\r\n## Acknowledgments\r\n\r\n- Inspired by [Opy](https://github.com/QQuick/Opy)'s AST-based approach\r\n- Clean room implementation - no code copying\r\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Modern Python Code Obfuscator with AST-based Transformations",
"version": "0.1.3",
"project_urls": {
"Bug Tracker": "https://github.com/zhurong2020/pyobfus/issues",
"Changelog": "https://github.com/zhurong2020/pyobfus/blob/main/CHANGELOG.md",
"Discussions": "https://github.com/zhurong2020/pyobfus/discussions",
"Documentation": "https://zhurong2020.github.io/pyobfus/",
"Funding": "https://www.buymeacoffee.com/zhurong052Q",
"Homepage": "https://github.com/zhurong2020/pyobfus",
"Repository": "https://github.com/zhurong2020/pyobfus",
"Source Code": "https://github.com/zhurong2020/pyobfus"
},
"split_keywords": [
"obfuscation",
" code-protection",
" security",
" python",
" ast",
" code-obfuscator",
" name-mangling"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "15baf13e7e4b7cff5139daf2b2bbec6c3d053f6e0ba231b39de454e3470a09b5",
"md5": "e114d1a6b941dd667a1be0ca3c43ceee",
"sha256": "e08cd5c259ddc6dc778700fb5d878771822f17da7737cdfd3e2a40b73b1a152c"
},
"downloads": -1,
"filename": "pyobfus-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e114d1a6b941dd667a1be0ca3c43ceee",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 42899,
"upload_time": "2025-11-12T02:01:06",
"upload_time_iso_8601": "2025-11-12T02:01:06.375651Z",
"url": "https://files.pythonhosted.org/packages/15/ba/f13e7e4b7cff5139daf2b2bbec6c3d053f6e0ba231b39de454e3470a09b5/pyobfus-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0b74bcc51ddfe6c84bea6da9d4df31bf662a56e81588ff6946769cfdb2d806a2",
"md5": "98dc30bb68359ccb4c752950b5c4232d",
"sha256": "a7e071c1d14a74484916e0e4eac7f566ce3617d8dcf6b564da3256078c62fba9"
},
"downloads": -1,
"filename": "pyobfus-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "98dc30bb68359ccb4c752950b5c4232d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 50144,
"upload_time": "2025-11-12T02:01:07",
"upload_time_iso_8601": "2025-11-12T02:01:07.511792Z",
"url": "https://files.pythonhosted.org/packages/0b/74/bcc51ddfe6c84bea6da9d4df31bf662a56e81588ff6946769cfdb2d806a2/pyobfus-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-12 02:01:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zhurong2020",
"github_project": "pyobfus",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pyobfus"
}
JSON
