tessl/maven-org-bytedeco--cpython

JavaCPP bindings for CPython 3.13.5 enabling Java applications to embed Python interpreters and interact with Python objects through the Python C API

—

Pending

Overview

Eval results

Files

Python Interpreter Initialization

Name: tessl/maven-org-bytedeco--cpython
Author: tessl

Complete API for initializing and configuring Python interpreters within Java applications. This includes basic initialization, advanced configuration, pre-initialization setup, and proper cleanup procedures.

Capabilities

Basic Initialization

Simple initialization functions for common use cases where default configuration is sufficient.

/**
 * Initialize Python interpreter with default settings
 */
public static native void Py_Initialize();

/**
 * Initialize Python interpreter with signal handling control
 * @param initsigs - If non-zero, initialize signal handling
 */
public static native void Py_InitializeEx(int initsigs);

/**
 * Finalize Python interpreter and free all memory
 */
public static native void Py_Finalize();

/**
 * Finalize Python interpreter with error code return
 * @return 0 on success, -1 on error
 */
public static native int Py_FinalizeEx();

Usage Example:

import static org.bytedeco.cpython.global.python.*;

// Basic initialization
Py_Initialize();

// Your Python operations here
PyRun_SimpleString("print('Python is running!')");

// Always finalize when done
Py_Finalize();

Helper Initialization (Convenience Methods)

Simplified initialization methods provided by the helper library for common scenarios.

/**
 * Initialize Python with additional library paths
 * @param path - Additional paths to add to Python sys.path
 * @return true if initialization successful, false otherwise
 * @throws IOException if path operations fail
 */
public static boolean Py_Initialize(File... path) throws IOException;

/**
 * Initialize Python with additional library paths as strings
 * @param path - Additional paths to add to Python sys.path
 * @return true if initialization successful, false otherwise  
 * @throws IOException if path operations fail
 */
public static boolean Py_Initialize(String... path) throws IOException;

Usage Example:

import org.bytedeco.cpython.helper.python;

// Initialize with custom Python library paths
boolean success = python.Py_Initialize(
    "/usr/local/lib/python3.13",
    "/opt/myapp/python-modules"
);

if (success) {
    // Python ready to use
    PyRun_SimpleString("import sys; print(sys.path)");
}

Configuration-Based Initialization

Advanced initialization using configuration structures for fine-grained control over the Python interpreter.

/**
 * Initialize Python from configuration object
 * @param config - Configuration structure
 * @return Status indicating success or failure
 */
public static native PyStatus Py_InitializeFromConfig(PyConfig config);

/**
 * Initialize configuration with Python defaults
 * @param config - Configuration structure to initialize
 */
public static native void PyConfig_InitPythonConfig(PyConfig config);

/**
 * Initialize configuration in isolated mode
 * @param config - Configuration structure to initialize
 */
public static native void PyConfig_InitIsolatedConfig(PyConfig config);

/**
 * Clear and deallocate configuration structure
 * @param config - Configuration to clear
 */
public static native void PyConfig_Clear(PyConfig config);

/**
 * Set string value in configuration
 * @param config - Configuration structure
 * @param configField - Pointer to the field to set
 * @param value - String value to set
 * @return Status indicating success or failure
 */
public static native PyStatus PyConfig_SetString(PyConfig config, PointerPointer configField, Pointer value);

Usage Example:

import static org.bytedeco.cpython.global.python.*;

// Create and configure Python
PyConfig config = new PyConfig();
PyConfig_InitPythonConfig(config);

// Initialize with configuration
PyStatus status = Py_InitializeFromConfig(config);

if (!PyStatus_IsError(status)) {
    // Python initialized successfully
    PyRun_SimpleString("print('Configured Python running!')");
} else {
    System.err.println("Python initialization failed");
}

// Clean up configuration
PyConfig_Clear(config);

Pre-Initialization Configuration

Control Python interpreter behavior before main initialization occurs.

/**
 * Pre-initialize Python interpreter
 * @param src_config - Pre-initialization configuration
 * @return Status indicating success or failure
 */
public static native PyStatus Py_PreInitialize(PyPreConfig src_config);

/**
 * Pre-initialize from arguments
 * @param src_config - Pre-initialization configuration
 * @param argc - Argument count
 * @param argv - Argument vector
 * @return Status indicating success or failure
 */
public static native PyStatus Py_PreInitializeFromArgs(PyPreConfig src_config, int argc, PointerPointer argv);

/**
 * Initialize pre-configuration with defaults
 * @param config - Pre-configuration structure
 */
public static native void PyPreConfig_InitPythonConfig(PyPreConfig config);

/**
 * Initialize pre-configuration in isolated mode
 * @param config - Pre-configuration structure  
 */
public static native void PyPreConfig_InitIsolatedConfig(PyPreConfig config);

Status Management

Functions for checking and handling initialization status results.

/**
 * Check if status indicates an error
 * @param status - Status to check
 * @return Non-zero if error occurred
 */
public static native int PyStatus_IsError(PyStatus status);

