0
# JavaScript Interpreters
1

2
Multiple JavaScript execution backends for solving Cloudflare challenges. CloudScraper supports various interpreters to handle different challenge complexities and system requirements, with automatic fallback and error handling.
3

4
## Capabilities
5

6
### Base Interpreter Interface
7

8
Abstract base class that all JavaScript interpreters implement for consistent challenge solving across different execution backends.
9

10
```python { .api }
11
class JavaScriptInterpreter:
12
    def __init__(self, name: str):
13
        """
14
        Initialize JavaScript interpreter.
15
        
16
        Parameters:
17
        - name: str, interpreter identifier
18
        """
19

20
    @classmethod
21
    def dynamicImport(cls, name: str):
22
        """
23
        Dynamically import and initialize interpreter.
24
        
25
        Parameters:
26
        - name: str, interpreter name to load
27
        
28
        Returns:
29
        JavaScriptInterpreter instance
30
        
31
        Raises:
32
        - ImportError: If interpreter cannot be loaded
33
        """
34

35
    def eval(self, jsEnv: str, js: str):
36
        """
37
        Execute JavaScript code in given environment.
38
        
39
        Parameters:
40
        - jsEnv: str, JavaScript environment/context
41
        - js: str, JavaScript code to execute
42
        
43
        Returns:
44
        Execution result
45
        
46
        Raises:
47
        - CloudflareSolveError: If JavaScript execution fails
48
        """
49

50
    def solveChallenge(self, body: str, domain: str) -> str:
51
        """
52
        Solve Cloudflare challenge using JavaScript execution.
53
        
54
        Parameters:
55
        - body: str, challenge JavaScript code
56
        - domain: str, target domain
57
        
58
        Returns:
59
        str: Challenge solution as formatted float
60
        
61
        Raises:
62
        - CloudflareSolveError: If challenge cannot be solved
63
        """
64
```
65

66
### js2py Interpreter
67

68
Pure Python JavaScript interpreter that provides good compatibility without external dependencies. This is the default and recommended interpreter.
69

70
```python { .api }
71
class ChallengeInterpreter(JavaScriptInterpreter):
72
    def __init__(self):
73
        """Initialize js2py interpreter."""
74

75
    def eval(self, jsEnv: str, js: str):
76
        """
77
        Execute JavaScript using js2py library.
78
        
79
        Parameters:
80
        - jsEnv: str, JavaScript environment code
81
        - js: str, JavaScript code to execute
82
        
83
        Returns:
84
        Execution result from js2py
85
        """
86
```
87

88
#### Usage Examples
89

90
```python
91
# js2py is the default interpreter
92
scraper = cloudscraper.create_scraper()  # Uses js2py
93

94
# Explicitly specify js2py
95
scraper = cloudscraper.create_scraper(interpreter='js2py')
96

97
# js2py works well with all challenge types
98
response = scraper.get('https://v1-protected-site.com')   # v1 challenges
99
response = scraper.get('https://v2-protected-site.com')   # v2 challenges  
100
response = scraper.get('https://v3-protected-site.com')   # v3 challenges (recommended)
101
```
102

103
### Node.js Interpreter
104

105
Subprocess-based interpreter that uses Node.js for JavaScript execution, providing high compatibility and performance.
106

107
```python { .api }
108
class ChallengeInterpreter(JavaScriptInterpreter):
109
    def __init__(self):
110
        """Initialize Node.js interpreter."""
111

112
    def eval(self, jsEnv: str, js: str):
113
        """
114
        Execute JavaScript using Node.js subprocess.
115
        
116
        Parameters:
117
        - jsEnv: str, JavaScript environment code
118
        - js: str, JavaScript code to execute
119
        
120
        Returns:
121
        Execution result from Node.js
122
        
123
        Raises:
124
        - CloudflareSolveError: If Node.js execution fails
125
        """
126
```
127

128
#### Usage Examples
129

130
```python
131
# Requires Node.js installed on system
132
scraper = cloudscraper.create_scraper(interpreter='nodejs')
133

134
# Good for complex JavaScript challenges
135
response = scraper.get('https://complex-protected-site.com')
136

137
# Check if Node.js is available
138
import subprocess
139
try:
140
    subprocess.check_output(['node', '--version'])
141
    scraper = cloudscraper.create_scraper(interpreter='nodejs')
142
except FileNotFoundError:
143
    print("Node.js not available, falling back to js2py")
144
    scraper = cloudscraper.create_scraper(interpreter='js2py')
145
```
146

147
### V8 Interpreter
148

149
V8 JavaScript engine wrapper that provides native performance and excellent compatibility with modern JavaScript features.
150

151
```python { .api }
152
class ChallengeInterpreter(JavaScriptInterpreter):
153
    def __init__(self):
154
        """Initialize V8 interpreter."""
155

156
    def eval(self, jsEnv: str, js: str):
157
        """
158
        Execute JavaScript using V8 engine.
159
        
160
        Parameters:
161
        - jsEnv: str, JavaScript environment code
162
        - js: str, JavaScript code to execute
163
        
164
        Returns:
165
        Execution result from V8
166
        """
167
```
168

