WrapPyJ - Auto‑generate Java wrappers for any Python library — seamless, zero‑glue interoperability.

WrapPyJ is a Java wrappers generator for Python libraries, enabling seamless integration of Python functionality within Java applications. This project consists of generator module that work together to provide a complete solution for Python-Java interoperability.

<dependency>
    <groupId>tech.thegamedefault.wrappyj</groupId>
    <artifactId>generator</artifactId>
    <version>1.0.0</version>
</dependency>

WrapPyJ Why ?

🏗️ Project Architecture

WrapPyJ is organized as a multi-module Maven project with the following structure:

WrapPyJ/
├── generator/                    # Core wrapper generation engine
├── example-generator/           # Example of generating wrappers
├── example-wrapper-usage/       # Example of using generated wrappers
└── src/main/java/.../generated/ # Generated wrapper classes

📦 Module Overview

1. Generator Module (`generator/`)

Core Engine for Python Library Analysis and Java Wrapper Generation

Key Components for clients:

WrapPyJGenerator: Main entry point for wrapper generation
WrapPyJApp: To be used once Java wrappers are generated, to initialize required dependencies.

Key Components for devs:

PythonRuntimeManager: Handles Python runtime initialization and dependencies
PythonAnalyser: Analyzes Python library structure and metadata
- WPJInterpreter: Manages Python interpreter instances via JEP
JavaWrapperGenerator: Generates Java wrapper classes using JavaPoet

Features:

Automatic Analysis: Scans Python libraries to understand their structure
Java Code Generation: Creates type-safe Java wrapper classes
Dependency Management: Handles Python package dependencies
Cross-Platform Support: Works on Linux, macOS, and Windows

Dependencies:

JEP (Java Embedded Python): For Python-Java interop
JavaPoet: For Java code generation
Spring Boot: For application framework
Jackson: For JSON processing
Lombok: For reducing boilerplate code

Usage:

List<GeneratorRequest> requests = List.of(
    GeneratorRequest.builder()
        .importDependencyName("numpy")
        .library("numpy")
        .outputPath("./src/main/java")
        .basePackage("com.example.wrappers")
        .build()
);

WrapPyJGenerator.generate(requests);


WrapPyJApp.init(List.of("pandas", "numpy", "matplotlib"));

2. Example Generator Module (`example-generator/`)

Demonstration of Wrapper Generation Process

This module showcases how to use the generator to create Java wrappers for popular Python libraries.

What it demonstrates:

Multi-library Generation: Generates wrappers for numpy, pandas, and matplotlib
Selective Generation: Shows how to include only specific functions/classes
Build Integration: Demonstrates Maven integration for automated generation

Generated Libraries:

NumPy: Scientific computing library wrapper
Pandas: Data manipulation and analysis wrapper
Matplotlib: Plotting and visualization wrapper

Key Features:

Automated Build Process: Wrappers are generated during Maven compilation
Customizable Output: Configurable output paths and package names
Selective Inclusion: Can generate wrappers for specific parts of libraries

Example Configuration:

List<GeneratorRequest> requests = List.of(
    GeneratorRequest.builder()
        .importDependencyName("numpy")
        .library("numpy")
        .build(),
    GeneratorRequest.builder()
        .importDependencyName("pandas")
        .library("pandas")
        .build(),
    GeneratorRequest.builder()
        .importDependencyName("matplotlib")
        .library("matplotlib.pyplot")
        .build()
);

3. Example Wrapper Usage Module (`example-wrapper-usage/`)

Demonstration of Using Generated Wrappers

This module shows how to use the generated Java wrappers in real applications, providing practical examples of Python-Java integration.

Demonstrations:

NumPy Integration (`TheNumpy.java`)

// Perform mathematical operations using NumPy
Object result = JNumpy.sum(List.of(1, 2, 3, 4, 5));
long actual = ((long[]) result)[0];

Pandas Data Analysis (`ThePandas.java`)

