tessl/pypi-cloudscraper

Enhanced Python module to bypass Cloudflare's anti-bot page with support for v1, v2, v3 challenges, Turnstile, proxy rotation, and stealth mode.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

JavaScript Interpreters

Name: tessl/pypi-cloudscraper
Author: tessl

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.

Capabilities

Base Interpreter Interface

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

class JavaScriptInterpreter:
    def __init__(self, name: str):
        """
        Initialize JavaScript interpreter.
        
        Parameters:
        - name: str, interpreter identifier
        """

    @classmethod
    def dynamicImport(cls, name: str):
        """
        Dynamically import and initialize interpreter.
        
        Parameters:
        - name: str, interpreter name to load
        
        Returns:
        JavaScriptInterpreter instance
        
        Raises:
        - ImportError: If interpreter cannot be loaded
        """

    def eval(self, jsEnv: str, js: str):
        """
        Execute JavaScript code in given environment.
        
        Parameters:
        - jsEnv: str, JavaScript environment/context
        - js: str, JavaScript code to execute
        
        Returns:
        Execution result
        
        Raises:
        - CloudflareSolveError: If JavaScript execution fails
        """

    def solveChallenge(self, body: str, domain: str) -> str:
        """
        Solve Cloudflare challenge using JavaScript execution.
        
        Parameters:
        - body: str, challenge JavaScript code
        - domain: str, target domain
        
        Returns:
        str: Challenge solution as formatted float
        
        Raises:
        - CloudflareSolveError: If challenge cannot be solved
        """

js2py Interpreter

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

class ChallengeInterpreter(JavaScriptInterpreter):
    def __init__(self):
        """Initialize js2py interpreter."""

    def eval(self, jsEnv: str, js: str):
        """
        Execute JavaScript using js2py library.
        
        Parameters:
        - jsEnv: str, JavaScript environment code
        - js: str, JavaScript code to execute
        
        Returns:
        Execution result from js2py
        """

Usage Examples

# js2py is the default interpreter
scraper = cloudscraper.create_scraper()  # Uses js2py

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

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

Node.js Interpreter

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

class ChallengeInterpreter(JavaScriptInterpreter):
    def __init__(self):
        """Initialize Node.js interpreter."""

    def eval(self, jsEnv: str, js: str):
        """
        Execute JavaScript using Node.js subprocess.
        
        Parameters:
        - jsEnv: str, JavaScript environment code
        - js: str, JavaScript code to execute
        
        Returns:
        Execution result from Node.js
        
        Raises:
        - CloudflareSolveError: If Node.js execution fails
        """

Usage Examples

# Requires Node.js installed on system
scraper = cloudscraper.create_scraper(interpreter='nodejs')

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

# Check if Node.js is available
import subprocess
try:
    subprocess.check_output(['node', '--version'])
    scraper = cloudscraper.create_scraper(interpreter='nodejs')
except FileNotFoundError:
    print("Node.js not available, falling back to js2py")
    scraper = cloudscraper.create_scraper(interpreter='js2py')

V8 Interpreter

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

class ChallengeInterpreter(JavaScriptInterpreter):
    def __init__(self):
        """Initialize V8 interpreter."""

    def eval(self, jsEnv: str, js: str):
        """
        Execute JavaScript using V8 engine.
        
        Parameters:
        - jsEnv: str, JavaScript environment code
        - js: str, JavaScript code to execute
        
        Returns:
        Execution result from V8
        """

Usage Examples

# Requires v8eval Python package
scraper = cloudscraper.create_scraper(interpreter='v8')

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

# Install v8eval: pip install v8eval
try:
    scraper = cloudscraper.create_scraper(interpreter='v8')
except ImportError:
    print("V8 not available, using js2py")
    scraper = cloudscraper.create_scraper(interpreter='js2py')

ChakraCore Interpreter

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

class ChallengeInterpreter(JavaScriptInterpreter):
    def __init__(self):
        """Initialize ChakraCore interpreter."""

    def eval(self, jsEnv: str, js: str):
        """
        Execute JavaScript using ChakraCore engine.
        
        Parameters:
        - jsEnv: str, JavaScript environment code
        - js: str, JavaScript code to execute
        
        Returns:
        Execution result from ChakraCore
        """

Usage Examples

# Windows-optimized interpreter
scraper = cloudscraper.create_scraper(interpreter='chakracore')

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

Native Interpreter

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

class ChallengeInterpreter(JavaScriptInterpreter):
    def __init__(self):
        """Initialize native Python interpreter."""

    def eval(self, jsEnv: str, js: str):
        """
        Execute JavaScript using native Python implementation.
        
        Parameters:
        - jsEnv: str, JavaScript environment code
        - js: str, JavaScript code to execute
        
        Returns:
        Execution result from native implementation
        """

Usage Examples

# No external dependencies required
scraper = cloudscraper.create_scraper(interpreter='native')

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

# Good fallback option
interpreters = ['js2py', 'nodejs', 'v8', 'native']
for interpreter in interpreters:
    try:
        scraper = cloudscraper.create_scraper(interpreter=interpreter)
        response = scraper.get('https://protected-site.com')
        print(f"Success with {interpreter}")
        break
    except Exception as e:
        print(f"Failed with {interpreter}: {e}")
        continue

