jpy - a Python-Java Bridge

jpy is a bi-directional Python-Java bridge which you can use to embed Java code in Python programs or the other way round. It has been designed particularly with regard to maximum data transfer speed between the two languages. It comes with a number of outstanding features:

• Fully translates Java class hierarchies to Python
• Transparently handles Java method overloading
• Support of Java multi-threading
• Fast and memory-efficient support of primitive Java array parameters via Python buffers (e.g. Numpy arrays)
• Support of Java methods that modify primitive Java array parameters (mutable parameters)
• Java arrays translate into Python sequence objects
• Java API for accessing Python objects (jpy.jar)

jpy has been tested with Python 3.9–3.15 and OpenJDK 11+ on Linux, Windows, and macOS.

The initial development of jpy was driven by the need to write Python extensions to an established scientific imaging application programmed in Java, namely the SNAP toolbox, the SeNtinel Application Platform project, funded by the European Space Agency (ESA). (jpy is bundled with the SNAP distribution.) Current development and maintenance is funded by Deephaven.

Writing such Python plug-ins for a Java application usually requires a bi-directional communication between Python and Java since the Python extension code must be able to call back into the Java APIs.

For more information please have a look into jpy's

• documentation
• source repository
• issue tracker

How to build wheels for Linux and Mac

Install a JDK 11. Set JDK_HOME or JPY_JDK_HOME to point to your JDK installation and run the build script:

$ export JDK_HOME=<your-jdk-dir>
$ export JAVA_HOME=$JDK_HOME
$ pip install setuptools wheel
$ python setup.py build maven bdist_wheel

On success, the wheel is found in the dist directory.

