jpy - 一个Python-Java桥梁

jpy是一个双向Python-Java桥梁，您可以使用它将Java代码嵌入到Python程序中，反之亦然。它特别设计用于在两种语言之间实现最大的数据传输速度。它具有许多出色的功能

• 完全将Java类层次结构转换为Python
• 透明处理Java方法重载
• 支持Java多线程
• 通过Python缓冲区（例如Numpy数组）快速且内存高效地支持Java原始数组参数
• 支持修改Java原始数组参数的Java方法（可变参数）
• Java数组转换为Python序列对象
• 访问Python对象的Java API（jpy.jar）

jpy已在64位Ubuntu Linux、Windows 10和macOS上与Python 3.4–3.8和OpenJDK 8进行了测试。

jpy的最初开发是由编写用Java编写的现有科学影像应用程序的Python扩展的需求驱动的，即SNAP工具箱，SeNtinel应用程序平台项目，由欧洲航天局（ESA）资助。（jpy包含在SNAP发行版中。）

为Java应用程序编写此类Python插件通常需要在Python和Java之间进行双向通信，因为Python扩展代码必须能够回调到Java API。

有关更多信息，请参阅jpy的

• 文档
• 源代码库
• 问题跟踪器

如何为Linux和Mac构建wheels

安装JDK 8，最好是Oracle发行版。将JDK_HOME或JPY_JDK_HOME设置为指向您的JDK安装，并运行构建脚本

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

成功后，wheels将位于dist目录中。

要部署jpy.jar（如果您不知道为什么需要此步骤，这不适合您）：

$ mvn clean deploy -DskipTests=true

如何为Windows构建wheels

将JDK_HOME或JPY_JDK_HOME设置为指向您的JDK安装。您需要Windows SDK 7.1或Visual Studio C++来构建源代码。使用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

使用Visual Studio 14及更高版本要容易得多：

> 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

成功后，wheels可以找到在dist目录中。

如何从源代码安装

待定

发布jpy

本节的目标读者是希望发布新jpy版本的jpy开发者。注意：您需要安装Sphinx来更新文档。

1. 确保所有Java和Python单元测试都运行绿色
2. 从Maven的pom.xml和setup.py文件中的版本名称中删除-SNAPSHOT限定符，并在jpyutil.py和doc/conf.py中更新版本号和版权年份。
3. 通过运行mvn javadoc:javadoc生成Java API文档，这将更新doc/_static目录
4. 更新文档，进入doc目录并运行make html
5. http://peterdowns.com/posts/first-time-with-pypi.html

运行测试

运行：python setup.py build test

自动化构建

截至2020-08-27，jpy的Python wheel软件包在AppVeyor上自动构建，但目前它们仅上传到私有FTP服务器，并未公开发布。在Linux、Windows和macOS（≥10.9）上为Python版本3.4、3.5、3.6、3.7和3.8构建了wheels。仅构建64位wheels。

存储库还包含一个过时的自动化Travis构建配置，但目前该配置未维护且损坏。

行为准则

本项目已采用贡献者契约行为准则。有关更多信息，请参阅行为准则或联系opencode@deephaven.io，如有任何其他问题或意见。

贡献

有关贡献说明，请参阅CONTRIBUTING.md。

注意

本README中的一些细节已过时。未来将努力改进它们。

jpy变更日志

版本0.18.0

• #158 获取正确的计算tb行号
• #153 从CI中移除pip升级
• #150 将docker/bake-action从4.5.0升级到4.6.0

版本0.17.0

• #146 延迟解析直到引用超类
• #145 在计算缓冲区长度时使用Py_ssize_t

版本0.16.0

• #128 转换Python值到显式Java类型的函数
• #132 更新auditwheel命令以使用--exclude
• 与CI相关的多个版本升级

版本0.15.0

• #112 添加jpy.byte_buffer()函数
• #119 修复Mac OSX + OpenJDK构建中JAVA_HOME包含libexec但不包含lib的问题
• #121 Python 3.12构建
• #109 将aarch64 Linux wheels添加到构建/发布工作流程中
• #113 更新build.yml动作

版本0.14.0

• #99 在getInt/Long/DoubleValue()中检查异常
• #104 PyDictWrapper.values()在仍然被引用时错误地关闭了底层的PyObject

版本0.13.0

• #96 Python 3.11兼容性

版本0.12.0

• #88 使用valueOf()将原始值装箱，而不是每次都创建新对象
• #89 在find_jvm_dll_file()中添加对'java.home'的Java进程查找
• #85 支持创建零大小的原始Java数组

版本0.11.1

• #79 生成可使用/可分发的macosx wheels

版本0.11.0

• 将工件发布到PyPi。适用于Linux、Mac和Windows（x86_64）的Python 3.6 - 3.10的源tarball和二进制wheels。
• 将发布到Maven Central，组ID为org.jpyconsortium，工件ID为jpy。Java-8兼容的jars。
• 更多更改。

版本0.10

• 添加将属性和选项传递给write_config_files的功能。这些值在JVM初始化时传递给JVM。由davidlehrian贡献。#180
• 通过设置环境变量PYTHONHOME从Java与Anaconda兼容，由Dr-Irv贡献。#143
• 修复了在接口中使用时从Java传递到Python的常量不被正确传递的问题#140。由Dr-Irv贡献。
• 修复了在Python 3.x中无法遍历字典的问题#136。由Dr-Irv贡献。
• 自动构建从3.4到3.8的所有Python版本的64位Python wheels，适用于Linux、Windows和Mac（修复了#174）。

版本0.9

本版本包含来自支持性GitHub用户的多个贡献。感谢大家！

