Release 2019.08.09

.gitignore

@@ -21,4 +21,19 @@ __pycache__/
 
 #idea/pycharm
 .idea/
-.tox
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+coverage.xml
+*.cover
+.pytest_cache/
+
+# testapp's build folder
+testapps/build/
+
+# Dolphin (the KDE file manager autogenerates the file `.directory`)
+.directory

Dockerfile.py2

@@ -58,8 +58,8 @@ RUN ${RETRY} curl --location --progress-bar --insecure \
 ENV ANDROID_SDK_HOME="${ANDROID_HOME}/android-sdk"
 
 # get the latest version from https://developer.android.com/studio/index.html
-ENV ANDROID_SDK_TOOLS_VERSION="3859397"
-ENV ANDROID_SDK_BUILD_TOOLS_VERSION="26.0.2"
+ENV ANDROID_SDK_TOOLS_VERSION="4333796"
+ENV ANDROID_SDK_BUILD_TOOLS_VERSION="28.0.2"
 ENV ANDROID_SDK_TOOLS_ARCHIVE="sdk-tools-linux-${ANDROID_SDK_TOOLS_VERSION}.zip"
 ENV ANDROID_SDK_TOOLS_DL_URL="https://dl.google.com/android/repository/${ANDROID_SDK_TOOLS_ARCHIVE}"
 
@@ -76,16 +76,14 @@ RUN mkdir --parents "${ANDROID_SDK_HOME}/.android/" \
     && echo '### User Sources for Android SDK Manager' \
         > "${ANDROID_SDK_HOME}/.android/repositories.cfg"
 
-# accept Android licenses (JDK necessary!)
+# Download and accept Android licenses (JDK necessary!)
 RUN ${RETRY} apt -y install -qq --no-install-recommends openjdk-8-jdk \
     && apt -y autoremove
 RUN yes | "${ANDROID_SDK_HOME}/tools/bin/sdkmanager" "build-tools;${ANDROID_SDK_BUILD_TOOLS_VERSION}" > /dev/null
+RUN yes | "${ANDROID_SDK_HOME}/tools/bin/sdkmanager" "platforms;android-27" > /dev/null
 
-# download platforms, API, build tools
-RUN "${ANDROID_SDK_HOME}/tools/bin/sdkmanager" "platforms;android-19" && \
-    "${ANDROID_SDK_HOME}/tools/bin/sdkmanager" "platforms;android-27" && \
-    "${ANDROID_SDK_HOME}/tools/bin/sdkmanager" "build-tools;${ANDROID_SDK_BUILD_TOOLS_VERSION}" && \
-    chmod +x "${ANDROID_SDK_HOME}/tools/bin/avdmanager"
+# Set avdmanager permissions (executable)
+RUN chmod +x "${ANDROID_SDK_HOME}/tools/bin/avdmanager"
 
 
 ENV USER="user"
@@ -124,8 +122,6 @@ RUN usermod -append --groups sudo ${USER}
 RUN echo "%sudo ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
 
 
-RUN pip install --upgrade cython==0.28.6
-
 WORKDIR ${WORK_DIR}
 COPY --chown=user:user . ${WORK_DIR}
 RUN chown --recursive ${USER} ${ANDROID_SDK_HOME}
@@ -134,4 +130,5 @@ USER ${USER}
 # install python-for-android from current branch
 RUN virtualenv --python=python venv \
     && . venv/bin/activate \
+    && pip install --upgrade cython==0.28.6 \
     && pip install -e .

Dockerfile.py3

@@ -58,8 +58,8 @@ RUN ${RETRY} curl --location --progress-bar --insecure \
 ENV ANDROID_SDK_HOME="${ANDROID_HOME}/android-sdk"
 
 # get the latest version from https://developer.android.com/studio/index.html
-ENV ANDROID_SDK_TOOLS_VERSION="3859397"
-ENV ANDROID_SDK_BUILD_TOOLS_VERSION="26.0.2"
+ENV ANDROID_SDK_TOOLS_VERSION="4333796"
+ENV ANDROID_SDK_BUILD_TOOLS_VERSION="28.0.2"
 ENV ANDROID_SDK_TOOLS_ARCHIVE="sdk-tools-linux-${ANDROID_SDK_TOOLS_VERSION}.zip"
 ENV ANDROID_SDK_TOOLS_DL_URL="https://dl.google.com/android/repository/${ANDROID_SDK_TOOLS_ARCHIVE}"
 
