| Name | pybooxdrop JSON |
| Version |
0.1.3
JSON |
| download |
| home_page | None |
| Summary | A friendly Python wrapper for the BOOXDrop API — unofficial, but built with care. |
| upload_time | 2025-07-09 22:12:01 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | MIT |
| keywords |
api
boox
ebook
onyx
reader
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 📖 pyBooxDrop
[](https://pypi.org/project/booxdrop/)
[](https://pypi.org/project/booxdrop/)
[](https://github.com/filipgodlewski/pyBooxDrop/blob/main/LICENSE)
<div>
🐍 A friendly Python wrapper for the BOOXDrop API — unofficial, but built with care.
<br>
📚 Great if you want to manage files on your BOOX device programmatically, automate uploads/downloads,
or plug it into your own tools and scripts.
</div>
---
## ✨ Features
- Clean and consistent API client for BOOXDrop
- Fully typed (with `pydantic`) and 100% modern Python 3.12+
- No external HTTP dependency — bring your own client, if you will
- HTTP client agnostic – plug in your own via simple `HttpClient` interface
- Open-source, MIT-licensed, built with readability in mind
<details>
<summary>Supported endpoints</summary>
```http
POST /users/sendVerifyCode
```
</details>
---
## 📦 Installation
```bash
pip install pybooxdrop
```
---
## 🚀 Quick start
```python
from boox import Boox
# Given it is the very first connection, and no token is available:
with Boox(base_url="eur.boox.com") as client:
payload = {"mobi": "foo@bar.com"}
_ = client.users.send_verification_code(payload=payload)
# OR, if you don't want to use the context manager
client = Boox(base_url="eur.boox.com")
payload = {"mobi": "foo@bar.com"}
_ = client.users.send_verification_code(payload=payload)
client.close()
```
---
## 🔌 Custom HTTP client support
Boox lets you plug in your own HTTP client.
To do this, implement a simple `HttpClient` protocol with the required methods and pass your adapter to `Boox`.
<details>
<summary>Example</summary>
```python
import httpx
from boox import Boox, HttpClient
class MyAdapter(HttpClient):
def post(self, url: str, json: dict | None = None) -> Any:
# your logic using requests, httpx, or anything else
...
with Boox(client=MyAdapter(httpx.Client())) as boox: ...
```
</details>
Why?
This gives you full control over things like:
- ⏰ timeouts
- ♻️ retries
- 🧾 logging
- 🌍 proxies or custom headers
- 🔐 session/cookie handling
> By design, Boox does **not** depend on any specific HTTP library.
> It only uses Python’s built-in `urllib` by default — you're free to use
> [`requests`](https://docs.python-requests.org/), [`httpx`](https://www.python-httpx.org/), or your own logic.
---
## 🧪 Testing
### Running unit tests
```bash
# to run all but e2e tests do the following:
uv sync
uv run pytest
```
Alternatively, use:
```bash
make test
```
### Running E2E tests
Please note that since the E2E tests are heavy, require real internet connection,
and they connect with the real BOOXDrop server, it is not recommended to run them often.
```bash
# required environment variables:
# E2E_SMTP_EMAIL - the e-mail address on smtp.dev
# E2E_SMTP_X_API_KEY - the X-API-KEY for the account
# E2E_TARGET_DOMAIN - the target BOOXDrop domain, e.g. push.boox.com
uv sync
uv run pytest -m e2e --e2e
```
Alternatively, use:
```bash
make e2e
```
- `E2E_SMTP_EMAIL` must lead to an e-mail that is connected to a real Boox account. It must be verified prior to the tests.
- `E2E_TARGET_DOMAIN` is the domain that the Boox account is used with.
AFAIK it can be any Boox' domain, because the account is not bound to any in particular.
This might change in the future though, so I would rather play safe there.
- `X-API-KEY` for [SMTP.dev](https://smtp.dev/) is required, as this is the client that is being used.
Currently there are no plans to support other providers.
---
## 📮 Feedback
Got ideas, feedback, or feature requests? Feel free to open an issue or pull request!
---
## 👷 Contributing
Contributions are welcome!
- Please fork the repository and create a branch for your feature or bugfix.
- Use pytest to run tests and add new tests when applicable.
- Follow the existing code style, checked by ruff, bandit and pyupgrade.
- Open a pull request with a clear description of your changes.
---
## 🫶 Special thanks
Big thanks to [hrw](https://github.com/hrw) for the project [onyx-send2boox](https://github.com/hrw/onyx-send2boox).
The project was the main inspiration behind this library.
While pyBooxDrop is a fresh, focused take on just the API, this project wouldn’t exist without this awesome groundwork.
Thanks for the great job!
---
## 🪪 License
MIT – use it, hack it, ship it.
Raw data
{
"_id": null,
"home_page": null,
"name": "pybooxdrop",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "api, boox, ebook, onyx, reader",
"author": null,
"author_email": "Filip Godlewski <54432731+filipgodlewski@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/19/44/e7ac76d91213b4aa67871cf89d653201da3fda10ea893a750744347cb770/pybooxdrop-0.1.3.tar.gz",
"platform": null,
"description": "# \ud83d\udcd6 pyBooxDrop\n\n\n[](https://pypi.org/project/booxdrop/)\n[](https://pypi.org/project/booxdrop/)\n[](https://github.com/filipgodlewski/pyBooxDrop/blob/main/LICENSE)\n\n<div>\n\ud83d\udc0d A friendly Python wrapper for the BOOXDrop API \u2014 unofficial, but built with care.\n<br>\n\ud83d\udcda Great if you want to manage files on your BOOX device programmatically, automate uploads/downloads,\nor plug it into your own tools and scripts.\n</div>\n\n---\n\n## \u2728 Features\n\n- Clean and consistent API client for BOOXDrop\n- Fully typed (with `pydantic`) and 100% modern Python 3.12+\n- No external HTTP dependency \u2014 bring your own client, if you will\n- HTTP client agnostic \u2013 plug in your own via simple `HttpClient` interface\n- Open-source, MIT-licensed, built with readability in mind\n\n<details>\n\n <summary>Supported endpoints</summary>\n\n```http\nPOST /users/sendVerifyCode\n```\n\n</details>\n\n---\n\n## \ud83d\udce6 Installation\n\n```bash\npip install pybooxdrop\n```\n\n---\n\n## \ud83d\ude80 Quick start\n\n```python\nfrom boox import Boox\n\n# Given it is the very first connection, and no token is available:\nwith Boox(base_url=\"eur.boox.com\") as client:\n payload = {\"mobi\": \"foo@bar.com\"}\n _ = client.users.send_verification_code(payload=payload)\n\n# OR, if you don't want to use the context manager\n\nclient = Boox(base_url=\"eur.boox.com\")\npayload = {\"mobi\": \"foo@bar.com\"}\n_ = client.users.send_verification_code(payload=payload)\nclient.close()\n```\n\n---\n\n## \ud83d\udd0c Custom HTTP client support\n\nBoox lets you plug in your own HTTP client.\nTo do this, implement a simple `HttpClient` protocol with the required methods and pass your adapter to `Boox`.\n\n<details>\n<summary>Example</summary>\n\n```python\nimport httpx\nfrom boox import Boox, HttpClient\n\nclass MyAdapter(HttpClient):\n def post(self, url: str, json: dict | None = None) -> Any:\n # your logic using requests, httpx, or anything else\n ...\n\nwith Boox(client=MyAdapter(httpx.Client())) as boox: ...\n```\n\n</details>\n\nWhy?\nThis gives you full control over things like:\n\n- \u23f0 timeouts\n- \u267b\ufe0f retries\n- \ud83e\uddfe logging\n- \ud83c\udf0d proxies or custom headers\n- \ud83d\udd10 session/cookie handling\n\n> By design, Boox does **not** depend on any specific HTTP library.\n> It only uses Python\u2019s built-in `urllib` by default \u2014 you're free to use\n> [`requests`](https://docs.python-requests.org/), [`httpx`](https://www.python-httpx.org/), or your own logic.\n\n---\n\n## \ud83e\uddea Testing\n\n### Running unit tests\n\n```bash\n# to run all but e2e tests do the following:\nuv sync\nuv run pytest\n```\n\nAlternatively, use:\n\n```bash\nmake test\n```\n\n### Running E2E tests\n\nPlease note that since the E2E tests are heavy, require real internet connection,\nand they connect with the real BOOXDrop server, it is not recommended to run them often.\n\n```bash\n# required environment variables:\n# E2E_SMTP_EMAIL - the e-mail address on smtp.dev\n# E2E_SMTP_X_API_KEY - the X-API-KEY for the account\n# E2E_TARGET_DOMAIN - the target BOOXDrop domain, e.g. push.boox.com\nuv sync\nuv run pytest -m e2e --e2e\n```\n\nAlternatively, use:\n\n```bash\nmake e2e\n```\n\n- `E2E_SMTP_EMAIL` must lead to an e-mail that is connected to a real Boox account. It must be verified prior to the tests.\n- `E2E_TARGET_DOMAIN` is the domain that the Boox account is used with.\n AFAIK it can be any Boox' domain, because the account is not bound to any in particular.\n This might change in the future though, so I would rather play safe there.\n- `X-API-KEY` for [SMTP.dev](https://smtp.dev/) is required, as this is the client that is being used.\n Currently there are no plans to support other providers.\n\n---\n\n## \ud83d\udcee Feedback\n\nGot ideas, feedback, or feature requests? Feel free to open an issue or pull request!\n\n---\n\n## \ud83d\udc77 Contributing\n\nContributions are welcome!\n\n- Please fork the repository and create a branch for your feature or bugfix.\n- Use pytest to run tests and add new tests when applicable.\n- Follow the existing code style, checked by ruff, bandit and pyupgrade.\n- Open a pull request with a clear description of your changes.\n\n---\n\n## \ud83e\udef6 Special thanks\n\nBig thanks to [hrw](https://github.com/hrw) for the project [onyx-send2boox](https://github.com/hrw/onyx-send2boox).\nThe project was the main inspiration behind this library.\nWhile pyBooxDrop is a fresh, focused take on just the API, this project wouldn\u2019t exist without this awesome groundwork.\n\nThanks for the great job!\n\n---\n\n## \ud83e\udeaa License\n\nMIT \u2013 use it, hack it, ship it.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A friendly Python wrapper for the BOOXDrop API \u2014 unofficial, but built with care.",
"version": "0.1.3",
"project_urls": null,
"split_keywords": [
"api",
" boox",
" ebook",
" onyx",
" reader"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3f941dfec05b27345f19c030cfe3f35e765549960742720baa41c335d8fd172f",
"md5": "c887aabdeef280c8bfda8b5aaaf55718",
"sha256": "a363d151b1dda270c8972b30da082f37617989180e8a0e9ec8eb99f5e3b80499"
},
"downloads": -1,
"filename": "pybooxdrop-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c887aabdeef280c8bfda8b5aaaf55718",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 10864,
"upload_time": "2025-07-09T22:12:00",
"upload_time_iso_8601": "2025-07-09T22:12:00.932831Z",
"url": "https://files.pythonhosted.org/packages/3f/94/1dfec05b27345f19c030cfe3f35e765549960742720baa41c335d8fd172f/pybooxdrop-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1944e7ac76d91213b4aa67871cf89d653201da3fda10ea893a750744347cb770",
"md5": "8feb77c04e94a4a1ba7b68ffb9deb370",
"sha256": "af3200b1a4e5408b4aff8ea3d3ddef80cd94b47d216473890387e66b36d3946d"
},
"downloads": -1,
"filename": "pybooxdrop-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "8feb77c04e94a4a1ba7b68ffb9deb370",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 28277,
"upload_time": "2025-07-09T22:12:01",
"upload_time_iso_8601": "2025-07-09T22:12:01.941715Z",
"url": "https://files.pythonhosted.org/packages/19/44/e7ac76d91213b4aa67871cf89d653201da3fda10ea893a750744347cb770/pybooxdrop-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 22:12:01",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pybooxdrop"
}