To deploy the jpy.jar (if you don't know why you need this step, this is not for you)::

$ mvn clean deploy -DskipTests=true

How to build a wheel for Windows

Set JDK_HOME or JPY_JDK_HOME to point to your JDK installation. You'll need Windows SDK 7.1 or Visual Studio C++ to build the sources. With Windows SDK 7.1::

> SET VS90COMNTOOLS=C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\Tools\
> SET DISTUTILS_USE_SDK=1
> C:\Program Files\Microsoft SDKs\Windows\v7.1\bin\setenv /x64 /release
> SET JDK_HOME=<your-jdk-dir>
> pip install setuptools wheel
> python setup.py build maven bdist_wheel

With Visual Studio 14 and higher it is much easier::

> SET VS100COMNTOOLS=C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\Tools\
> SET JDK_HOME=<your-jdk-dir>
> pip install setuptools wheel
> python setup.py build maven bdist_wheel

On success, the wheel can be found in the dist directory.

How to install from sources

TBD

Releasing jpy

The target reader of this section is a jpy developer wishing to release a new jpy version. Note: You need to have Sphinx installed to update the documentation.

1. Make sure all Java and Python units tests run green
2. Remove the -SNAPSHOT qualifier from versions names in both the Maven pom.xml and setup.py files, and update the version numbers and copyright years in jpyutil.py and doc/conf.py.
3. Generate Java API doc by running mvn javadoc:javadoc which will update directory doc/_static
4. Update documentation, cd doc and run make html
5. http://peterdowns.com/posts/first-time-with-pypi.html

Running Tests

Run: python setup.py build test

Code Of Conduct

This project has adopted the Contributor Covenant Code of Conduct. For more information see the Code of Conduct or contact opencode@deephaven.io with any additional questions or comments.

Contributing

For instructions on contributing, see CONTRIBUTING.md.

Notes

Some of the details on this README are out of date. Efforts to improve them will be made in the future.

jpy Changelog

Version 2.2.0

• #240 Bump actions/checkout from 6 to 7
• #242 Bump actions/setup-python from 6 to 7
• #244 Bump actions/setup-java from 5 to 6
• #245 Support Python 3.15: replace the Py_GetPath()-family diagnostics removed in 3.15 with PyConfig_Get(), and add 3.15 / 3.15t to the CI and wheel build matrix
• #245 Fix -Wincompatible-pointer-types error in PyLib.getType reported by GCC 14+
• #246 Bump docker/bake-action from 7.2.0 to 7.4.0
• #247 fix: fetch bullseye packages from archive.debian.org

Version 2.1.0

• #233 refactor: simplify Python object cleanup to make it more efficient and avoid accessing Java heap when Java OOM happens
• #234 Bump docker/bake-action from 7.1.0 to 7.2.
• #236 fix the jpy_cleanup_thread_test for 3.14

Version 2.0.0

This version bumps the minimum Java requirements from 8 to 11. See #226 for more details.

• #226 fix: Fix a race caused by premature-finalization when calling a method on transient PyObjects
• #228 Replace Java 23 with 25 in Check CI due to EOL
• #229 Update top level documentation
• #231 Fix the empty jar issue

Version 1.4.0

• #220 Use Python built-in exception formating
• #215 Bump actions/checkout from 5 to 6
• #207 Bump actions/setup-python from 5 to 6
• #223 Bump docker/setup-buildx-action from 3 to 4
• #224 Bump docker/bake-action from 6.9.0 to 7.1.0
• #221 Bump actions/download-artifact from 4 to 8
• #222 Bump actions/upload-artifact from 4 to 7
• #225 Bump docker/setup-qemu-action from 3 to 4

Version 1.3.0

• #212 feat: Add 3.14 builds
• #214 Remove 3.6, 3.7, 3.8 from project's metadata and related dead code in the code base

Version 1.2.0

• #199 Call PyObject_IsTrue() to test truthiness

Version 1.1.0

• #179 Improve libpython search with python's sysconfig INSTSONAME

Version 1.0.0

• #176 fix: make PyObject cleanup thread-safe in free-threaded Python and reduce contention
• #175 Update project's Development Status classifier

Version 0.19.0

• #165 feat: free-threaded Python (3.13.0+) support
• #168 Add Python 3.13 builds
• #164 fix: Make org.jpy.PyLib.getCurrentLocals/Globals work for Python 3.13
• #162 Find Zero-Assembler OpenJDK 21

Version 0.18.0

• #158 Get the correct computed tb lineno
• #153 Remove pip upgrade from CI
• #150 Bump docker/bake-action from 4.5.0 to 4.6.0

Version 0.17.0

• #146 Delay resolving super classes until referenced
• #145 Use Py_ssize_t when calculate buffer len

Version 0.16.0

• #128 Function for converting Python values to an explicit Java type
• #132 Update auditwheel command to use --exclude
• Various CI-related version bumps

Version 0.15.0

• #112 Add jpy.byte_buffer() function
• #119 Fix Mac OSX + OpenJDK builds where JAVA_HOME contains libexec but not lib
• #121 Python 3.12 build
• #109 Add aarch64 Linux wheels to build / release workflow
• #113 Update build.yml actions

Version 0.14.0

• #99 Check for exception in getInt/Long/DoubleValue()
• #104 PyDictWrapper.values() incorrectly close the underlying PyObject while it is still referenced

Version 0.13.0

• #96 Python 3.11 compatibility

Version 0.12.0

• #88 Use valueOf() to box primitive values instead of creating new objects every time
• #89 Add Java process lookup for 'java.home' in find_jvm_dll_file()
• #85 Support creation of zero-sized primitive Java arrays

Version 0.11.1

• #79 Produce usable / distributable macosx wheels

Version 0.11.0

• Publish artifacts to PyPi. Source tarball and binary wheels for Python 3.6 - 3.10 for Linux, Mac, and Windows (x86_64).
• Publish release to Maven Central with group id org.jpyconsortium and artifact id jpy. Java-8 compatible jars.
• Many more changes.

Version 0.10

• Add the ability to pass properties and options to write_config_files. These values get passed to the jvm when it is initialized. #180 Contribution by davidlehrian.
• Make jpy work with Anaconda by setting environment variable PYTHONHOME from Java #143. Contribution by Dr-Irv.
• Fixed: Constants are not properly passed from Java to Python when using interfaces #140. Contribution by Dr-Irv.
• Fixed: Cannot iterate through a dict in Python 3.x #136. Contribution by Dr-Irv.
• Automatically build 64-bit Python wheels for all Python versions from 3.4 to 3.8 on Linux, Windows, and Mac (fixes #174).

Version 0.9

This version includes a number of contributions from supportive GitHub users. Thanks to all of you!

Fixes

• Corrected Java reference count of complex PyObject passed back and forth to methods (issue #120). Fix by sbarnoud.
• Fixed problem where default methods on Java 8 Interfaces were not found (issue #102). Fix by Charles P. Wright.
• Fixed error caused by missing sys.argv in Python when called from Java (issue #81). Fix by Dave Voutila.
• Fixed problem where calling jpy.get_type() too many times causes a memory access error (issue #74). Fix by Dave Voutila.
• Fixed a corruption when retrieving long values (#72). Fix by chipkent.
• Fixed fatal error when stopping python session (issue #70, #77). Fix by Dave Voutila.
• Explicit null checks for avoiding JVM crash (issue #126). Fix by Geomatys.

Improvements

• Can now use pip to install Python jpy package directly from GitHub (#83). This works for Linux and OS X where C compilers are available by default and should work on Windows with Visual Studio 15 installed. Contribution by Dave Voutila.
• Java PyObject is now serializable. Contribution by Mario Briggs.
• Improved Varargs method matching. You may pass in either an array (as in the past) or individual Python arguments, the match for a varargs method call is the minimum match for each of the arguments. Zero length arrays (i.e. no arguments) are also permitted with a match value of 10.
• jpy.type_translations dictionary for callbacks when instantiating Python objects.
• jpy.VerboseExceptions enables full Java stack traces.
• More Python exceptions are translated to the corresponding Java type.
• Globals and locals are converted when executing code with PyLib, to allow variables to be used across statement invocation; and interrogated from Java.
• PyObject wrappers for dictionary, list, and introspection functions to tell you whether or not you can convert the object.
• Support for isAssignable checks when dealing with Python Strings and primitives, to allow matches for argument types such as java.lang.Comparable or java.lang.Number.

Version 0.8

Fixes

• Java interface types don't include methods of extended interfaces (issue #64)
• Loading of jpy DLL fails for user-specific Python installations on Windows (issue #58)
• Java interface types didn't expose java.lang.Object methods (issue #57)
• Java 1-arg static method was confused with a zero-arg non-static method (issue #54)
• Python interpreter crash occurred when executing del statement on Java arrays (issue #52)
• Python extensions loaded from Java couldn't see Python symbols (Linux) (issue #38)

Improvements

• It is now possible to use jpy Java API to work with multiple Python installations (issue #35). A tool called 'jpyutil.py' can be used to write configuration files that determine the required shared libraries for a given Python versions. A new Java system property 'jpy.config' is used to point to a desired configuration file.
• Simplified jpy installation (issue #15):
  • removed need to add JVM path to PATH (Windows) / LD_LIBRARY_PATH (Unix) environment variable
  • removed need to compile Java module using Maven
  • removed need to specify JDK_HOME environment variable, if JAVA_HOME already points to a JDK
• Added 'jclass' attribute to Python type that wraps a Java class (issue #63) .
• Java API extensions

• new jpy.org.PyObject.executeCode() methods
• new jpy.org.PyModule.getBuiltins() method
• new jpy.org.PyModule.getMain() method
• new jpy.org.PyModule.extendSysPath() method

• Java API configuration changes:
  • System property jpy.jpyLib:
  • System property jpy.jdlLib:
  • System property jpy.pythonLib:
  • System property jpy.config:
  • Loaded from
    • File ./jpyconfig.properties
    • Resource /jpyconfig.properties
    • File ${jpy.config}
• Python API configuration changes:
  • Loaded from
    • File ./jpyconfig.py
    • Resource ${jpy-module}/jpyconfig.py
  • Attribute java_home
  • Attribute jvm_dll
• Python API extensions
  • new jpyutil module
    • jpyutil.init_jvm(...)
    • jpyutil.preload_jvm_lib(...)
  • new jpyutil tool
    • usage: jpyutil.py [-h] [--out OUT] [--java_home JAVA_HOME] [--jvm_dll JVM_DLL]
• Added basic support for Java Scripting Engine API (issue #53)

Other changes

• Switched to Apache 2.0 license from version 0.8 and later (issue #60)

Version 0.7.5

• Fixed bad pointer in C-code which caused unpredictable crashes (issue #43)

Version 0.7.4

• Fixed a problem where jpy crashes with unicode arguments (issue #42)
• Fixed segmentation fault occurring occasionally during installation of jpy (issue #40)
• Improved Java exception messages on Python errors (issue #39)

Version 0.7.3

• Fixed problem where a Java primitive array argument has occasionally not been initialised by a related Python buffer argument (issue #37)

Version 0.7.2

• Added backward compatibility with Python 2.7 (issue #34).
• Added Java parameter annotation 'output' (issue #36). This is used to optimise passing Python buffer arguments where Java primitive arrays are expected.
• Removed debugging prints of the form "JNI_OnLoad: ..."
• Corrected documentation of jpy.array(type, init) function, which was said to be jpy.array(type, length)
• Removed console dumps that occurred when calling from Java proxies into Python
• Updated Java API documentation and added it to Sphinx doc folder (doc/_static/java-apidoc)
• Added new diagnostic F_ERR flag to Java class PyLib.Diag
• Java class PyLib is no longer instantiable

Version 0.7.1

• Updated README and added MANIFEST.in after recognising that the jpy-0.7.zip distribution misses most of the required source files and learning what to do on this case.

Version 0.7

• Initial version.