Pyjnius Documentation Release 1.0a1

Pyjnius Documentation Release 1.0a1 Kivy Team and other contributors Feb 10, 2019 Contents 1 Installation 3 1.1 Installation on GNU/Linux distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.2 Installation for Android . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.3 Installation for Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.4 Installation for macOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.5 Installation for Conda . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2 Quickstart 7 2.1 A minimal example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.2 Automatic recursive inspection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3 Android 9 3.1 Get the DPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.2 Recording an audio file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.3 Playing an audio file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.4 Accessing the Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.5 Accelerometer access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.6 Using TextToSpeech . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 4 API 15 4.1 Reflection classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 4.2 Reflection functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 4.3 Java class implementation in Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 4.4 Java signature format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 4.5 JVM options and the class path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 4.6 Pyjnius and threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 5 Packaging 23 5.1 main.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 5.2 main.spec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 5.3 Running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 6 Indices and tables 27 Python Module Index 29 i ii Pyjnius Documentation, Release 1.0a1 Pyjnius is a Python library for accessing Java classes. This documentation is divided into differents parts. We recommend you to start with Installation, and then head over to the Quickstart. You can also check Android for specific example for the Android platform. If you’d rather dive into the internals of Pyjnius, check out the API documentation. Contents 1 Pyjnius Documentation, Release 1.0a1 2 Contents CHAPTER 1 Installation PyJNIus depends on Cython and the Java Development Kit (includes the Java Runtime Environment). 1.1 Installation on GNU/Linux distributions You need the GNU Compiler Collection (GCC), the JDK and JRE installed (openjdk will do), and Cython. Then, just type: sudo python setup.py install If you want to compile the extension within the directory for any development, just type: make You can run the tests suite to make sure everything is running right: make tests 1.2 Installation for Android To use pyjnius in an Android app, you must include it in your compiled Python distribution. This is done automatically if you build a Kivy app, but you can also add it to your requirements explicitly as follows. If you use buildozer, add pyjnius to your requirements in buildozer.spec: requirements = pyjnius If you use python-for-android directly, add pyjnius to the requirements argument when creating a dist or apk: p4a apk --requirements=pyjnius 3 Pyjnius Documentation, Release 1.0a1 1.3 Installation for Windows Python and pip must be installed and present in the PATH environment variable. 1. Download and install the JDK containing the JRE: http://www.oracle.com/technetwork/java/javase/downloads/index.html 2. Edit your system and environment variables (use the appropriate Java bitness and version in the paths): Add to your Environment Variables: • JAVA_HOME: C:\Program Files\Java\jdk1.7.0_79\bin • PATH: C:\Program Files\Java\jdk1.7.0_79\jre\bin\server contains the jvm.dll necessary for importing and using PyJNIus. Note: set PATH=%PATH%;C:\Program Files\Java\jdk1.7.0_79\jre\bin\server Add to System Variables or have it present in your PATH: • PATH: C:\Program Files\Java\jdk1.7.0_79\bin‘ 3. Download and install the C compiler: (a) Microsoft Visual C++ Compiler for Python 2.7: http://aka.ms/vcpython27 (b) MinGWPy for Python 2.7: https://anaconda.org/carlkl/mingwpy (c) Microsoft Visual C++ Build Tools (command-line tools subset of Visual Studio) for Python 3.5 and 3.6: https://visualstudio.microsoft.com/downloads/ For other versions see Python’s Windows Compilers wiki. 4. Update pip and setuptools: python -m pip install --upgrade pip setuptools 5. Install Cython: python -m pip install --upgrade cython 6. Install Pyjnius: pip install pyjnius Note: In case of MinGWPy’s GCC returning a CreateProcess failed: 5 error you need to run the command prompt with elevated permissions, so that the compiler can access the JDK in C:\Program Files\Java\jdkx.y.z_b or C:\Program Files (x86)\Java\jdkx.y.z_b. 1.4 Installation for macOS Python and pip must be installed and present in the PATH environment variable. 4 Chapter 1. Installation Pyjnius Documentation, Release 1.0a1 1. Download and install the JDK containing the JRE: http://www.oracle.com/technetwork/java/javase/downloads/index.html 2. Edit your system and environment variables (use the appropriate Java bitness and version in the paths): Add to your Environment Variables: • export JAVA_HOME=/usr/libexec/java_home 3. Install Xcode command-line tools. 4. Update pip and setuptools: python -m pip install --upgrade pip setuptools 5. Install Cython: python -m pip install --upgrade cython 6. Install Pyjnius: pip install pyjnius 1.5 Installation for Conda Similar to PIP there is a package manager for Anaconda <https://www.anaconda.com/what-is-anaconda/> called Conda. An unofficial compiled distributions of PyJNIus for Conda supported platforms you can find at https: //anaconda.org/conda-forge/pyjnius. You can install pyjnius with this command: conda install -c conda-forge pyjnius Or if you want a specific package label e.g. gcc7: conda install -c conda-forge/label/gcc7 pyjnius 1.5. Installation for Conda 5 Pyjnius Documentation, Release 1.0a1 6 Chapter 1. Installation CHAPTER 2 Quickstart Eager to get started? This page will give you a good introduction to Pyjnius. It assumes you have already Pyjnius installed. If you do not, head over the Installation section. 2.1 A minimal example A minimal Pyjnius example looks something like this: from jnius import autoclass Stack = autoclass('java.util.Stack') stack = Stack() stack.push('hello') stack.push('world') print stack.pop() # --> 'world' print stack.pop() # --> 'hello' Just save it as test.py (or something similar) and run it with your Python interpreter. Make sure not to call your application jnius.py because it would conflict with Pyjnius itself: $ python test.py world hello 2.2 Automatic recursive inspection Pyjnius uses Java reflection to give you a new autoclass() if the return type is not a native type. Let’s see this example: System = autoclass('java.lang.System') System.out.println('Hello World') 7 Pyjnius Documentation, Release 1.0a1 We only declared the first System class, but we are able to use all the static fields and methods naturally. Let’s go deeper: >>> System = autoclass('java.lang.System') >>> System <class 'jnius.java.lang