0
# GraalPy Python Launcher
1

2
GraalPy Python Launcher is a command-line executable that provides a Python-compatible interface for running Python applications on GraalVM. It serves as the entry point for GraalPy, Oracle's high-performance Python implementation built on the JVM, offering seamless Java integration, JIT compilation, and native image capabilities.
3

4
## Package Information
5

6
- **Package Name**: python-launcher
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: org.graalvm.python
10
- **Artifact ID**: python-launcher
11
- **Installation**: 
12
  - Maven: `<dependency><groupId>org.graalvm.python</groupId><artifactId>python-launcher</artifactId><version>24.2.1</version></dependency>`
13
  - Gradle: `implementation 'org.graalvm.python:python-launcher:24.2.1'`
14
  - Typically bundled with GraalVM or GraalPy distributions as `graalpy` executable
15

16
**Note**: This artifact provides the command-line launcher. For embedding GraalPy in Java applications, use the separate `org.graalvm.python:python-embedding` artifact.
17

18
## Core Usage
19

20
The launcher is designed to be invoked as an executable rather than used as a library. It provides a Python-compatible command-line interface:
21

22
```bash
23
# Basic script execution
24
graalpy script.py
25

26
# Interactive REPL
27
graalpy
28

29
# Execute code string
30
graalpy -c "print('Hello, World!')"
31

32
# Run module as script
33
graalpy -m module_name
34
```
35

36
## Basic Usage
37

38
```bash
39
# Execute a Python script
40
graalpy my_script.py arg1 arg2
41

42
# Start interactive Python shell
43
graalpy -i
44

45
# Execute Python code directly
46
graalpy -c "import sys; print(sys.version)"
47

48
# Run a module with arguments
49
graalpy -m http.server 8080
50

51
# Verbose mode with environment ignore
52
graalpy -v -E script.py
53
```
54

55
## Capabilities
56

57
### Command-Line Execution
58

59
The launcher provides Python-compatible command-line execution with standard Python options and behavior.
60

61
```java { .api }
62
public final class GraalPythonMain extends AbstractLanguageLauncher {
63
    /**
64
     * Creates a new GraalPythonMain launcher instance
65
     */
66
    public GraalPythonMain();
67
    
68
    /**
69
     * Main entry point for the GraalPy launcher
70
     * @param args Command line arguments (Python-compatible options and script/module)
71
     */
72
    public static void main(String[] args);
73
    
74
    /**
75
     * Preprocesses command line arguments before context creation
76
     * @param givenArgs Raw command line arguments
77
     * @param polyglotOptions Options map to populate
78
     * @return Processed arguments list
79
     */
80
    protected List<String> preprocessArguments(List<String> givenArgs, Map<String, String> polyglotOptions);
81
    
82
    /**
83
     * Validates arguments and options before execution
84
     * @param polyglotOptions Options map to validate
85
     */
86
    protected void validateArguments(Map<String, String> polyglotOptions);
87
    
88
    /**
89
     * Launches the Python context with the given configuration
90
     * @param contextBuilder Configured context builder
91
     */
92
    protected void launch(Context.Builder contextBuilder);
93
    
94
    /**
95
     * Returns the language identifier for GraalPy
96
     * @return "python"
97
     */
98
    protected String getLanguageId();
99
    
100
    /**
101
     * Returns default languages supported by this launcher
102
     * @return Array containing "python", "llvm", "regex"
103
     */
104
    protected String[] getDefaultLanguages();
105
    
106
    /**
107
     * Prints help message for command line options
108
     * @param maxCategory Maximum option category to display
109
     */
110
    protected void printHelp(OptionCategory maxCategory);
111
    
112
    /**
113
     * Collects available command line options
114
     * @param options Set to populate with option names
115
     */
116
    protected void collectArguments(Set<String> options);
117
}
118
```
119

120
### Script Execution Options
121

122
**File Execution:**
123
- `graalpy script.py` - Execute Python script file
124
- `graalpy script.py arg1 arg2` - Execute with command-line arguments
125

126
**Code String Execution:**
127
- `graalpy -c "code"` - Execute Python code string
128
- `graalpy -c "import os; print(os.getcwd())"` - Execute with imports
129

130
**Module Execution:**
131
- `graalpy -m module` - Run library module as script
132
- `graalpy -m http.server 8080` - Run built-in HTTP server
133
- `graalpy -m pip install package` - Run pip for package management
134

135
### Interactive Mode
136

