@@ -3,42 +3,36 @@ Accessing Android APIs
33======================
44
55When writing an Android application you may want to access the normal
6- Android APIs, which are available in Java. It is by calling these that
7- you would normally accomplish everything from vibration, to opening
8- other applications, to accessing sensor data, to controlling settings
9- like screen orientation and wakelocks.
10-
11- These APIs can be accessed from Python to perform all of these tasks
12- and many more. This is made possible by the `Pyjnius
13- <http://pyjnius.readthedocs.org/en/latest/> `_ module, a Python
14- library for automatically wrapping Java and making it callable from
15- Python code. This is fairly simple to use, though not very Pythonic
16- and inherits Java's verbosity. For this reason the Kivy organisation
17- also created `Plyer <https://plyer.readthedocs.org/en/latest/ >`_,
18- which further wraps specific APIs in a Pythonic and cross-platform
19- way - so in fact you can call the same code in Python but have it do
20- the right thing also on platforms other than Android.
21-
22- These are both independent projects whose documentation is linked
23- above, and you can check this to learn about all the things they can
24- do. The following sections give some simple introductory examples,
25- along with explanation of how to include these modules in your APKs.
6+ Android Java APIs, in order to control your application's appearance
7+ (fullscreen, orientation etc.), interact with other apps or use
8+ hardware like vibration and sensors.
9+
10+ You can access these with `Pyjnius
11+ <http://pyjnius.readthedocs.org/en/latest/> `_, a Python library for
12+ automatically wrapping Java and making it callable from Python
13+ code. Pyjnius is fairly simple to use, but not very Pythonic and it
14+ inherits Java's verbosity. For this reason the Kivy organisation also
15+ created `Plyer <https://plyer.readthedocs.org/en/latest/ >`_, which
16+ further wraps specific APIs in a Pythonic and cross-platform way; you
17+ can call the same code in Python but have it do the right thing also
18+ on platforms other than Android.
19+
20+ Pyjnius and Plyer are independent projects whose documentation is
21+ linked above. See below for some simple introductory examples, and
22+ explanation of how to include these modules in your APKs.
2623
2724
2825Using Pyjnius
2926-------------
3027
31- Pyjnius lets you call the Android API directly from Python; this let's
32- you do almost everything you can (and probably would) do in a Java
33- app. Pyjnius is works by dynamically wrapping Java classes, so you
34- don't have to wait for any particular feature to be pre-supported.
28+ Pyjnius lets you call the Android API directly from Python Pyjnius is
29+ works by dynamically wrapping Java classes, so you don't have to wait
30+ for any particular feature to be pre-supported.
3531
36- You can include Pyjnius in your APKs by adding the `pyjnius ` or
37- `pyjniussdl2 ` recipes to your build requirements (the former works
38- with Pygame/SDL1, the latter with SDL2, the need to make this choice
39- will be removed later when pyjnius internally supports multiple
40- Android backends). It is automatically included in any APK containing
41- Kivy, in which case you don't need to specify it manually.
32+ You can include Pyjnius in your APKs by adding `pyjnius ` to your build
33+ requirements, e.g. :code: `--requirements=flask,pyjnius `. It is
34+ automatically included in any APK containing Kivy, in which case you
35+ don't need to specify it manually.
4236
4337The basic mechanism of Pyjnius is the `autoclass ` command, which wraps
4438a Java class. For instance, here is the code to vibrate your device::
@@ -87,17 +81,16 @@ You can check the `Pyjnius documentation <Pyjnius_>`_ for further details.
8781Using Plyer
8882-----------
8983
90- Plyer aims to provide a much less verbose, Pythonic wrapper to
91- platform-specific APIs. Android is a supported platform, but it also
92- supports iOS and desktop operating systems, with the idea that the
93- same Plyer code would do the right thing on any of them, though Plyer
94- is a work in progress and not all platforms support all Plyer calls
95- yet. This is the disadvantage of Plyer, it does not support all APIs
96- yet, but you can always Pyjnius to call anything that is currently
97- missing.
84+ Plyer provides a much less verbose, Pythonic wrapper to
85+ platform-specific APIs. It supports Android as well as iOS and desktop
86+ operating systems, though plyer is a work in progress and not all
87+ platforms support all Plyer calls yet.
88+
89+ Plyer does not support all APIs yet, but you can always Pyjnius to
90+ call anything that is currently missing.
9891
9992You can include Plyer in your APKs by adding the `Plyer ` recipe to
100- your build requirements. It is not included automatically.
93+ your build requirements, e.g. :code: ` --requirements=plyer `.
10194
10295You should check the `Plyer documentation <Plyer _>`_ for details of all supported
10396facades (platform APIs), but as an example the following is how you
@@ -106,8 +99,4 @@ would achieve vibration as described in the Pyjnius section above::
10699 from plyer.vibrator import vibrate
107100 vibrate(10) # in Plyer, the argument is in seconds
108101
109- This is obviously *much * less verbose!
110-
111- .. warning :: At the time of writing, the Plyer recipe is not yet
112- ported, and Plyer doesn't support SDL2. These issues will
113- be fixed soon.
102+ This is obviously *much * less verbose than with Pyjnius!
0 commit comments