0
# PyArmor
1

2
A comprehensive Python script obfuscation tool that protects Python intellectual property through code obfuscation, hardware binding, and license management. PyArmor provides seamless replacement of original scripts with obfuscated versions while maintaining compatibility, offering multiple protection strategies from basic obfuscation to advanced machine-code compilation.
3

4
## Package Information
5

6
- **Package Name**: pyarmor
7
- **Language**: Python
8
- **Installation**: `pip install pyarmor`
9
- **License**: Free To Use But Restricted (commercial licensing available)
10

11
## Core Imports
12

13
```python
14
import pyarmor
15
```
16

17
For programmatic access to legacy API:
18

19
```python
20
from pyarmor import utils, project
21
from pyarmor.pyarmor import main_entry, main_entry_8
22
```
23

24
For modern CLI components (advanced usage):
25

26
```python
27
from pyarmor.cli.context import Context
28
from pyarmor.cli.generate import Builder
29
from pyarmor.cli.register import Register, WebRegister
30
from pyarmor.cli.config import Configer
31
```
32

33
## Basic Usage
34

35
### Command Line Usage (Primary Interface)
36

37
```bash
38
# Install PyArmor
39
pip install pyarmor
40

41
# Basic script obfuscation
42
pyarmor gen foo.py
43

44
# Obfuscate with options
45
pyarmor gen --recursive --output dist --mix-str src/
46

47
# Advanced obfuscation with hardware binding
48
pyarmor gen --bind-device "00:11:22:33:44:55" --expired "2024-12-31" foo.py
49

50
# Pack with PyInstaller
51
pyarmor gen --pack onefile foo.py
52

53
# Check configuration
54
pyarmor cfg
55

56
# Register license
57
pyarmor reg pyarmor-regcode-xxxx.txt
58
```
59

60
### Programmatic Usage (Advanced)
61

62
```python
63
import os
64
from pyarmor import utils, project
65

66
# Initialize PyArmor environment
67
utils.pytransform_bootstrap()
68

69
# Create and configure project
70
proj = project.Project()
71
proj.name = "MyProject"
72
proj.src = "src"
73
proj.output = "dist"
74
proj.entry = "main.py"
75
proj.obf_code = 1  # Enable code obfuscation
76
proj.obf_mod = 1   # Enable module obfuscation
77
proj.save("myproject.json")
78

79
# Obfuscate scripts
80
capsule = utils.make_capsule(None)
81
utils.make_runtime(capsule, "dist")
82
utils.encrypt_script(capsule, "src/main.py", "dist/main.py")
83
```
84

85
## Architecture
86

87
PyArmor employs a multi-layered protection architecture:
88

89
- **Script Layer**: Python source code transformation and obfuscation
90
- **Module Layer**: Import-time protection and validation  
91
- **Runtime Layer**: C extension libraries providing core protection
92
- **License Layer**: Hardware binding and time-based restrictions
93
- **Platform Layer**: Cross-platform support with native libraries
94

95
The tool supports multiple interface generations:
96
- **Legacy (v7)**: Full-featured interface with project management
97
- **Modern (v8+)**: Streamlined CLI with simplified commands
98
- **Hybrid (v9+)**: Combined interface supporting both approaches
99

100
## Capabilities
101

102
### Command Line Interface
103

104
Primary interface for PyArmor providing obfuscation, configuration, and license management through intuitive commands. Supports both modern streamlined interface and legacy full-featured commands.
105

106
```python { .api }
107
# Modern CLI Commands (pyarmor, pyarmor-8)
108
def gen(*args, **kwargs): ...  # Generate obfuscated scripts
109
def cfg(*args, **kwargs): ...  # Configuration management  
110
def reg(*args, **kwargs): ...  # License registration
111
def man(*args, **kwargs): ...  # Interactive help system
112

113
# Legacy CLI Commands (pyarmor-7)  
114
def obfuscate(*args, **kwargs): ...  # Direct obfuscation without project
115
def init(*args, **kwargs): ...       # Initialize project
116
def build(*args, **kwargs): ...      # Build project
117
def config(*args, **kwargs): ...     # Configure project
118
def licenses(*args, **kwargs): ...   # Generate license files
119
def pack(*args, **kwargs): ...       # Package with external tools
120
```
121

122
[Command Line Interface](./cli.md)
123

124
### Project Management
125

126
Create, configure, and manage PyArmor projects for organized obfuscation workflows with persistent settings and batch processing capabilities.
127

