repository·master·Indexed 23 days ago
https://github.com/kivy/pyjniusA Python library that enables access to Java classes via the Java Native Interface (JNI). It is widely used in the Kivy ecosystem to access Android APIs through python-for-android. Key features include the autoclass() function for automatic class discovery, manual Java class definition via MetaJavaClass, and support for Android-specific hardware and system APIs such as MediaRecorder, MediaPlayer, and TextToSpeech.
PyJNIus is a Python library that enables access to Java classes via the Java Native Interface (JNI). It functions in two modes:
It is managed by the Kivy Team and is compatible with python-for-android.
To access a Java class from Python, subclass JavaClass and define the following required attributes:
__javaclass__: The Java class name in 'path/to/Class' format (e.g., 'java/util/Stack').__metaclass__: Must be set to MetaJavaClass.__metaclass__ = MetaJavaClassclass Stack(JavaClass, metaclass=MetaJavaClass):Optional attributes:
__javaconstructor__: A tuple of all possible constructor signatures in JNI format (e.g., ('()V', '(Ljava/lang/String;)V')). If not set, a no-argument constructor is assumed.You can then add JavaMethod, JavaStaticMethod, JavaField, or JavaStaticField to map specific members.
from jnius import JavaClass, MetaJavaClass
class Stack(JavaClass):
__javaclass__ = 'java/util/Stack'
__metaclass__ = MetaJavaClassPyJNIus utilizes Java reflection to automatically wrap returned Java objects. If a method or field returns a Java object that is not a native type, PyJNIus provides a new autoclass-like object that allows you to continue accessing the returned object's members naturally without manual re-declaration.
For example, accessing java.lang.System.out automatically provides access to the PrintStream object's methods.
from jnius import autoclass
System = autoclass('java.lang.System')
# System.out is automatically reflected as a Java object
System.out.println('Hello World')When implementing Java in Python, the signature of the Java method must match exactly. Java signatures follow the format (<argument1><argument2><...>)<return type>.
Type Identifiers:
L<java class>;: A Java object of type <java class>Z: java/lang/BooleanB: java/lang/ByteC: java/lang/CharacterS: java/lang/ShortI: java/lang/IntegerJ: java/lang/LongF: java/lang/FloatD: java/lang/DoubleV: void (return type only)[ prefix: Indicates an array (e.g., [B is a Byte[])Examples:
(ILjava/util/List;)V: Argument 1 is an Integer, Argument 2 is a java.util.List, returns void.([B)Z: Argument 1 is a Byte[], returns a boolean.You can use the javap tool to find these signatures. For Android classes, use the -classpath flag pointing to android.jar within your Android SDK platforms directory.
To implement a Java interface in Python so it can be passed to Java, subclass PythonJavaClass.
Requirements:
__javainterfaces__: A list of Java interfaces in 'path/to/Interface' format.@java_method(signature) decorator on Python methods to map them to the interface.Class Loaders (__javacontext__):
'system' (default): Used for standard Java API interfaces.'app': Required on Android if you are implementing an interface that is part of your own APK/application code.from jnius import PythonJavaClass, java_method
class PythonListIterator(PythonJavaClass):
__javainterfaces__ = ['java/util/ListIterator']
def __init__(self, collection, index=0):
super(PythonListIterator, self).__init__()
self.collection = collection
self.index = index
@java_method('()Z')
def hasNext(self):
return self.index < len(self.collection.data) - 1
@java_method('()Ljava/lang/Object;')
def next(self):
obj = self.collection.data[self.index]
self.index += 1
return objPyJNIus can be distributed as a prebuilt Android wheel (android_* tags) that is SDL-agnostic and Java-free. Unlike the desktop version, the Android wheel does not bundle a JVM or Java classes; instead, it attaches to the JVM already running in the host process.
To use this wheel, the host application must satisfy two requirements:
In-process JVM discovery: The host must have a JVM discoverable at the time of import jnius. PyJNIus attempts to resolve JNIEnv in this order:
SDL_GetAndroidJNIEnv from libSDL3.so (SDL3)SDL_AndroidGetJNIEnv from libSDL2.so (SDL2)JNI_GetCreatedJavaVMs from libnativehelper.so (API 31+ only)Note: For SDL hosts, the SDL library must be loaded before the first import jnius occurs.
Java glue on the dex classpath: If using features like PythonJavaClass or @java_method (proxies), the host application's packager must compile and include org.jnius.NativeInvocationHandler in the APK's dex classpath. Plain autoclass and method calls do not require this glue.
$ character in the class name string passed to autoclass. For example, to access android.provider.MediaStore.Images.Media, use autoclass('android.provider.MediaStore$Images$Media').For more control or to explicitly declare only the methods and fields you need, you can manually define a Python class that inherits from JavaClass and uses MetaJavaClass as its metaclass. You must provide the __javaclass__ (the Java class path using slashes instead of dots) and define methods using JavaStaticMethod or JavaMethod with their JNI signatures.
from jnius import MetaJavaClass, JavaClass, JavaMethod, JavaStaticMethod
class Hardware(JavaClass):
__metaclass__ = MetaJavaClass
__javaclass__ = 'org/renpy/android/Hardware'
vibrate = JavaStaticMethod('(D)V')
accelerometerEnable = JavaStaticMethod('(Z)V')
accelerometerReading = JavaStaticMethod('()[F')
getDPI = JavaStaticMethod('()I')
# Usage
print('DPI is', Hardware.getDPI())
Hardware.accelerometerEnable(True)Building PyJNIus is required for development or when a pre-built binary is unavailable for your platform.
All platforms require a Java Development Kit (JDK). If PyJNIus cannot locate your JDK, set the JAVA_HOME environment variable.
GNU Compiler Collection (GCC). On Debian-based systems, use apt-get install build-essentials.Microsoft Visual C++ Build Tools (the command-line tools subset of Visual Studio).Xcode command-line tools.After checking out the repository, install it using pip:
pip install .This will install Cython in the Python build environment as specified in pyproject.toml.
To build redistributable Android wheels, use a Linux x86_64 or macOS host with an Android SDK. The process involves generating a Cython-produced C file and using cibuildwheel to drive the NDK.
Important Build Requirements:
rm -rf build) to prevent stale Java payloads from being re-injected, which violates the Java-free guarantee of the wheel.LDFLAGS = "-Wl,-z,max-page-size=16384" to ensure 16 KB page alignment required by Android 15/16.build or uv as the frontend; Android does not support pip for this process.Install PyJNIus using pip. Note that the PyPI package name is pyjnius (not jnius).
pip install pyjniusmake tests. This requires pytest and Cython to be installed in your current Python environment.make tests