169
#### Usage Examples
170

171
```python
172
# Requires v8eval Python package
173
scraper = cloudscraper.create_scraper(interpreter='v8')
174

175
# High performance for intensive challenges
176
response = scraper.get('https://performance-intensive-site.com')
177

178
# Install v8eval: pip install v8eval
179
try:
180
    scraper = cloudscraper.create_scraper(interpreter='v8')
181
except ImportError:
182
    print("V8 not available, using js2py")
183
    scraper = cloudscraper.create_scraper(interpreter='js2py')
184
```
185

186
### ChakraCore Interpreter
187

188
Microsoft ChakraCore JavaScript engine wrapper for Windows environments and specific compatibility requirements.
189

190
```python { .api }
191
class ChallengeInterpreter(JavaScriptInterpreter):
192
    def __init__(self):
193
        """Initialize ChakraCore interpreter."""
194

195
    def eval(self, jsEnv: str, js: str):
196
        """
197
        Execute JavaScript using ChakraCore engine.
198
        
199
        Parameters:
200
        - jsEnv: str, JavaScript environment code
201
        - js: str, JavaScript code to execute
202
        
203
        Returns:
204
        Execution result from ChakraCore
205
        """
206
```
207

208
#### Usage Examples
209

210
```python
211
# Windows-optimized interpreter
212
scraper = cloudscraper.create_scraper(interpreter='chakracore')
213

214
# Requires ChakraCore binaries
215
# Download from: https://github.com/VeNoMouS/cloudscraper/tree/ChakraCore/
216
response = scraper.get('https://windows-optimized-site.com')
217
```
218

219
### Native Interpreter
220

221
Self-contained Python implementation for solving challenges without external JavaScript engines.
222

223
```python { .api }
224
class ChallengeInterpreter(JavaScriptInterpreter):
225
    def __init__(self):
226
        """Initialize native Python interpreter."""
227

228
    def eval(self, jsEnv: str, js: str):
229
        """
230
        Execute JavaScript using native Python implementation.
231
        
232
        Parameters:
233
        - jsEnv: str, JavaScript environment code
234
        - js: str, JavaScript code to execute
235
        
236
        Returns:
237
        Execution result from native implementation
238
        """
239
```
240

241
#### Usage Examples
242

243
```python
244
# No external dependencies required
245
scraper = cloudscraper.create_scraper(interpreter='native')
246

247
# Limited to simpler challenges
248
response = scraper.get('https://simple-protected-site.com')
249

250
# Good fallback option
251
interpreters = ['js2py', 'nodejs', 'v8', 'native']
252
for interpreter in interpreters:
253
    try:
254
        scraper = cloudscraper.create_scraper(interpreter=interpreter)
255
        response = scraper.get('https://protected-site.com')
256
        print(f"Success with {interpreter}")
257
        break
258
    except Exception as e:
259
        print(f"Failed with {interpreter}: {e}")
260
        continue
261
```
262

263
## Interpreter Selection and Compatibility
264

265
### Recommended Interpreters by Challenge Type
266

267
Different challenge types work better with specific interpreters:
268

269
```python
270
# Challenge type recommendations
271
challenge_interpreters = {
272
    'v1_challenges': ['js2py', 'nodejs', 'native'],
273
    'v2_challenges': ['js2py', 'nodejs', 'v8'],
274
    'v3_challenges': ['js2py', 'nodejs'],        # js2py highly recommended
275
    'complex_js': ['nodejs', 'v8', 'js2py'],
276
    'simple_js': ['native', 'js2py']
277
}
278

279
# For maximum v3 compatibility
280
scraper = cloudscraper.create_scraper(
281
    interpreter='js2py',
282
    delay=5  # Allow extra time for complex v3 challenges
283
)
284
```
285

286
### Interpreter Testing and Fallback
287

288
Test different interpreters to find the most compatible one:
289

290
```python
291
def test_interpreters(url, interpreters=['js2py', 'nodejs', 'v8', 'native']):
292
    """Test different interpreters for a specific site."""
293
    results = {}
294
    
295
    for interpreter in interpreters:
296
        try:
297
            scraper = cloudscraper.create_scraper(
298
                interpreter=interpreter,
299
                debug=True  # See which challenges are detected
300
            )
301
            response = scraper.get(url)
302
            results[interpreter] = {
303
                'status': response.status_code,
304
                'success': response.status_code == 200,
305
                'error': None
306
            }
307
            print(f"✅ {interpreter}: Success ({response.status_code})")
308
            
309
        except Exception as e:
310
            results[interpreter] = {
311
                'status': None,
312
                'success': False, 
313
                'error': str(e)
314
            }
315
            print(f"❌ {interpreter}: Failed - {e}")
316
    
317
    return results
318

319
# Test site with different interpreters
320
results = test_interpreters('https://protected-site.com')
321
```
322