@@ -76,16 +76,14 @@ RUN mkdir --parents "${ANDROID_SDK_HOME}/.android/" \
     && echo '### User Sources for Android SDK Manager' \
         > "${ANDROID_SDK_HOME}/.android/repositories.cfg"
 
-# accept Android licenses (JDK necessary!)
+# Download and accept Android licenses (JDK necessary!)
 RUN ${RETRY} apt -y install -qq --no-install-recommends openjdk-8-jdk \
     && apt -y autoremove
 RUN yes | "${ANDROID_SDK_HOME}/tools/bin/sdkmanager" "build-tools;${ANDROID_SDK_BUILD_TOOLS_VERSION}" > /dev/null
+RUN yes | "${ANDROID_SDK_HOME}/tools/bin/sdkmanager" "platforms;android-27" > /dev/null
 
-# download platforms, API, build tools
-RUN "${ANDROID_SDK_HOME}/tools/bin/sdkmanager" "platforms;android-19" && \
-    "${ANDROID_SDK_HOME}/tools/bin/sdkmanager" "platforms;android-27" && \
-    "${ANDROID_SDK_HOME}/tools/bin/sdkmanager" "build-tools;${ANDROID_SDK_BUILD_TOOLS_VERSION}" && \
-    chmod +x "${ANDROID_SDK_HOME}/tools/bin/avdmanager"
+# Set avdmanager permissions (executable)
+RUN chmod +x "${ANDROID_SDK_HOME}/tools/bin/avdmanager"
 
 
 ENV USER="user"
@@ -96,7 +94,7 @@ ENV WORK_DIR="${HOME_DIR}" \
 # install system dependencies
 RUN ${RETRY} apt -y install -qq --no-install-recommends \
         python3 virtualenv python3-pip python3-venv \
-        wget lbzip2 patch sudo \
+        wget lbzip2 patch sudo python python-pip \
     && apt -y autoremove
 
 # build dependencies
@@ -124,8 +122,8 @@ RUN useradd --create-home --shell /bin/bash ${USER}
 RUN usermod -append --groups sudo ${USER}
 RUN echo "%sudo ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
 
-
-RUN pip3 install --upgrade cython==0.28.6
+# install cython for python 2 (for python 3 it's inside the venv)
+RUN pip2 install --upgrade Cython==0.28.6
 
 WORKDIR ${WORK_DIR}
 COPY --chown=user:user . ${WORK_DIR}
@@ -135,4 +133,5 @@ USER ${USER}
 # install python-for-android from current branch
 RUN virtualenv --python=python3 venv \
     && . venv/bin/activate \
+    && pip3 install --upgrade Cython==0.28.6 \
     && pip3 install -e .

ci/constants.py

@@ -3,7 +3,6 @@
 
 class TargetPython(Enum):
     python2 = 0
-    python3crystax = 1
     python3 = 2
 
 
@@ -22,7 +21,6 @@ class TargetPython(Enum):
     'ffpyplayer',
     'flask',
     'groestlcoin_hash',
-    'hostpython3crystax',
     # https://github.com/kivy/python-for-android/issues/1354
     'kiwisolver',
     'libmysqlclient',
@@ -88,5 +86,5 @@ class TargetPython(Enum):
 # recipes that were already built will be skipped
 CORE_RECIPES = set([
     'pyjnius', 'kivy', 'openssl', 'requests', 'sqlite3', 'setuptools',
-    'numpy', 'android', 'python2', 'python3',
+    'numpy', 'android', 'hostpython2', 'hostpython3', 'python2', 'python3',
 ])

ci/rebuild_updated_recipes.py

@@ -28,6 +28,7 @@
 from pythonforandroid.graph import get_recipe_order_and_bootstrap
 from pythonforandroid.toolchain import current_directory
 from pythonforandroid.util import BuildInterruptingException
+from pythonforandroid.recipe import Recipe
 from ci.constants import TargetPython, CORE_RECIPES, BROKEN_RECIPES
 
 
@@ -66,7 +67,7 @@ def build(target_python, requirements):
         # iterates to stream the output
         for line in sh.python(
                 testapp, 'apk', '--sdk-dir', android_sdk_home,
-                '--ndk-dir', android_ndk_home, '--bootstrap', 'sdl2', '--requirements',
+                '--ndk-dir', android_ndk_home, '--requirements',
                 requirements, _err_to_out=True, _iter=True):
             print(line)
 