/**
 * Check if status indicates exit was requested
 * @param status - Status to check
 * @return Non-zero if exit requested
 */
public static native int PyStatus_IsExit(PyStatus status);

/**
 * Check if status indicates an exception
 * @param status - Status to check
 * @return Non-zero if exception occurred
 */
public static native int PyStatus_Exception(PyStatus status);

Interpreter State Management

Functions for managing multiple Python interpreters and sub-interpreters.

/**
 * Create new interpreter configuration
 * @param config - Configuration structure to initialize
 */
public static native void PyInterpreterConfig_InitLegacyConfig(PyInterpreterConfig config);

/**
 * Get current interpreter state
 * @return Current interpreter state
 */
public static native PyInterpreterState PyInterpreterState_Get();

/**
 * Create new sub-interpreter
 * @param tstate_p - Pointer to receive new thread state
 * @param config - Interpreter configuration
 * @return Status indicating success or failure
 */
public static native PyStatus Py_NewInterpreterFromConfig(PointerPointer tstate_p, PyInterpreterConfig config);

Key Configuration Types

/**
 * Main Python configuration structure
 */
class PyConfig extends Pointer {
    // Contains all configuration options for Python initialization
    // Fields accessed through PyConfig_SetString and similar functions
}

/**
 * Pre-initialization configuration 
 */
class PyPreConfig extends Pointer {
    // Configuration applied before main Python initialization
    // Controls allocator, locale, and other low-level settings
}

/**
 * Status return structure for initialization operations
 */
class PyStatus extends Pointer {
    // Contains result of initialization operations
    // Check with PyStatus_IsError, PyStatus_IsExit functions
}

/**
 * Interpreter-specific configuration
 */
class PyInterpreterConfig extends Pointer {
    // Configuration for individual interpreter instances
    // Used with sub-interpreter creation
}

/**
 * Python interpreter state
 */
class PyInterpreterState extends Pointer {
    // Represents an individual Python interpreter instance
}

Advanced Usage Patterns

Custom Configuration Setup

import static org.bytedeco.cpython.global.python.*;

// Create isolated configuration
PyConfig config = new PyConfig();
PyConfig_InitIsolatedConfig(config);

// Set custom program name
// Note: String handling requires proper wide character conversion
// This is typically done through helper methods

PyStatus status = Py_InitializeFromConfig(config);

if (!PyStatus_IsError(status)) {
    // Python running in isolated mode
    // No access to system Python installation
    PyRun_SimpleString("import sys; print('Isolated Python:', sys.executable)");
    
    Py_Finalize();
} else {
    System.err.println("Isolated initialization failed");
}

PyConfig_Clear(config);

Multiple Interpreter Management

import static org.bytedeco.cpython.global.python.*;

// Initialize main interpreter
Py_Initialize();

// Create sub-interpreter configuration
PyInterpreterConfig config = new PyInterpreterConfig();
PyInterpreterConfig_InitLegacyConfig(config);

// Create sub-interpreter
PointerPointer tstate_p = new PointerPointer(1);
PyStatus status = Py_NewInterpreterFromConfig(tstate_p, config);

if (!PyStatus_IsError(status)) {
    PyThreadState subInterpreter = new PyThreadState(tstate_p.get());
    
    // Switch to sub-interpreter
    PyThreadState oldState = PyThreadState_Swap(subInterpreter);
    
    // Run code in sub-interpreter
    PyRun_SimpleString("print('Running in sub-interpreter')");
    
    // Switch back to main interpreter
    PyThreadState_Swap(oldState);
    
    // Clean up sub-interpreter
    PyThreadState_Clear(subInterpreter);
    PyThreadState_Delete(subInterpreter);
}

Py_Finalize();

Error Handling

Always check initialization status and handle errors appropriately:

PyStatus status = Py_InitializeFromConfig(config);

if (PyStatus_IsError(status)) {
    System.err.println("Python initialization failed");
    // Handle initialization error
    return;
}

if (PyStatus_IsExit(status)) {
    System.out.println("Python requested exit during initialization");
    // Handle exit request
    return;
}

// Initialization successful, proceed with Python operations

Important Notes

Thread Safety

Python initialization is not thread-safe. Ensure initialization occurs from a single thread before any other threads attempt to use Python APIs.

Memory Management

Configuration structures must be properly cleaned up with PyConfig_Clear() to prevent memory leaks.

Platform Considerations

The helper initialization methods handle platform-specific differences in Python installation paths and executable names automatically.

Install with Tessl CLI

npx tessl i tessl/maven-org-bytedeco--cpython

docs

tessl/maven-org-bytedeco--cpython

initialization.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Python Interpreter Initialization

Capabilities

Basic Initialization

Helper Initialization (Convenience Methods)

Configuration-Based Initialization

Pre-Initialization Configuration

Status Management

Interpreter State Management

Key Configuration Types

Advanced Usage Patterns

Custom Configuration Setup

Multiple Interpreter Management

Error Handling

Important Notes

Thread Safety

Memory Management

Platform Considerations

initialization.mddocs/