Jpype Documentation Release 0.7.5
Total Page:16
File Type:pdf, Size:1020Kb
JPype Documentation Release 0.7.5 Steve Menard, Luis Nell and others Aug 07, 2020 Contents 1 Parts of the documentation 3 1.1 Installation................................................3 1.2 JPype User Guide............................................5 1.3 Java QuickStart Guide.......................................... 47 1.4 API Reference.............................................. 57 1.5 JImport.................................................. 66 1.6 Changelog................................................ 67 1.7 Developer Guide............................................. 74 2 Indices and tables 89 Python Module Index 91 Index 93 i ii JPype Documentation, Release 0.7.5 JPype is a Python module to provide full access to Java from within Python. It allows Python to make use of Java spe- cific libraries, explore and visualize Java structures, develop and test Java libraries, make use of scientific computing, and much more. By enabling the use of Python for rapid prototyping and Java for strong typed production code, JPype provides a powerful environment for engineering and code development. Unlike Jython, JPype does not achive this by re-implementing Python, but instead by interfacing both virtual machines at the native level. This shared memory based approach achieves good computing performance, while providing the access to the entirety of CPython and Java libraries. Contents 1 JPype Documentation, Release 0.7.5 2 Contents CHAPTER 1 Parts of the documentation 1.1 Installation JPype is available either as a pre-compiled binary for Anaconda, or may be built from source though various methods. 1.1.1 Binary Install JPype can be installed as pre-compiled binary if you are using the Anaconda Python stack. Binaries are available for Linux, OSX, and windows on conda-forge. 1. Ensure you have installed Anaconda/Miniconda. Instructions can be found here. 2. Install from the conda-forge software channel: conda install-c conda-forge jpype1 1.1.2 Source Install Installing from source requires: Python JPype works CPython 3.5 or later. Both the runtime and the development package are required. Java Either the Sun/Oracle JDK/JRE Variant or OpenJDK. JPype source distribution includes a copy of the Java JNI header and precompiled Java code, thus the Java Development Kit (JDK) is not required. JPype has been tested with Java versions from Java 1.7 to Java 13. C++ A C++ compiler which matches the ABI used to build CPython. JDK (Optional) JPype contains sections of Java code. These sections are precompiled in the source distribution, but must be built when installing directly from the git repository. Once these requirements have been met, one can use pip to build from either the source distribution or directly from the repository. Specific requirements from different achitectures are listed below. 3 JPype Documentation, Release 0.7.5 Build using pip JPype may be built and installed with one step using pip. To install the latest JPype, use: pip install JPype1 This will install JPype either from source or binary distribution, depending on your operating system and pip version. To install from the current github master use: pip install git+https://github.com/jpype-project/jpype.git More details on installing from git can be found at Pip install. The git version does not include a prebuilt jar the JDK is required. Build and install manually JPype can be built entirely from source. 1. Get the JPype source The JPype source may be acquired from either github or from PyPi. 2. Build the source with desired options Compile JPype using the included setup.py script: python setup.py build The setup script recognizes several arguments. --enable-build-jar Force setup to recreate the jar from scratch. --enable-tracing Build a verison of JPype with full logging to the console. This can be used to diagnose tricky JNI issues. After building, JPype can be tested using the test bench. The test bench requires JDK to build. 3. Test JPype with (optional): python setup.py test 4. Install JPype with: python setup.py install If it fails. Most failures happen when setup.py is unable to find the JDK home directory which shouble be set in the enviroment variable JAVA_HOME. If this happens, preform the following steps: 1. Identify the location of your systems JDK installation and explicitly passing it to setup.py. JAVA_HOME=/usr/lib/java/jdk1.8.0/ python setup.py install 2. If that setup.py still fails please create an Issue on github and post the relevant logs. 4 Chapter 1. Parts of the documentation JPype Documentation, Release 0.7.5 Platform Specific requirements JPype is known to work on Linx, OSX, and Windows. To make it easier to those who have not built CPython modules before here are some helpful tips for different machines. Debian/Ubuntu Debian/Ubuntu users will have to install g++ and python-dev. Use: sudo apt-get install g++ python-dev python3-dev Windows CPython modules must be built with the same C++ compiler used to build Python. The tools listed below work for Python 3.5 to 3.8. Check with Python dev guide for the latest instructions. 1. Install your desired version of Python (3.5 or higher), e.g., Miniconda is a good choice for users not yet familiar with the language 2. For Python 3 series, Install either 2017 or 2019 Visual Studio. Microsoft Visual Studio 2019 Community Edition is known to work. From the Python developer page: When installing Visual Studio 2019, select the Python development workload and the optional Python native development tools component to obtain all of the necessary build tools. If you do not already have git installed, you can find git for Windows on the Individual components tab of the installer. When building for windows you must use the Visual Studio developer command prompt. 1.1.3 Path requirements On certain systems such as Windows 2016 Server, the JDK will not load properly despite JPype properly locating the JVM library. The work around for this issue is add the JRE bin directory to the system PATH. Apparently, the shared library requires dependencies which are located in the bin directory. If a JPype fails to load despite having the correct JAVA_HOME and system architecture, it may be this issue. 1.1.4 Known Bugs/Limitations • Java classes outside of a package (in the <default>) cannot be imported. • Because of lack of JVM support, you cannot shutdown the JVM and then restart it. Nor can you start more than one copy of the JVM. • Mixing 64 bit Python with 32 bit Java and vice versa crashes on import of the jpype module. 1.2 JPype User Guide 1.2.1 JPype Introduction JPype is a Python module to provide full access to Java from within Python. Unlike Jython, JPype does not achive this by re-implementing Python, but instead by interfacing both virtual machines at the native level. This shared memory 1.2. JPype User Guide 5 JPype Documentation, Release 0.7.5 based approach achieves good computing performance, while providing the access to the entirety of CPython and Java libraries. This approach allows direct memory access between the two machines, implementation of Java interfaces in Python, and even use of Java threading. JPype Use Cases Here are three typical reasons to use JPype. • Access to a Java library from a Python program (Python oriented) • Visualization of Java data structures (Java oriented) • Interactive Java and Python development including scientific and mathematical programming. Let’s explore each of these options. Case 1: Access to a Java library Suppose you are a hard core Python programmer. You can easily use lambdas, threading, dictionary hacking, monkey patching, been there, done that. You are hard at work on your latest project but you just need to pip in the database driver for your customers database and you can call it a night. Unfortunately, it appears that your customers database will not connect to the Python database API. The whole thing is custom and the customer isn’t going to supply you with a Python version. They did sent you a Java driver for the database but fat lot of good that will do for you. Stumbling through the internet you find a module that says it can natively load Java packages as Python modules. Well, it worth a shot. So first thing the guide says is that you need to install Java and set up a JAVA_HOME environment variable pointing to the JRE. Then start the JVM with classpath pointed to customers jar file. The customer sent over an example in Java so you just have to port it into Python. package com.paying.customer; import com.paying.customer.DataBase public class MyExample { public void main(String[] args){ Database db= new Database("our_records"); try (DatabaseConnection c= db.connect()) { c.runQuery(); while (c.hasRecords()) { Record record= db.nextRecord(); ... } } } } It does not look too horrible to translate. You just need to look past all those pointless type declarations and mean- ingless braces. Once you do, you can glue this into Python and get back to what you really love, like performing dictionary comprehensions on multiple keys. You glance over the JPype quick start guide. It has a few useful patterns. set the class path, start the JVM, remove all the type declarations, and you are done. 6 Chapter 1. Parts of the documentation JPype Documentation, Release 0.7.5 # Boiler plate stuff to start the module import jpype import jpype.imports from jpype.types import * # Launch the JVM jpype.startJVM(classpath=['jars/database.jar']) # import the Java modules from com.paying.customer import DataBase # Copy in the patterns from the guide to replace the example code db= Database("our_records") with db.connect() as DatabaseConnection: c.runQuery() while c.hasRecords(): record= db.nextRecord() ... Launch it in the interactive window.