// Read CSV and perform data analysis
JDataFrame df = new JDataFrame(JPandas.read_csv(CSV_PATH));
Object head = df.head();
Object desc = df.describe();
Object groupBy = new JDataFrame(df.groupby("active")).sum();

Matplotlib Visualization (`TheMatplotlibPyplot.java`)

// Create plots and save images
Object xs = JNumpy.linspace(0, 6.28, 100);
Object ys = JNumpy.sin(xs);
JPyplot.plot(xs, ys);
JPyplot.title("Sine wave (from Java)");
JPyplot.savefig("./sine.png");

Key Features:

Spring Boot Integration: Shows how to integrate wrappers in Spring applications
Real-world Examples: Practical use cases for data analysis and visualization
Resource Management: Proper initialization and cleanup of Python interpreters
Error Handling: Demonstrates robust error handling patterns

🚀 Getting Started

Prerequisites

Java 19 or higher
Maven 3.6+
Python 3.10+ (embedded in the project)

Quick Start

Clone the repository
```
git clone <repository-url>
cd WrapPyJ
```
Build the project
```
mvn clean install
```
Generate wrappers (optional - already included)
```
cd example-generator
mvn clean compile
```
Note: The wrapper generation uses the Maven exec plugin to automatically run during the compile phase. See the Custom Wrapper Generation section for details on setting up your own generator.

Run the example application

cd example-wrapper-usage
mvn spring-boot:run

Custom Wrapper Generation

The recommended way to generate wrappers is using the Maven exec plugin, as demonstrated in the example-generator module.

Step 1: Create a Generator Class

Create a Java class similar to WrapPyJGeneratorExample:

package com.yourcompany.generator;

import java.util.List;
import tech.thegamedefault.wrappyj.generator.WrapPyJGenerator;
import tech.thegamedefault.wrappyj.generator.WrapPyJGenerator.GeneratorRequest;

public class YourLibraryGenerator {
    
    private static final List<GeneratorRequest> GENERATOR_REQUESTS = List.of(
        GeneratorRequest.builder()
            .importDependencyName("your-library")
            .library("your.library.module")
            .outputPath("./src/main/java")
            .basePackage("com.yourcompany.wrappers")
            .includeOnly(List.of("function1", "function2")) // Optional
            .build()
    );

    public static void main(String[] args) {
        WrapPyJGenerator.generate(GENERATOR_REQUESTS);
    }
}

Step 2: Configure Maven Exec Plugin

Add the exec-maven-plugin to your pom.xml:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>exec-maven-plugin</artifactId>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>java</goal>
            </goals>
            <configuration>
                <mainClass>com.yourcompany.generator.YourLibraryGenerator</mainClass>
                <classpathScope>compile</classpathScope>
            </configuration>
        </execution>
    </executions>
</plugin>

Step 3: Run the Generation

Execute the generation as part of your Maven build:

mvn clean package exec:java

Or run it during the compile phase:

mvn clean compile

Alternative: Direct Java Execution

You can also run the generator directly in Java code:

List<GeneratorRequest> requests = List.of(
    GeneratorRequest.builder()
        .importDependencyName("your-library")
        .library("your.library.module")
        .outputPath("./src/main/java")
        .basePackage("com.yourcompany.wrappers")
        .includeOnly(List.of("function1", "function2")) // Optional
        .build()
);

WrapPyJGenerator.generate(requests);

🔧 Configuration

Generator Configuration

Output Path: Where generated Java files will be placed
Base Package: Java package name for generated classes
Include Only: Specific functions/classes to include (optional)
Import Dependencies: Python package names to install

Runtime Configuration

Python Interpreter: Managed automatically by JEP
Memory Management: Automatic cleanup of Python objects
Error Handling: Comprehensive exception handling

📊 Generated Wrapper Structure

Generated wrappers follow a consistent pattern:

generated/
├── library_name/
│   ├── JLibraryName.java          # Main library wrapper
│   ├── JClassName.java            # Class wrappers
│   └── JFunctionName.java         # Function wrappers

Each wrapper provides:

Type-safe method calls to Python functions [** Not supported for all libraries, part of next milestone]
Automatic parameter conversion between Java and Python types
Exception handling for Python errors
Resource management for Python objects

🛠️ Development Workflow

Analysis Phase: PythonAnalyser scans the target library
Generation Phase: JavaWrapperGenerator creates Java classes
Integration Phase: Generated wrappers are used in Java applications
Runtime Phase: WPJInterpreter manages Python execution

🔍 Troubleshooting

Common Issues:

Python Import Errors: Ensure Python packages are installed
Memory Issues: Check JEP memory configuration
Type Conversion: Verify parameter types match expected Python types

Debug Mode:

Enable debug logging to see detailed generation and execution information.

📈 Performance Considerations

Lazy Loading: Python modules are loaded only when needed
Object Pooling: Reuses Python interpreter instances
Memory Management: Automatic cleanup of Python objects
Batch Operations: Efficient handling of multiple operations

🔒 Security

Sandboxed Execution: Python code runs in controlled environment
Input Validation: Automatic validation of parameters
Resource Limits: Configurable limits on Python operations

📝 License

This project is licensed under the terms specified in the LICENSE file.

🤝 Contributing

Contributions are welcome! Please see our Contributing Guidelines for detailed information on:

🛠️ Development setup and environment configuration
📝 Coding standards and best practices
🧪 Testing guidelines and requirements
🔄 Pull request process and review checklist
🐛 Issue reporting templates
🚀 Release process and versioning
👥 Community guidelines and code of conduct

We appreciate all contributions, from bug reports to feature requests to code improvements!

📞 Support

For support and questions:

Create an issue in the repository
Check the documentation
Review the example modules for usage patterns

WrapPyJ - Auto‑generate Java wrappers for any Python library — seamless, zero‑glue interop.

Name		Name	Last commit message	Last commit date
assets		assets
example-generator		example-generator
example-wrapper-usage		example-wrapper-usage
generator		generator
scripts/python/framework		scripts/python/framework
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
mvnw		mvnw
mvnw.cmd		mvnw.cmd
pom.xml		pom.xml

Latest commit

History

Folders and files

Repository files navigation

WrapPyJ - Auto‑generate Java wrappers for any Python library — seamless, zero‑glue interoperability.

WrapPyJ Why ?

🏗️ Project Architecture

📦 Module Overview

1. Generator Module (generator/)

Key Components for clients:

Key Components for devs:

Features:

Dependencies:

Usage:

2. Example Generator Module (example-generator/)

What it demonstrates:

Generated Libraries:

Key Features:

Example Configuration:

3. Example Wrapper Usage Module (example-wrapper-usage/)

Demonstrations:

NumPy Integration (TheNumpy.java)

Pandas Data Analysis (ThePandas.java)

Matplotlib Visualization (TheMatplotlibPyplot.java)

Key Features:

🚀 Getting Started

Prerequisites

Quick Start

Custom Wrapper Generation

Step 1: Create a Generator Class

Step 2: Configure Maven Exec Plugin

Step 3: Run the Generation

Alternative: Direct Java Execution

🔧 Configuration

Generator Configuration

Runtime Configuration

📊 Generated Wrapper Structure

🛠️ Development Workflow

🔍 Troubleshooting

Common Issues:

Debug Mode:

📈 Performance Considerations

🔒 Security

📝 License

🤝 Contributing

📞 Support

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

1. Generator Module (`generator/`)

2. Example Generator Module (`example-generator/`)

3. Example Wrapper Usage Module (`example-wrapper-usage/`)

NumPy Integration (`TheNumpy.java`)

Pandas Data Analysis (`ThePandas.java`)

Matplotlib Visualization (`TheMatplotlibPyplot.java`)