Reading and Writing Device Files

The file read and write interface allows you to easily upload or download files from a device. It supports uploading and downloading large files. You can use the provided APIs to download files to your local machine or memory, or upload files from memory or your local system to the device. Additional functionalities include deleting files, modifying file permissions, and retrieving file information.

For operations on files that do not exist or for which the user lacks permission, calling these interfaces will raise native Python exceptions such as OSError or FileNotFoundError.

Downloading a File to Local Storage

This API downloads a file from the device to your local machine. In the example below, the content of the file /verity_key on the device is downloaded to a local file named my_file.txt. Note that downloaded files do not retain their original permission attributes.

d.download_file("/verity_key", "my_file.txt")

>>> d.download_file("/adb_keys", "my_file.txt")
name: "adb_keys"
path: "/adb_keys"
st_mode: 33188
st_atime: 1230768000
st_mtime: 1230768000
st_ctime: 1230768000
st_size: 2202

>>> result = d.download_file("/adb_keys", "my_file.txt")
>>> print(result.st_mtime)
1230768000
>>> os.chmod("my_file.txt", result.st_mode)

Downloading a File into Memory

This API downloads a file from the device into memory using BytesIO.

from io import BytesIO
fd = BytesIO()

d.download_fd("/verity_key", fd)
print(fd.getvalue())

Downloading a File to a File Descriptor

This API downloads a file from the device to a file descriptor. Note that the file must be opened in binary write mode (wb).

fd = open("my_file.txt", "wb")
d.download_fd("/verity_key", fd)

Uploading a File to the Device

This API uploads a local file to the device. In the example below, the local file 测试文件.txt is uploaded to /data/usr/file.txt on the device. Uploaded files do not retain their original permission attributes.

d.upload_file("测试文件.txt", "/data/usr/file.txt")

>>> d.upload_file("file.txt", "/data/usr/file.txt")
name: "file.txt"
path: "/data/usr/file.txt"
st_mode: 33184
st_atime: 1230768000
st_mtime: 1230768000
st_ctime: 1230768000

>>> result = d.upload_file("file.txt", "/data/usr/file.txt")
>>> print(result.st_size)
0

Uploading a File from Memory

In the example below, file content stored in memory via BytesIO is uploaded to /data/usr/file.txt on the device.

from io import BytesIO
d.upload_fd(BytesIO(b"fileContent"), "/data/usr/file.txt")

Uploading a File from a File Descriptor

In the example below, the content of the local file myfile.txt is uploaded to /data/usr/file.txt on the device via a file descriptor. Note that the local file must be opened in binary read mode (rb).

fd = open("myfile.txt", "rb")
d.upload_fd(fd, "/data/usr/file.txt")

Deleting a Device File

This API deletes a file on the device.

d.delete_file("/data/usr/file.txt")

>>> d.delete_file("/data/usr/file.txt")
True

>>> d.delete_file("/adb_keys")
Traceback (most recent call last):
  File "<console>", line 1, in <module>
OSError: [Errno 30] Read-only file system

Modifying File Permissions

This API modifies the permissions of a file on the device.

d.file_chmod("/data/usr/file.txt", mode=0o777)

>>> d.file_chmod("/data/usr/file.txt", mode=0o777)
name: "file.txt"
path: "/data/usr/file.txt"
st_mode: 33279
st_atime: 1230768000
st_mtime: 1230768000
st_ctime: 1230768000

>>> result = d.file_chmod("/data/usr/file.txt", mode=0o777)
>>> print(oct(result.st_mode))
0o100777

Retrieving File Information

This API retrieves information about a file on the device.

d.file_stat("/data/usr/file.txt")

>>> d.file_stat("/data/usr/file.txt")
name: "file.txt"
path: "/data/usr/file.txt"
st_mode: 33279
st_atime: 1230768000
st_mtime: 1230768000
st_ctime: 1230768000

>>> result = d.file_stat("/data/usr/file.txt")
>>> print(result.name)
'file.txt'