128
```python { .api }
129
class Project(dict):
130
    def open(self, path: str) -> None: ...
131
    def save(self, path: str) -> None: ...
132
    def check(self) -> bool: ...
133
    def get_build_files(self, force: bool = False, excludes: list = []) -> list: ...
134
    def info(self) -> str: ...
135
    def _update(self, **kwargs) -> None: ...
136
```
137

138
[Project Management](./project-management.md)
139

140
### Script Obfuscation
141

142
Core obfuscation engine providing multiple protection levels from basic name mangling to advanced binary code compilation with machine instruction generation.
143

144
```python { .api }
145
def encrypt_script(pubkey, filename: str, destname: str, wrap_mode: int = 1, obf_code: int = 1, obf_mod: int = 1, adv_mode: int = 0, rest_mode: int = 1, entry: int = 0, protection: int = 0, platforms = None, plugins = None, rpath = None, suffix: str = '', sppmode: bool = False, mixins = None) -> None: ...
146
def make_runtime(capsule, output: str, licfile = None, platforms = None, package: bool = False, suffix: str = '', supermode: bool = False) -> None: ...
147
def make_capsule(filename: str) -> None: ...
148
def make_entry(entris: str, path: str, output: str, rpath = None, relative = None, suffix: str = '', advanced: int = 0) -> None: ...
149
def make_bootstrap_script(output: str, **kwargs) -> None: ...
150
```
151

152
[Script Obfuscation](./obfuscation.md)
153

154
### License Management
155

156
Generate and manage licenses with hardware binding, expiration dates, and custom restrictions for controlling access to obfuscated scripts.
157

158
```python { .api }
159
def make_license_key(capsule, code: str, output: str = None, key = None, legency: int = 0) -> None: ...
160
def query_keyinfo(key: str) -> dict: ...
161
def activate_regcode(ucode: str) -> dict: ...
162
def register_keyfile(filename: str, upgrade: bool = False, legency: bool = False) -> None: ...
163
def get_registration_code() -> str: ...
164
```
165

166
[License Management](./licensing.md)
167

168
### Configuration Management
169

170
System-wide and project-specific configuration with hierarchical settings and interactive configuration shell for managing obfuscation parameters.
171

172
```python { .api }
173
class Configer:
174
    def list_sections(self, local: bool = True, name: str = None) -> list: ...
175
    def list_options(self, sect: str, local: bool = True, name: str = None) -> list: ...
176
    def run(self, options: list, local: bool, name: str) -> None: ...
177
    def reset(self, options: list, local: bool, name: str) -> None: ...
178

179
class Context:
180
    def __init__(self, *paths): ...
181
    def push(self, options: dict) -> None: ...
182
    def get_res_options(self, fullname: str, catalog: str) -> dict: ...
183
```
184

185
[Configuration Management](./configuration.md)
186

187
### Platform Support
188

189
Cross-platform obfuscation with automatic platform detection, library downloading, and support for 40+ target platforms including embedded systems.
190

191
```python { .api }
192
def show_hd_info(name: str = None) -> str: ...
193
def download_pytransform(platname: str, **kwargs) -> None: ...
194
def check_cross_platform(platforms: list, **kwargs) -> None: ...
195
def get_platform_name() -> str: ...
196
def format_platform(system: str = None, machine: str = None) -> str: ...
197
```
198

199
[Platform Support](./platform-support.md)
200

201
## Types
202

203
```python { .api }
204
# Project Configuration
205
class ProjectConfig:
206
    name: str
207
    title: str  
208
    src: str
209
    output: str
210
    entry: str
211
    obf_code: int      # 0=disable, 1=enable, 2=advanced
212
    obf_mod: int       # 0=disable, 1=enable
213
    wrap_mode: int     # 0=disable, 1=enable
214
    advanced_mode: int # 0-5 protection levels
215
    restrict_mode: int # 0=none, 1=import, 2=private, 3=restrict
216
    runtime_path: str
217
    platform: str
218
    package_runtime: int
219
    cross_protection: int
220
    license_file: str
221

222
# Obfuscation Options  
223
class ObfuscationOptions:
224
    recursive: bool
225
    output: str
226
    obf_module: int
227
    obf_code: int
228
    mix_str: bool
229
    enable_bcc: bool
230
    enable_jit: bool
231
    enable_rft: bool
232
    enable_themida: bool
233
    assert_call: bool
234
    assert_import: bool
235
    restrict_module: int
236
    platforms: list
237
    outer: bool
238
    expired: str
239
    period: int
240
    devices: list
241
    bind_data: str
242

243
# Registration Info
244
class RegistrationInfo:
245
    product: str
246
    version: str
247
    lictype: str
248
    features: list
249
    expired: str
250
    devices: int
251
    platform: str
252
```