Interpreter Selection and Compatibility

Recommended Interpreters by Challenge Type

Different challenge types work better with specific interpreters:

# Challenge type recommendations
challenge_interpreters = {
    'v1_challenges': ['js2py', 'nodejs', 'native'],
    'v2_challenges': ['js2py', 'nodejs', 'v8'],
    'v3_challenges': ['js2py', 'nodejs'],        # js2py highly recommended
    'complex_js': ['nodejs', 'v8', 'js2py'],
    'simple_js': ['native', 'js2py']
}

# For maximum v3 compatibility
scraper = cloudscraper.create_scraper(
    interpreter='js2py',
    delay=5  # Allow extra time for complex v3 challenges
)

Interpreter Testing and Fallback

Test different interpreters to find the most compatible one:

def test_interpreters(url, interpreters=['js2py', 'nodejs', 'v8', 'native']):
    """Test different interpreters for a specific site."""
    results = {}
    
    for interpreter in interpreters:
        try:
            scraper = cloudscraper.create_scraper(
                interpreter=interpreter,
                debug=True  # See which challenges are detected
            )
            response = scraper.get(url)
            results[interpreter] = {
                'status': response.status_code,
                'success': response.status_code == 200,
                'error': None
            }
            print(f"✅ {interpreter}: Success ({response.status_code})")
            
        except Exception as e:
            results[interpreter] = {
                'status': None,
                'success': False, 
                'error': str(e)
            }
            print(f"❌ {interpreter}: Failed - {e}")
    
    return results

# Test site with different interpreters
results = test_interpreters('https://protected-site.com')

Performance Considerations

Different interpreters have different performance characteristics:

# Performance ranking (fastest to slowest)
performance_ranking = [
    'v8',          # Native C++ V8 engine
    'chakracore',  # Native ChakraCore engine  
    'nodejs',      # Node.js subprocess (overhead but fast execution)
    'js2py',       # Pure Python (slower but very compatible)
    'native'       # Limited Python implementation
]

# For performance-critical applications
scraper = cloudscraper.create_scraper(
    interpreter='v8',
    delay=3  # Faster interpreter may need less delay
)

# For maximum compatibility  
scraper = cloudscraper.create_scraper(
    interpreter='js2py',
    delay=5  # More conservative timing
)

Advanced Interpreter Configuration

Custom Interpreter Environment

Configure interpreter-specific settings:

# Different interpreters may support different configurations
scraper = cloudscraper.create_scraper(
    interpreter='js2py',
    debug=True  # See JavaScript execution details
)

# Some interpreters work better with specific delays
interpreter_delays = {
    'js2py': 5,
    'nodejs': 3,
    'v8': 2,
    'chakracore': 3,
    'native': 5
}

interpreter = 'js2py'
scraper = cloudscraper.create_scraper(
    interpreter=interpreter,
    delay=interpreter_delays.get(interpreter, 5)
)

Interpreter Error Handling

Handle interpreter-specific errors:

try:
    scraper = cloudscraper.create_scraper(interpreter='v8')
    response = scraper.get('https://protected-site.com')
    
except ImportError:
    print("V8 not available, trying Node.js")
    try:
        scraper = cloudscraper.create_scraper(interpreter='nodejs')
        response = scraper.get('https://protected-site.com')
    except Exception:
        print("Node.js failed, falling back to js2py")
        scraper = cloudscraper.create_scraper(interpreter='js2py')
        response = scraper.get('https://protected-site.com')
        
except cloudscraper.CloudflareSolveError as e:
    print(f"JavaScript execution failed: {e}")
    print("Try a different interpreter or check the challenge type")

Dynamic Interpreter Selection

Automatically select the best available interpreter:

def get_best_interpreter():
    """Select the best available interpreter."""
    # Try interpreters in preference order
    preferred_order = ['v8', 'nodejs', 'js2py', 'native']
    
    for interpreter in preferred_order:
        try:
            # Test interpreter availability
            test_scraper = cloudscraper.create_scraper(interpreter=interpreter)
            return interpreter
        except ImportError:
            continue
    
    # Default fallback
    return 'js2py'

# Use best available interpreter
best_interpreter = get_best_interpreter()
scraper = cloudscraper.create_scraper(interpreter=best_interpreter)
print(f"Using interpreter: {best_interpreter}")

Troubleshooting Interpreters

Common Issues and Solutions

# Issue: ImportError when using specific interpreter
try:
    scraper = cloudscraper.create_scraper(interpreter='v8')
except ImportError:
    print("Install v8eval: pip install v8eval")

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

# Issue: Timeout during challenge solving
scraper = cloudscraper.create_scraper(
    interpreter='js2py',
    delay=10,  # Increase delay for slow interpreters
    debug=True  # See execution progress
)

Interpreter Debugging

Enable debug mode to see interpreter execution:

scraper = cloudscraper.create_scraper(
    interpreter='js2py',
    debug=True
)

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

# Debug output shows:
# "Using js2py interpreter for challenge solving"
# "Executing JavaScript challenge code..."
# "Challenge solved with result: 1234.5678901234"

Install with Tessl CLI