137
**REPL (Read-Eval-Print Loop):**
138
- `graalpy` - Start interactive Python shell
139
- `graalpy -i` - Force interactive mode
140
- `graalpy -i script.py` - Interactive after script execution
141

142
**Console Features:**
143
- Command history (when JLine is available)
144
- Tab completion for Python objects and modules
145
- Multi-line input support for code blocks
146
- Standard Python prompts (`>>>` and `...`)
147

148
### Command-Line Options
149

150
**Python Compatibility Options:**
151
- `-c cmd` - Program passed as string
152
- `-m mod` - Run library module as script
153
- `-i` - Inspect interactively after running script
154
- `-v` - Verbose (trace import statements)
155
- `-q` - Quiet (don't print version messages)
156
- `-E` - Ignore PYTHON* environment variables
157
- `-B` - Don't write .pyc files
158
- `-S` - Don't imply 'import site' on initialization
159
- `-u` - Unbuffered binary stdout and stderr
160
- `-I` - Isolated mode (implies -E, -P, -s)
161
- `-P` - Don't prepend potentially unsafe path to sys.path
162
- `-s` - Don't add user site directory to sys.path
163
- `-V` / `--version` - Print version and exit
164
- `-h` / `--help` - Print help message
165
- `-W arg` - Warning control
166
- `-X opt` - Implementation-specific options
167

168
**Environment Variable Support:**
169
- `PYTHONPATH` - Module search path
170
- `PYTHONHOME` - Python installation directory  
171
- `PYTHONIOENCODING` - Encoding for stdin/stdout/stderr
172
- `PYTHONHASHSEED` - Hash randomization seed
173
- `PYTHONPYCACHEPREFIX` - Cache directory prefix
174
- `PYTHONINSPECT` - Force interactive mode after script execution
175
- `PYTHONNOUSERSITE` - Don't add user site directory to sys.path
176
- `PYTHONSAFEPATH` - Don't prepend potentially unsafe path to sys.path
177
- `PYTHONVERBOSE` - Verbose mode (trace import statements)
178
- `PYTHONUNBUFFERED` - Unbuffered binary stdout and stderr
179
- `PYTHONDONTWRITEBYTECODE` - Don't write .pyc files
180
- `PYTHONINTMAXSTRDIGITS` - Maximum number of digits in string conversions
181
- `PYTHONWARNINGS` - Warning filter configuration
182
- `PYTHONSTARTUP` - File executed on interactive startup
183
- `PYTHONCASEOK` - Ignore case in import statements (Windows)
184
- `GRAAL_PYTHON_ARGS` - Additional launcher arguments
185
- `GRAAL_PYTHONHOME` - GraalPy-specific Python home directory
186
- `VERBOSE_GRAALVM_LAUNCHERS` - Enable launcher debugging output
187

188
### Console Handler API
189

190
Provides console input/output handling for interactive and non-interactive execution modes.
191

192
```java { .api }
193
/**
194
 * Abstract base class for console input/output handling
195
 */
196
abstract class ConsoleHandler {
197
    /**
198
     * Reads a line of input with optional prompting
199
     * @return Input line as string
200
     */
201
    public final String readLine();
202
    
203
    /**
204
     * Reads a line of input with prompt control
205
     * @param prompt Whether to display prompt
206
     * @return Input line as string
207
     */
208
    public abstract String readLine(boolean prompt);
209
    
210
    /**
211
     * Sets the prompt string for interactive input
212
     * @param prompt Prompt string to display
213
     */
214
    public abstract void setPrompt(String prompt);
215
    
216
    /**
217
     * Sets the polyglot context for the console
218
     * @param context Polyglot context instance
219
     */
220
    public void setContext(Context context);
221
    
222
    /**
223
     * Sets up readline functionality with history and completion
224
     * @param shouldRecord Function determining if input should be recorded
225
     * @param getSize Function returning history size
226
     * @param addItem Consumer for adding history items
227
     * @param getItem Function for retrieving history items by index
228
     * @param setItem BiConsumer for setting history items
229
     * @param removeItem Consumer for removing history items
230
     * @param clear Runnable for clearing history
231
     * @param completer Function providing tab completion
232
     */
233
    public void setupReader(BooleanSupplier shouldRecord, IntSupplier getSize, 
234
                          Consumer<String> addItem, IntFunction<String> getItem, 
235
                          BiConsumer<Integer, String> setItem, IntConsumer removeItem,
236
                          Runnable clear, Function<String, List<String>> completer);
237
    
238
    /**
239
     * Creates an input stream for console reading
240
     * @return InputStream for console input
241
     */
242
    public InputStream createInputStream();
243
    
244
    /**
245
     * Gets terminal width in characters
246
     * @return Terminal width (default: 80)
247
     */
248
    public int getTerminalWidth();
249
    
250
    /**
251
     * Gets terminal height in characters  
252
     * @return Terminal height (default: 25)
253
     */
254
    public int getTerminalHeight();
255
}
256

257
/**
258
 * JLine-based console handler with advanced terminal features
259
 * Provides history, tab completion, and line editing
260
 */
261
class JLineConsoleHandler extends ConsoleHandler {
262
    /**
263
     * Creates JLine console handler
264
     * @param inStream Input stream
265
     * @param outStream Output stream  
266
     * @param noPrompt Whether to suppress prompts
267
     */
268
    public JLineConsoleHandler(InputStream inStream, OutputStream outStream, boolean noPrompt);
269
}
270

271
/**
272
 * Basic console handler for non-interactive environments
273
 * Simple BufferedReader-based implementation
274
 */
275
class DefaultConsoleHandler extends ConsoleHandler {
276
    /**
277
     * Creates default console handler
278
     * @param in Input stream
279
     */
280
    public DefaultConsoleHandler(InputStream in);
281
}
282
```
283

284
### GraalVM Integration Features
285

286
**Polyglot Context:**
287
- Automatic GraalVM polyglot context creation
288
- Java interoperability when running on GraalVM
289
- Access to other GraalVM languages (JavaScript, Ruby, etc.)
290

291
**Performance Features:**
292
- JIT compilation for improved performance over CPython
293
- Native image support for fast startup and reduced memory footprint
294
- Optimized execution of pure Python code
295

296
**Virtual Environment Support:**
297
- Automatic detection of Python virtual environments
298
- Support for `pyvenv.cfg` configuration files
299
- Compatible with standard Python virtual environment tools
300

301
## Installation and Distribution
302

303
The python-launcher is typically distributed as part of:
304

305
1. **GraalVM Community/Enterprise Edition**: Bundled as the `python` or `graalpy` executable
306
2. **Standalone GraalPy**: Available as a standalone Python distribution
307
3. **Maven Artifact**: Can be included in Java projects for custom launcher scenarios
308

309
## Error Handling
310

311
The launcher handles various error conditions:
312

313
- **Script Errors**: Python exceptions are displayed with stack traces
314
- **Import Errors**: Module not found errors with search path information
315
- **Syntax Errors**: Python syntax errors with line numbers and context
316
- **Exit Codes**: Proper exit code propagation from Python scripts
317
- **Signal Handling**: Ctrl+C interrupt handling in interactive mode
318

319
## Examples
320

321
```bash
322
# Basic script execution
323
graalpy hello.py
324

325
# Script with arguments
326
graalpy process_data.py input.csv output.csv --format json
327

328
# Interactive exploration
329
graalpy -i -c "import numpy as np; data = np.array([1,2,3])"
330

331
# Module execution
332
graalpy -m json.tool input.json
333

334
# Performance benchmarking
335
graalpy -X warn_default_encoding benchmark.py
336

337
# Virtual environment usage
338
graalpy -m venv myenv
339
source myenv/bin/activate  # or myenv\Scripts\activate on Windows
340
graalpy -m pip install requests
341
graalpy app.py
342
```
343

344
## Types
345

346
```java { .api }
347
/**
348
 * Required imports for using GraalPythonMain
349
 */
350
import com.oracle.graal.python.shell.GraalPythonMain;
351
import com.oracle.graal.python.shell.ConsoleHandler;
352
import com.oracle.graal.python.shell.JLineConsoleHandler;
353
import com.oracle.graal.python.shell.DefaultConsoleHandler;
354

355
/**
356
 * GraalVM/Polyglot API imports (from org.graalvm.polyglot)
357
 */
358
import org.graalvm.polyglot.Context;
359
import org.graalvm.polyglot.Context.Builder;
360
import org.graalvm.options.OptionCategory;
361

362
/**
363
 * Standard Java imports used in API
364
 */
365
import java.io.InputStream;
366
import java.io.OutputStream;
367
import java.util.List;
368
import java.util.Map;
369
import java.util.Set;
370
import java.util.function.*;
371
```