修复

• 修复了在方法间传递复杂数据时Java引用计数的问题（问题#120）。由sbarnoud修复。
• 修复了Java 8接口中默认方法未找到的问题（问题#102）。由Charles P. Wright修复。
• 修复了从Java调用Python时缺少sys.argv导致的问题（问题#81）。由Dave Voutila修复。
• 修复了多次调用jpy.get_type()导致内存访问错误的问题（问题#74）。由Dave Voutila修复。
• 修复了在检索长值时发生损坏的问题（问题#72）。由chipkent修复。
• 修复了在停止Python会话时发生的致命错误（问题#70、#77）。由Dave Voutila修复。
• 显式null检查以避免JVM崩溃（问题#126）。由Geomatys修复。

改进

• 现在可以直接使用pip从GitHub安装Python jpy包（#83）。这对于Linux和OS X有效，其中默认提供C编译器，并且应该与已安装Visual Studio 15的Windows兼容。由Dave Voutila贡献。
• Java PyObject现在可序列化。由Mario Briggs贡献。
• 改进了可变参数方法的匹配。您现在可以传递数组（如过去一样）或单个Python参数，可变参数方法调用的匹配是每个参数的最小匹配。空长度数组（即没有参数）也允许，匹配值为10。
• jpy.type_translations字典用于在实例化Python对象时回调。
• jpy.VerboseExceptions启用完整的Java堆栈跟踪。
• 更多Python异常被转换为相应的Java类型。
• 在执行带有PyLib的代码时，全局和局部变量将被转换，以便允许变量跨语句调用使用；并且可以从Java中查询。
• 为字典、列表和内省函数提供PyObject包装器，以告知您是否可以转换对象。
• 在处理Python字符串和原始数据类型时支持isAssignable检查，以便允许匹配java.lang.Comparable或java.lang.Number之类的参数类型。

版本0.8

修复

• Java接口类型不包含扩展接口的方法（问题#64）
• 在Windows上，对于用户特定的Python安装，加载jpy DLL失败（问题#58）
• Java接口类型没有公开java.lang.Object方法（问题#57）
• Java 1个参数的静态方法与0个参数的非静态方法混淆（问题#54）
• 在Java数组上执行del语句时，Python解释器发生崩溃（问题#52）
• 从Java加载的Python扩展在Linux上无法看到Python符号（问题#38）

改进

• 现在可以使用jpy Java API与多个Python安装一起使用（问题#35）。可以使用名为'jpyutil.py'的工具编写配置文件，以确定给定Python版本所需的共享库。使用新的Java系统属性'jpy.config'来指向所需的配置文件。
• 简化jpy安装（问题#15）
  • 无需将JVM路径添加到PATH（Windows）/ LD_LIBRARY_PATH（Unix）环境变量
  • 无需使用Maven编译Java模块
  • 如果JAVA_HOME已指向JDK，则无需指定JDK_HOME环境变量
• 为包装Java类的Python类型添加了'jclass'属性（问题#63）。
• Java API扩展

• 新的jpy.org.PyObject.executeCode()方法
• 新的jpy.org.PyModule.getBuiltins()方法
• 新的jpy.org.PyModule.getMain()方法
• 新的jpy.org.PyModule.extendSysPath()方法

• Java API配置更改
  • 系统属性jpy.jpyLib
  • 系统属性jpy.jdlLib
  • 系统属性jpy.pythonLib
  • 系统属性jpy.config
  • 从
    • 文件./jpyconfig.properties
    • 资源/jpyconfig.properties
    • 文件${jpy.config}
• Python API配置更改
  • 从
    • 文件./jpyconfig.py
    • 资源${jpy-module}/jpyconfig.py
  • 属性java_home
  • 属性jvm_dll
• Python API扩展
  • 新的jpyutil模块
    • jpyutil.init_jvm(...)
    • jpyutil.preload_jvm_lib(...)
  • 新的jpyutil工具
    • 用法：jpyutil.py [-h] [--out OUT] [--java_home JAVA_HOME] [--jvm_dll JVM_DLL]
• 添加了对Java Scripting Engine API的基本支持（问题#53）

其他更改

• 从版本0.8及以后切换到Apache 2.0许可证（问题#60）

版本0.7.5

• 修复了C代码中的坏指针，导致不可预测的崩溃（问题#43）

版本0.7.4

• 修复了jpy在Unicode参数上崩溃的问题（问题#42）
• 修复了安装jpy期间偶尔发生的段错误（问题#40）
• 改进了Python错误上的Java异常消息（问题#39）

版本0.7.3

• 修复了有时由于相关的Python缓冲区参数未初始化而导致Java原始数组参数未初始化的问题（问题编号#37）

版本 0.7.2

• 添加了对Python 2.7的向后兼容性（问题编号#34）。
• 添加了Java参数注解 'output'（问题编号#36）。这用于优化传递Java原始数组预期的Python缓冲区参数。
• 删除了形如 "JNI_OnLoad: ..." 的调试打印。
• 更正了jpy.array(type, init)函数的文档，该函数被错误地标记为jpy.array(type, length)
• 删除了从Java代理调用Python时发生的控制台转储。
• 更新了Java API文档，并将其添加到Sphinx文档文件夹（doc/_static/java-apidoc）
• 向Java类PyLib.Diag添加了新的诊断F_ERR标志
• Java类PyLib不再可实例化

版本 0.7.1

• 更新了README，并在识别出jpy-0.7.zip发行版缺少大多数所需源文件以及了解在此情况下应如何操作后添加了MANIFEST.in。

版本 0.7

• 初始版本。