0
# DukPy
1

2
A simple JavaScript interpreter for Python built on top of the duktape engine without any external dependencies. DukPy provides comprehensive JavaScript execution environment within Python applications and includes built-in transpilers for popular JavaScript preprocessors including CoffeeScript, BabelJS, TypeScript, JSX, and LESS.
3

4
## Package Information
5

6
- **Package Name**: dukpy
7
- **Language**: Python
8
- **Installation**: `pip install dukpy`
9

10
## Core Imports
11

12
```python
13
import dukpy
14
```
15

16
For specific functionality:
17

18
```python
19
from dukpy import evaljs, JSInterpreter, coffee_compile, babel_compile, jsx_compile, typescript_compile, less_compile, install_jspackage
20
from dukpy.nodelike import NodeLikeInterpreter
21
from dukpy.module_loader import JSModuleLoader
22
```
23

24
## Basic Usage
25

26
```python
27
import dukpy
28

29
# One-off JavaScript execution
30
result = dukpy.evaljs("5 + 3")
31
print(result)  # 8
32

33
# Passing Python variables to JavaScript
34
result = dukpy.evaljs("dukpy.value * 2", value=10)
35
print(result)  # 20
36

37
# Persistent JavaScript interpreter
38
interpreter = dukpy.JSInterpreter()
39
interpreter.evaljs("var counter = 0")
40
counter = interpreter.evaljs("++counter")
41
print(counter)  # 1
42

43
# JavaScript transpilation
44
es6_code = "const greeting = (name) => `Hello, ${name}!`"
45
compiled = dukpy.babel_compile(es6_code)
46
print(compiled['code'])
47

48
# CoffeeScript compilation  
49
coffee_code = "greeting = (name) -> \"Hello, #{name}!\""
50
js_code = dukpy.coffee_compile(coffee_code)
51
print(js_code)
52
```
53

54
## Architecture
55

56
DukPy provides multiple layers of JavaScript integration:
57

58
- **Core Interpreter**: The `_dukpy` C extension wraps the duktape JavaScript engine
59
- **evaljs**: Simple one-off JavaScript execution with automatic cleanup
60
- **JSInterpreter**: Persistent JavaScript context with module loading capabilities  
61
- **Module System**: CommonJS-compatible module loading with filesystem integration
62
- **Transpilers**: Built-in support for popular JavaScript/CSS preprocessors
63
- **WebAssets**: Integration filters for asset pipeline automation
64
- **Package Management**: npm package installation with dependency resolution
65

66
## Capabilities
67

68
### JavaScript Evaluation
69

70
Core JavaScript execution functionality supporting both one-off evaluation and persistent interpreter contexts with variable passing, module loading, and Python function exports.
71

72
```python { .api }
73
def evaljs(code, **kwargs):
74
    """Evaluates JavaScript code and returns the result"""
75

76
class JSInterpreter:
77
    def evaljs(self, code, **kwargs):
78
        """Runs JavaScript code in persistent context"""
79
    def export_function(self, name, func):
80
        """Exports Python function to JavaScript"""
81
```
82

83
[JavaScript Evaluation](./javascript-evaluation.md)
84

85
### JavaScript Transpilers
86

87
Built-in compilation support for modern JavaScript dialects and preprocessors including CoffeeScript, ES6+ via Babel, TypeScript, JSX, and LESS CSS preprocessing.
88

89
```python { .api }
90
def coffee_compile(source):
91
    """Compiles CoffeeScript to JavaScript"""
92
    
93
def babel_compile(source, **kwargs):
94
    """Compiles ES6+ to ES5 using BabelJS"""
95
    
96
def jsx_compile(source, **kwargs):
97
    """Compiles JSX to React-compatible JavaScript"""
98
    
99
def typescript_compile(source):
100
    """Compiles TypeScript to ES5"""
101
    
102
def less_compile(source, options=None):
103
    """Compiles LESS to CSS"""
104
```
105

106
[Transpilers](./transpilers.md)
107

108
### Package Management
109

110
npm package installation with automatic dependency resolution, enabling JavaScript module usage within Python applications through the persistent interpreter's require() system.
111

112
```python { .api }
113
def install_jspackage(package_name, version, modulesdir):
114
    """Installs JavaScript packages from npmjs.org"""
115
```
116

117
[Package Management](./package-management.md)
118

119
### Command Line Interface
120

121
Built-in CLI tools for package installation and JavaScript execution, available as console scripts after installation.
122

123
```python { .api }
124
def main():
125
    """
126
    CLI entry point for running JavaScript files.
127
    Available as 'dukpy' command after installation.
128
    Supports shebang removal and uses NodeLikeInterpreter.
129
    """
130
```
131

132
Usage:
133

134
```bash
135
# Install JavaScript packages
136
dukpy-install react 16.14.0 ./js_modules
137

138
# Run JavaScript files  
139
dukpy script.js
140
```
141

142
### WebAssets Integration
143

144
Filter classes for integrating JavaScript transpilation into WebAssets asset pipeline, supporting automatic compilation of CoffeeScript, ES6+, TypeScript, JSX, and LESS in web applications.
145

146
```python { .api }
147
class BabelJS(Filter):
148
    """WebAssets filter for ES6+ compilation"""
149
    
150
class TypeScript(Filter):
151
    """WebAssets filter for TypeScript compilation"""
152
    
153
class CompileLess(Filter):
154
    """WebAssets filter for LESS compilation"""
155
    
156
class BabelJSX(Filter):
157
    """WebAssets filter for JSX compilation"""
158
```
159

160
[WebAssets](./webassets.md)
161

162
## Types
163

164
```python { .api }
165
class JSRuntimeError(Exception):
166
    """Exception raised when JavaScript execution fails"""
167

168
class JSPackageInstallError(Exception):
169
    """Exception raised when package installation fails"""
170
    def __init__(self, msg, error_code):
171
        super().__init__(msg)
172
        self.error_code = error_code
173

174
class LessCompilerError(Exception):
175
    """Exception raised when LESS compilation fails"""
176

177
class JSModuleLoader:
178
    """Manages finding and loading JS modules in CommonJS format"""
179
    def register_path(self, path):
180
        """Registers a directory where to look for modules"""
181
    def lookup(self, module_name):
182
        """Searches for a file providing given module"""
183
    def load(self, module_name):
184
        """Returns source code and normalized module id"""
185

186
class NodeLikeInterpreter(JSInterpreter):
187
    """A DukPy Interpreter that provides a minimal compatibility layer with NodeJS"""
188
    def __init__(self):
189
        """Creates NodeLikeInterpreter with filesystem and jscore module support"""
190

191
class FS:
192
    """Provides oversimplified fs.js native functions for JavaScript"""
193
    @classmethod
194
    def exists(cls, filepath):
195
        """Checks if a file or directory exists"""
196
    @classmethod  
197
    def read(cls, path, encoding):
198
        """Reads file contents with optional encoding"""
199
```