Package: androidstorage4kivy
Android Shared Storage 4 KivyA package for accessing Android Shared Storage.2023-11-13 This repository is archived.OverviewTo use, addandroidstorage4kivyto Buildozer requirements, see the examples.Programming ModelThe methods in this Python package provide a consistent file storage model and api across Android versions >= 5. As a result the model implements constraints that may not exist on some older versions of Android.The model consists of 'private files' which are accessed as traditional OS files, and 'shared files' which are copied or deleted by the api. 'Shared files' can be shared between apps in the usual Android ways, 'private files' cannot be shared between apps.On Android shared storage is structured as collections (Environment.DIRECTORY_MUSIC,Environment.DIRECTORY_DOCUMENTS, etc.) that each hold specific file types. Android documents thepredefined collections.ClassesThis package contains three classes,SharedStorage,ShareSheet, andChooser.SharedStorageallows copying files to and from shared storage with thecopy_to_shared(),copy_from_shared(), anddelete_shared()methods.ShareSheetallows sending plain text, or a 'shared file' to another app. Using theshare_plain_text(),share_file(), andshare_file_list()methods, these create an Android ShareSheet used to select the target app. You can also call theview_file()method to open a 'shared file' in another app - Android will try to use default application available for that specific file type.Chooserallows selecting a 'shared file' using the Android Chooser UI. The callback returns a list of one or more shared files.These classes are described in more detail in the following sections.On Android a 'shared file' is usually (but not always) implemented as an'android.net.Uri', this isnota Python file reference. Which is why we copy between shared and private files (which are Python files). For consistent behavior across Android versions use only this api to create, consume, or delete a 'shared file'.External storage must be availaible, this may not be true on older devices with a removable sdcard.On modern Android devices, and perhaps on older ones (which might alternatively use afileuri), this package depends on the Android JavaUri classto represent acontenturi. In particular two methods in this class may be usefultoString(), andparse(). Read that documentation.In Python, use these like this:content_uri_string = java_uri_class.toString()from jnius import autoclass
Uri = autoclass('android.net.Uri')
java_uri_class = Uri.parse(content_uri_string)Themusic_service_exampleuses these methods to pass uris between app and service. Because memory references cannot be passed in this case. Independent of Uri, in that case 'utf8' encoding is required byoscpy.PermissionsAndroid < 10 : WRITE_EXTERNAL_STORAGEAndroid >= 10, android.api < 33 : READ_EXTERNAL_STORAGEAndroid >= 10, android.api >= 33 : READ_MEDIA_IMAGES, READ_MEDIA_VIDEO, READ_MEDIA_AUDIO, READ_EXTERNAL_STORAGEThat Android >= 10, android.api >= 33 READ_EXTERNAL_STORAGE is for reading from the documents collection.ExamplesBasic usage,shared_storage_example.Share with another app,share_send_example.Receive from another app,share_receive_example.SharedStorage ClassOverviewUse for copying files to and from shared storage, and deleting from shared storage.The SharedStorage Class provides these methods:copy_to_shared(),copy_from_shared(),delete_shared()APIdefcopy_to_shared(private_file,collection=None,filepath=None)returnsshared_fileorNonedefcopy_from_shared(shared_file)returnsprivate_fileorNonedefdelete_shared(shared_file)returnsTrueifdeleted,elseFalseprivate_file- a fully qualified file path to a file in app private storage;copy_from_shared()copies to app private cache storage.collection- override the default collection. Must be valid for the file type. For example .jpg (defaults to DIRECTORY_PICTURES) and can be DIRECTORY_DCIM, but not DIRECTORY_MOVIES. Invalid entries are ignored and the default is used.filepath- shared storage filepath including file name, but not including 'Collection/app-Title'.shared_file- A reference to a file in shared storage returned bycopy_to_shared(). Or a string  e.g. '//sub_dir/name.ext'.There are also three utility functions:defget_cache_dir(self):returnsfilepathorNonedefget_app_title(self):returnsastringdefget_file_MIME_type(self,file_name):returnsastringcache_dirishttps://github.com/Android-for-Python/Android-for-Python-Users#app-cache-directorywith the directory"FromSharedStorage"appended.app_titleis used in the shared storage pathMIME_typeis used to determine in which collection a file belongs, it is determined based on the file externsion.Implementation DetailsMediaStore file versions (" (N)" inserted the file name) are usually not created. However when a file cannot be replaced (due to some internal permissions issue that reqires MANAGER permission to adddress) a new file version will be added. Use the File Manager app (which has MANAGER permission) to address the underlying issue.Some MIME classifications (on which Collection classification is based) have changed with Android versions. For example '.ogg' files are 'application/ogg' on older devices and 'audio/ogg' on newer devices.A share receive of a large file (such as an mp4) is slow on Android < 10. To improve performance of this case, copy thefaster_copydirectory inshare_receive_exampleto your app and in buildozer.spec addandroid.add_src = faster_copy.The Downloads directory is a special case. In this directory Android only allows access to files downloaded by the current app. The traditional common usage of Downloads as a shared pool of files is not possible.Some users want to use the original shared storage filepath, not the filepath of a copy. This is possible with the Mediastore DATA column.Howeverthis column isdeprecated, so from the point of view of this package the original shared storage filepath (DATA column) will in the long term be unsupportable.ShareSheet ClassOverviewEnables sending either plain_text, a file, or a file list to another app. The target app is selected either with the ShareSheet UI, or specified with the api argument. Android requires that the target app must declare that it is able to receive shares of this type, for more details see theshare_receive_example.APIdefshare_plain_text(self,plain_text,app=None):defshare_file(self,shared_file,app=None):defshare_file_list(self,shared_file_list,app=None):defview_file(self,shared_file):plain_textis a string.appa string identifying the target app (for example, 'com.google.android.gm' for Gmail), The default opens a ShareSheet to select a compatible app.shared_fileis a file in shared storage.shared_file_listis a list of files in shared storage.Android < 10The ShareSheet class should probably be persistent since destroying the class destroys the shared uri.Chooser ClassOverviewThe Chooser class enables opening an Android Chooser, the chosen 'shared file' or 'shared files' is returned in a callback.As an alternative to the Android Chooser, you may want to implement your own custom picker. There is an example of this in themusic_service_example. That picker queries the Mediastore and hirearchicaly organizes music by genre, album, and track; displaying album art. The same approach can be used to custom pick from other media.APIInstantiate the class with a callback method as the argument.self.chooser=Chooser(self.chooser_callback)The Chooser UI is opened withchoose_content(), this can optionally be filtered by MIME type. The Android Chooser recognizes MIME wildcards such as 'image/*' or '*/*' but not '*/jpg'.self.chooser.choose_content('video/*')The selected files are reported by the app's callback method as a list. The default is one file in the list. To enable selecting multiple files, setmultiple = True.self.chooser.choose_content('image/*',multiple=True)defchooser_callback(self,shared_file_list):self.private_files=[]ss=SharedStorage()forshared_fileinshared_file_list:self.private_files.append(ss.copy_from_shared(shared_file))