fix: Convert Android permission int values to True/False

Add docstrings

Author: gbm001

pythonforandroid/recipes/android/src/android/permissions.py

@@ -423,6 +423,10 @@ class Permission:
         )
 
 
+PERMISSION_GRANTED = 0
+PERMISSION_DENIED = -1
+
+
 class _onRequestPermissionsCallback(PythonJavaClass):
     """Callback class for registering a Python callback from
     onRequestPermissionsResult in PythonActivity.
@@ -441,8 +445,7 @@ def onRequestPermissionsResult(self, requestCode,
 
 
 class _RequestPermissionsManager:
-    """Internal class for requesting Android permissions via
-    requestPermissions, including registering callbacks to requestPermissions.
+    """Internal class for requesting Android permissions.
 
     Permissions are requested through the method 'request_permissions' which
     accepts a list of permissions and an optional callback.
@@ -465,10 +468,18 @@ class _RequestPermissionsManager:
     onRequestPermissionsCallback, which allows the Java callback to be
     propagated to the class method 'python_callback'. This is then, in turn,
     used to call an application callback if provided to request_permissions.
+
+    The attribute '_callback_id' is incremented with each call to
+    request_permissions which has a callback (the value '1' is used for any
+    call which does not pass a callback). This is passed to requestCode in
+    the Java call, and used to identify (via the _callbacks dictionary)
+    the matching call.
     """
     _java_callback = None
     _callbacks = {1: None}
     _callback_id = 1
+    # Lock to prevent multiple calls to request_permissions being handled
+    # simultaneously (as incrementing _callback_id is not atomic)
     _lock = threading.Lock()
 
     @classmethod
@@ -484,7 +495,7 @@ def request_permissions(cls, permissions, callback=None):
         If 'callback' is supplied, the request is made with a new requestCode
         and the callback is stored in the _callbacks dict. When a Java callback
         with the matching requestCode is received, callback will be called
-        with arguments of 'permissions' and 'grantResults'.
+        with arguments of 'permissions' and 'grant_results'.
         """
         with cls._lock:
             if not cls._java_callback:
@@ -502,13 +513,54 @@ def request_permissions(cls, permissions, callback=None):
     def python_callback(cls, requestCode, permissions, grantResults):
         """Calls the relevant callback with arguments of 'permissions'
         and 'grantResults'."""
+        # Convert from Android codes to True/False
+        grant_results = [x == PERMISSION_GRANTED for x in grantResults]
         if cls._callbacks.get(requestCode):
-            cls._callbacks[requestCode](permissions, grantResults)
+            cls._callbacks[requestCode](permissions, grant_results)
 
 
 # Public API methods for requesting permissions
 
 def request_permissions(permissions, callback=None):
+    """Requests Android permissions.
+
+    Args:
+        permissions (str): A list of permissions to requests (str)
+        callback (callable, optional): A function to call when the request
+            is completed (callable)
+
+    Returns:
+        None
+
+    Notes:
+
+    Permission strings can be imported from the 'Permission' class in this
+    module. For example:
+
+    from android import Permission
+        permissions_list = [Permission.CAMERA,
+                            Permission.WRITE_EXTERNAL_STORAGE]
+
+    See the p4a source file 'permissions.py' for a list of valid permission
+    strings (pythonforandroid/recipes/android/src/android/permissions.py).
+
+    Any callback supplied must accept two arguments:
+       permissions (list of str): A list of permission strings
+       grant_results (list of bool): A list of bools indicating whether the
+           respective permission was granted.
+    See Android documentation for onPermissionsCallbackResult for
+    further information.
+
+    Note that if the request is interupted the callback may contain an empty
+    list of permissions, without permissions being granted; the App should
+    check that each permission requested has been granted.
+
+    Also note that calling request_permission on SDK_INT < 23 will return
+    immediately (as run-time permissions are not required), and so the callback
+    will never happen. Therefore, request_permissions should only be called
+    with a callback if calling check_permission has indicated that it is
+    necessary.
+    """
     _RequestPermissionsManager.request_permissions(permissions, callback)
 
 
@@ -517,6 +569,14 @@ def request_permission(permission, callback=None):
 
 
 def check_permission(permission):
+    """Checks if an app holds the passed permission.
+
+    Args:
+        - permission     An Android permission (str)
+
+    Returns:
+        bool: True if the app holds the permission given, False otherwise.
+    """
     python_activity = autoclass('org.kivy.android.PythonActivity')
     result = bool(python_activity.checkCurrentPermission(
         permission + ""