# `MpyFileOpt`--Efficient MicroPython Device File System Management Tool
๐ [็ฎไฝไธญๆ](./README_zh.md)
This tool is designed for managing the file system of MicroPython devices, supporting operations such as uploading, downloading, deleting, viewing, renaming, and creating folders for the file system.
Features:
- Compared to [ampy](https://github.com/scientifichackers/ampy), it supports more file system operations.
- The average file upload speed is as high as `8.70KB/s`, and the average download speed is as high as `11.00KB/s`, which is much higher than [ampy](https://github.com/scientifichackers/ampy) and most similar tools.
Note: `1K = 1024`, the device used for testing: [HandPy](https://labplus.cn/handPy)
- Supports recursive upload, download, and deletion of non-empty folders.
- A complete device exception handling mechanism ensures stability.
It is suitable for scenarios where efficient operations on the MicroPython device file system are required, and its speed advantage is particularly evident when transferring large files.
## Installation and use
### Install
If you prefer to install directly, you can use pip (depending on the situation):
```shell
pip install mpyfileopt
```
Or, manually package and install (depending on the situation):
```shell
git clone https://github.com/emofalling/MpyFileOpt-Python.git
cd ./MpyFileOpt-Python
python -m build --wheel
# If `build` is not installed, please install `build` first (depending on the situation):
# python -m pip install build
# Then find the file with the .whl extension in ./dist, and install it using pip (depending on the situation):
python -m pip install ./dist/your_whl_file.whl
```
Otherwise, you can first clone this project and then navigate directly to the directory [./mpyfopt](./mpyfopt):
```shell
git clone https://github.com/emofalling/MpyFileOpt-Python.git
cd ./MpyFileOpt-Python/mpyfopt
# If you use this way, in subsequent commands related to mpyfopt, replace mpyfopt with ./mpyfopt or .\mpyfopt (as appropriate).
```
### Using as a Command Line Tool
Verify that you can run the mpyfopt program and get the help output:
```shell
mpyfopt --help
```
Using example:
```shell
~/myproject/micropython/mpyzip $ mpyfopt -p /dev/ttyUSB3 ls
boot.py lib main.py mpyzip.mpy
~/myproject/micropython/mpyzip $ mpyfopt -p /dev/ttyUSB3 shell
/ > push / ./tests/test_unzip.zip
Write file: /test_unzip.zip
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ 60.64/60.64 KB 8.89 KB/s eta 0:00:00
Wrote in 8.32 seconds, average speed: 8.41 KB/s
Total report: Wrote 0 directories, 1 files
/ > ls
boot.py lib main.py mpyzip.mpy test_unzip.zip
/ > exit
~/myproject/micropython/mpyzip $
```
For detailed command-line usage of `mpyfopt`, please refer to [Usage of mpyfopt Commands](./docs/cli_usage.md).
### Using as a Python Library
Execute this code in Python to import (depending on the situation):
```python
import mpyfopt
```
For detailed usage of importing `mpyfopt`, please refer to [Import and Usage of mpyfopt](./docs/import_usage.md).
## Appendix
### The choice of Block Size
It depends on the device.
When reading, the larger the block size, the faster the read speed, but it will gradually approach a critical point $^1$.
When writing, the block size is fastest at a certain critical point $^2$, but the speed decreases when it is above or below this critical point.
Whether reading or writing, if the block size is too large, the device will throw a `MemoryError` (but don't worry, the robust exception handling mechanism of `mpyfopt` makes it difficult for errors to cause crashes), making it impossible to read.
$^1$: Baudrate รท 8, in units of `B/s`. When the baudrate is `115200`, this critical point is `14.4KB/s` (`1K=1024`).
$^2$: It depends on the device. Actual tests show that a block size of `4096` bytes can ensure that most devices are close to this critical point.
Raw data
{
"_id": null,
"home_page": "https://github.com/emofalling/MpyFileOpt-Python",
"name": "mpyfileopt",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "mpyfileopt, mpyfopt, python, micropython, windows, linux, mac, ampy",
"author": "emofalling",
"author_email": "emofalling@dingtalk.com",
"download_url": "https://files.pythonhosted.org/packages/4f/ef/fea9032d36bf372548b121002eddf5fe7b40036b592697013bf0a2e61720/mpyfileopt-1.1.tar.gz",
"platform": null,
"description": "# `MpyFileOpt`--Efficient MicroPython Device File System Management Tool\r\n\r\n\ud83c\udf10 [\u7b80\u4f53\u4e2d\u6587](./README_zh.md)\r\n\r\nThis tool is designed for managing the file system of MicroPython devices, supporting operations such as uploading, downloading, deleting, viewing, renaming, and creating folders for the file system.\r\n\r\nFeatures:\r\n\r\n- Compared to [ampy](https://github.com/scientifichackers/ampy), it supports more file system operations.\r\n- The average file upload speed is as high as `8.70KB/s`, and the average download speed is as high as `11.00KB/s`, which is much higher than [ampy](https://github.com/scientifichackers/ampy) and most similar tools. \r\nNote: `1K = 1024`, the device used for testing: [HandPy](https://labplus.cn/handPy)\r\n- Supports recursive upload, download, and deletion of non-empty folders.\r\n- A complete device exception handling mechanism ensures stability.\r\n\r\nIt is suitable for scenarios where efficient operations on the MicroPython device file system are required, and its speed advantage is particularly evident when transferring large files.\r\n\r\n## Installation and use\r\n\r\n### Install\r\n\r\nIf you prefer to install directly, you can use pip (depending on the situation):\r\n\r\n```shell\r\npip install mpyfileopt\r\n```\r\n\r\nOr, manually package and install (depending on the situation):\r\n\r\n```shell\r\ngit clone https://github.com/emofalling/MpyFileOpt-Python.git\r\ncd ./MpyFileOpt-Python\r\n\r\npython -m build --wheel\r\n# If `build` is not installed, please install `build` first (depending on the situation):\r\n# python -m pip install build\r\n\r\n# Then find the file with the .whl extension in ./dist, and install it using pip (depending on the situation):\r\npython -m pip install ./dist/your_whl_file.whl\r\n```\r\n\r\nOtherwise, you can first clone this project and then navigate directly to the directory [./mpyfopt](./mpyfopt):\r\n\r\n```shell\r\ngit clone https://github.com/emofalling/MpyFileOpt-Python.git\r\ncd ./MpyFileOpt-Python/mpyfopt\r\n# If you use this way, in subsequent commands related to mpyfopt, replace mpyfopt with ./mpyfopt or .\\mpyfopt (as appropriate).\r\n```\r\n\r\n### Using as a Command Line Tool\r\n\r\nVerify that you can run the mpyfopt program and get the help output:\r\n\r\n```shell\r\nmpyfopt --help\r\n```\r\n\r\nUsing example:\r\n\r\n```shell\r\n~/myproject/micropython/mpyzip $ mpyfopt -p /dev/ttyUSB3 ls\r\nboot.py lib main.py mpyzip.mpy\r\n~/myproject/micropython/mpyzip $ mpyfopt -p /dev/ttyUSB3 shell\r\n/ > push / ./tests/test_unzip.zip\r\nWrite file: /test_unzip.zip\r\n \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501 60.64/60.64 KB 8.89 KB/s eta 0:00:00\r\nWrote in 8.32 seconds, average speed: 8.41 KB/s\r\nTotal report: Wrote 0 directories, 1 files\r\n/ > ls\r\nboot.py lib main.py mpyzip.mpy test_unzip.zip\r\n/ > exit\r\n~/myproject/micropython/mpyzip $\r\n```\r\n\r\nFor detailed command-line usage of `mpyfopt`, please refer to [Usage of mpyfopt Commands](./docs/cli_usage.md).\r\n\r\n### Using as a Python Library\r\n\r\nExecute this code in Python to import (depending on the situation):\r\n\r\n```python\r\nimport mpyfopt\r\n```\r\n\r\nFor detailed usage of importing `mpyfopt`, please refer to [Import and Usage of mpyfopt](./docs/import_usage.md).\r\n\r\n## Appendix\r\n\r\n### The choice of Block Size\r\n\r\nIt depends on the device.\r\n\r\nWhen reading, the larger the block size, the faster the read speed, but it will gradually approach a critical point $^1$. \r\nWhen writing, the block size is fastest at a certain critical point $^2$, but the speed decreases when it is above or below this critical point.\r\n\r\nWhether reading or writing, if the block size is too large, the device will throw a `MemoryError` (but don't worry, the robust exception handling mechanism of `mpyfopt` makes it difficult for errors to cause crashes), making it impossible to read.\r\n\r\n$^1$: Baudrate \u00f7 8, in units of `B/s`. When the baudrate is `115200`, this critical point is `14.4KB/s` (`1K=1024`). \r\n$^2$: It depends on the device. Actual tests show that a block size of `4096` bytes can ensure that most devices are close to this critical point.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Efficient MicroPython Device File System Management Tool",
"version": "1.1",
"project_urls": {
"Homepage": "https://github.com/emofalling/MpyFileOpt-Python"
},
"split_keywords": [
"mpyfileopt",
" mpyfopt",
" python",
" micropython",
" windows",
" linux",
" mac",
" ampy"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4feffea9032d36bf372548b121002eddf5fe7b40036b592697013bf0a2e61720",
"md5": "ddb96cec9245112565b18f5af9f7c08b",
"sha256": "37e74aa9210c1957d3f970395c3a57ef8dc0c58fc78fb43ba045b81000eda461"
},
"downloads": -1,
"filename": "mpyfileopt-1.1.tar.gz",
"has_sig": false,
"md5_digest": "ddb96cec9245112565b18f5af9f7c08b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 25385,
"upload_time": "2025-02-08T09:37:45",
"upload_time_iso_8601": "2025-02-08T09:37:45.845305Z",
"url": "https://files.pythonhosted.org/packages/4f/ef/fea9032d36bf372548b121002eddf5fe7b40036b592697013bf0a2e61720/mpyfileopt-1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-08 09:37:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "emofalling",
"github_project": "MpyFileOpt-Python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mpyfileopt"
}
JSON