@@ -78,6 +79,18 @@ def main():
     recipes -= CORE_RECIPES
     logger.info('recipes to build: {}'.format(recipes))
     context = Context()
+
+    # removing the deleted recipes for the given target (if any)
+    for recipe_name in recipes.copy():
+        try:
+            Recipe.get_recipe(recipe_name, context)
+        except ValueError:
+            # recipe doesn't exist, so probably we remove it
+            recipes.remove(recipe_name)
+            logger.warning(
+                'removed {} from recipes because deleted'.format(recipe_name)
+            )
+
     # forces the default target
     recipes_and_target = recipes | set([target_python.name])
     try:

doc/source/apis.rst

@@ -5,6 +5,60 @@ Working on Android
 This page gives details on accessing Android APIs and managing other
 interactions on Android.
 
+Storage paths
+-------------
+
+If you want to store and retrieve data, you shouldn't just save to
+the current directory, and not hardcode `/sdcard/` or some other
+path either - it might differ per device.
+
+Instead, the `android` module which you can add to your `--requirements`
+allows you to query the most commonly required paths::
+
+      from android.storage import app_storage_path
+      settings_path = app_storage_path()
+
+      from android.storage import primary_external_storage_path
+      primary_ext_storage = primary_external_storage_path()
+
+      from android.storage import secondary_external_storage_path
+      secondary_ext_storage = secondary_external_storage_path()
+
+`app_storage_path()` gives you Android's so-called "internal storage"
+which is specific to your app and cannot seen by others or the user.
+It compares best to the AppData directory on Windows.
+
+`primary_external_storage_path()` returns Android's so-called
+"primary external storage", often found at `/sdcard/` and potentially
+accessible to any other app.
+It compares best to the Documents directory on Windows.
+Requires `Permission.WRITE_EXTERNAL_STORAGE` to read and write to.
+
+`secondary_external_storage_path()` returns Android's so-called
+"secondary external storage", often found at `/storage/External_SD/`.
+It compares best to an external disk plugged to a Desktop PC, and can
+after a device restart become inaccessible if removed.
+Requires `Permission.WRITE_EXTERNAL_STORAGE` to read and write to.
+
+.. warning::
+   Even if `secondary_external_storage_path` returns a path
+   the external sd card may still not be present.
+   Only non-empty contents or a successful write indicate that it is.
+
+Read more on all the different storage types and what to use them for
+in the Android documentation:
+
+https://developer.android.com/training/data-storage/files
+
+A note on permissions
+~~~~~~~~~~~~~~~~~~~~~
+
+Only the internal storage is always accessible with no additional
+permissions. For both primary and secondary external storage, you need
+to obtain `Permission.WRITE_EXTERNAL_STORAGE` **and the user may deny it.**
+Also, if you get it, both forms of external storage may only allow
+your app to write to the common pre-existing folders like "Music",
+"Documents", and so on. (see the Android Docs linked above for details)
 
 Runtime permissions
 -------------------

doc/source/buildoptions.rst

@@ -33,25 +33,14 @@ e.g. ``--requirements=python3``.
 
 
 CrystaX python3
-###############
+~~~~~~~~~~~~~~~
 
-.. warning:: python-for-android originally supported Python 3 using the CrystaX
-             NDK. This support is now being phased out as CrystaX is no longer
-             actively developed.
+python-for-android no longer supports building for Python 3 using the CrystaX
+NDK. Instead, use the python3 recipe, which can be built using the normal
+Google NDK.
 
-.. note:: You must manually download the `CrystaX NDK
-   <https://www.crystax.net/android/ndk>`__ and tell
-   python-for-android to use it with ``--ndk-dir /path/to/NDK``.
-
-Select this by adding the ``python3crystax`` recipe to your
-requirements, e.g. ``--requirements=python3crystax``.
-
-This uses the prebuilt Python from the `CrystaX NDK
-<https://www.crystax.net/android/ndk>`__, a drop-in replacement for
-Google's official NDK which includes many improvements. You
-*must* use the CrystaX NDK 10.3.0 or higher when building with
-python3. You can get it `here
-<https://www.crystax.net/en/download>`__.
+.. note:: The last python-for-android version supporting CrystaX was `0.7.0.
+          <https://github.com/kivy/python-for-android/archive/0.7.0.zip>`__
 
 .. _bootstrap_build_options: