diff --git a/doc/source/index.rst b/doc/source/index.rst index 451999e02c..dee8836e59 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -32,6 +32,7 @@ Contents commands recipes bootstraps + services apis troubleshooting contribute diff --git a/doc/source/services.rst b/doc/source/services.rst new file mode 100644 index 0000000000..835cf2ba5e --- /dev/null +++ b/doc/source/services.rst @@ -0,0 +1,80 @@ +Services +======== + +python-for-android supports the use of Android Services, background +tasks running in separate processes, in this case each running their +own Python interpreter instance. 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 python-for-android is run. 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 +`__ or (a heavier option) +`twisted `__. + +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 +~~~~~~~~~~~~~~~~~ + +.. 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('your.package.name.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.