# 讀寫裝置檔案

檔案讀寫介面可讓您輕鬆地使用此功能從裝置上傳或下載檔案，支援大檔案的下載和上傳。您可以使用相關介面將檔案下載到本機或記憶體，將記憶體或本機的檔案上傳到裝置上，同時也包含刪除檔案、修改檔案權限以及獲取檔案資訊等功能。
對於不存在或無權限操作的檔案，呼叫將會引發**原生**的 Python 例外，例如 `OSError`、`FileNotFoundError`。

## 下載檔案到本機

此介面可以將裝置上的檔案下載到本機。在下述範例中，會將裝置上的檔案 `/verity_key` 的內容下載到目前電腦的 `my_file.txt` 檔案中。請注意，下載的檔案不會保留原始的權限資訊。

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

```python
>>> 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
```

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

## 下載檔案到記憶體

此介面可以將裝置上的檔案下載到記憶體中（透過 BytesIO）。

```python
from io import BytesIO
fd = BytesIO()

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


## 下載檔案到描述符

此介面可以將裝置上的檔案下載到檔案描述符，請注意檔案需要以 `wb` 二進位模式開啟。

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

## 上傳檔案到裝置

此介面可以將本機的檔案上傳到裝置上。在範例中，意指將本機的 `測試檔案.txt` 上傳到裝置的 `/data/usr/file.txt` 檔案中。上傳的檔案同樣不會保留原始的權限資訊。

```python
d.upload_file("測試檔案.txt", "/data/usr/file.txt")
```

```python
>>> 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
```

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

## 從記憶體上傳檔案

以下範例將記憶體中的檔案內容透過 BytesIO 上傳到裝置的 `/data/usr/file.txt` 檔案。

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

## 從描述符上傳檔案

以下範例將本機的檔案 `myfile.txt` 內容透過 fd 描述符上傳到裝置的 `/data/usr/file.txt` 檔案。請注意，本機的檔案需要使用 `rb` 二進位模式開啟。

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

## 刪除裝置檔案

此介面用於刪除裝置上的檔案。

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

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

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

## 修改檔案權限

此介面用於修改裝置上的檔案權限。

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

```python
>>> 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
```

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

## 獲取檔案資訊

此介面用於獲取裝置上檔案的相關資訊。

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

```python
>>> 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
```

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