323
### Performance Considerations
324

325
Different interpreters have different performance characteristics:
326

327
```python
328
# Performance ranking (fastest to slowest)
329
performance_ranking = [
330
    'v8',          # Native C++ V8 engine
331
    'chakracore',  # Native ChakraCore engine  
332
    'nodejs',      # Node.js subprocess (overhead but fast execution)
333
    'js2py',       # Pure Python (slower but very compatible)
334
    'native'       # Limited Python implementation
335
]
336

337
# For performance-critical applications
338
scraper = cloudscraper.create_scraper(
339
    interpreter='v8',
340
    delay=3  # Faster interpreter may need less delay
341
)
342

343
# For maximum compatibility  
344
scraper = cloudscraper.create_scraper(
345
    interpreter='js2py',
346
    delay=5  # More conservative timing
347
)
348
```
349

350
## Advanced Interpreter Configuration
351

352
### Custom Interpreter Environment
353

354
Configure interpreter-specific settings:
355

356
```python
357
# Different interpreters may support different configurations
358
scraper = cloudscraper.create_scraper(
359
    interpreter='js2py',
360
    debug=True  # See JavaScript execution details
361
)
362

363
# Some interpreters work better with specific delays
364
interpreter_delays = {
365
    'js2py': 5,
366
    'nodejs': 3,
367
    'v8': 2,
368
    'chakracore': 3,
369
    'native': 5
370
}
371

372
interpreter = 'js2py'
373
scraper = cloudscraper.create_scraper(
374
    interpreter=interpreter,
375
    delay=interpreter_delays.get(interpreter, 5)
376
)
377
```
378

379
### Interpreter Error Handling
380

381
Handle interpreter-specific errors:
382

383
```python
384
try:
385
    scraper = cloudscraper.create_scraper(interpreter='v8')
386
    response = scraper.get('https://protected-site.com')
387
    
388
except ImportError:
389
    print("V8 not available, trying Node.js")
390
    try:
391
        scraper = cloudscraper.create_scraper(interpreter='nodejs')
392
        response = scraper.get('https://protected-site.com')
393
    except Exception:
394
        print("Node.js failed, falling back to js2py")
395
        scraper = cloudscraper.create_scraper(interpreter='js2py')
396
        response = scraper.get('https://protected-site.com')
397
        
398
except cloudscraper.CloudflareSolveError as e:
399
    print(f"JavaScript execution failed: {e}")
400
    print("Try a different interpreter or check the challenge type")
401
```
402

403
### Dynamic Interpreter Selection
404

405
Automatically select the best available interpreter:
406

407
```python
408
def get_best_interpreter():
409
    """Select the best available interpreter."""
410
    # Try interpreters in preference order
411
    preferred_order = ['v8', 'nodejs', 'js2py', 'native']
412
    
413
    for interpreter in preferred_order:
414
        try:
415
            # Test interpreter availability
416
            test_scraper = cloudscraper.create_scraper(interpreter=interpreter)
417
            return interpreter
418
        except ImportError:
419
            continue
420
    
421
    # Default fallback
422
    return 'js2py'
423

424
# Use best available interpreter
425
best_interpreter = get_best_interpreter()
426
scraper = cloudscraper.create_scraper(interpreter=best_interpreter)
427
print(f"Using interpreter: {best_interpreter}")
428
```
429

430
## Troubleshooting Interpreters
431

432
### Common Issues and Solutions
433

434
```python
435
# Issue: ImportError when using specific interpreter
436
try:
437
    scraper = cloudscraper.create_scraper(interpreter='v8')
438
except ImportError:
439
    print("Install v8eval: pip install v8eval")
440

441
# Issue: CloudflareSolveError during JavaScript execution
442
try:
443
    scraper = cloudscraper.create_scraper(interpreter='js2py', debug=True)
444
    response = scraper.get('https://protected-site.com')
445
except cloudscraper.CloudflareSolveError as e:
446
    print(f"JavaScript execution failed: {e}")
447
    print("Try different interpreter or check challenge complexity")
448

449
# Issue: Timeout during challenge solving
450
scraper = cloudscraper.create_scraper(
451
    interpreter='js2py',
452
    delay=10,  # Increase delay for slow interpreters
453
    debug=True  # See execution progress
454
)
455
```
456

457
### Interpreter Debugging
458

459
Enable debug mode to see interpreter execution:
460

461
```python
462
scraper = cloudscraper.create_scraper(
463
    interpreter='js2py',
464
    debug=True
465
)
466

467
response = scraper.get('https://protected-site.com')
468

469
# Debug output shows:
470
# "Using js2py interpreter for challenge solving"
471
# "Executing JavaScript challenge code..."
472
# "Challenge solved with result: 1234.5678901234"
473
```