87 lines
3.5 KiB
ReStructuredText
87 lines
3.5 KiB
ReStructuredText
Services
|
|
========
|
|
|
|
python-for-android supports the use of Android Services, background
|
|
tasks running in separate processes. These are the closest Android
|
|
equivalent to multiprocessing on e.g. desktop platforms, and it is not
|
|
possible to use normal multiprocessing on Android. Services are also
|
|
the only way to run code when your app is not currently opened by the user.
|
|
|
|
Services must be declared when building your APK. Each one
|
|
will have its own main.py file with the Python script to be run. You
|
|
can communicate with the service process from your app using e.g. `osc
|
|
<https://pypi.python.org/pypi/python-osc>`__ or (a heavier option)
|
|
`twisted <https://twistedmatrix.com/trac/>`__.
|
|
|
|
Service creation
|
|
----------------
|
|
|
|
There are two ways to have services included in your APK.
|
|
|
|
Service folder
|
|
~~~~~~~~~~~~~~
|
|
|
|
This basic method works with both the new SDL2 and old Pygame
|
|
bootstraps. It is recommended to use the second method (below) where
|
|
possible.
|
|
|
|
Create a folder named ``service`` in your app directory, and add a
|
|
file ``service/main.py``. This file should contain the Python code
|
|
that you want the service to run.
|
|
|
|
To start the service, use the :code:`start_service` function from the
|
|
:code:`android` module (included automatically with the Pygame
|
|
bootstrap, you must add it to the requirements manually with SDL2 if
|
|
you wish to use this method)::
|
|
|
|
import android
|
|
android.start_service(title='service name',
|
|
description='service description',
|
|
arg='argument to service')
|
|
|
|
.. _arbitrary_scripts_services:
|
|
|
|
Arbitrary service scripts
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. note:: This service method is *not supported* by the Pygame bootstrap.
|
|
|
|
This method is recommended for non-trivial use of services as it is
|
|
more flexible, supporting multiple services and a wider range of
|
|
options.
|
|
|
|
To create the service, create a python script with your service code
|
|
and add a :code:`--service=myservice:/path/to/myservice.py` argument
|
|
when calling python-for-android. The ``myservice`` name before the
|
|
colon is the name of the service class, via which you will interact
|
|
with it later. You can add multiple
|
|
:code:`--service` arguments to include multiple services, which you
|
|
will later be able to stop and start from your app.
|
|
|
|
To run the services (i.e. starting them from within your main app
|
|
code), you must use PyJNIus to interact with the java class
|
|
python-for-android creates for each one, as follows::
|
|
|
|
from jnius import autoclass
|
|
service = autoclass('your.package.name.ServiceMyservice')
|
|
mActivity = autoclass('org.kivy.android.PythonActivity').mActivity
|
|
argument = ''
|
|
service.start(mActivity, argument)
|
|
|
|
Here, ``your.package.name`` refers to the package identifier of your
|
|
APK as set by the ``--package`` argument to python-for-android, and
|
|
the name of the service is ``ServiceYourservicename``, in which
|
|
``Yourservicename`` is the identifier passed to the ``--service``
|
|
argument with the first letter upper case. You must also pass the
|
|
``argument`` parameter even if (as here) it is an empty string. If you
|
|
do pass it, the service can make use of this argument.
|
|
|
|
Services support a range of options and interactions not yet
|
|
documented here but all accessible via calling other methods of the
|
|
``service`` reference.
|
|
|
|
.. note:: The app root directory for Python imports will be in the app
|
|
root folder even if the service file is in a subfolder. To import from
|
|
your service folder you must use e.g. ``import service.module``
|
|
instead of ``import module``, if the service file is in the
|
|
``service/`` folder.
|