Features

• OAuth-based authorization

• Send large (>10MB) files to Kindle devices

Installation

Python 3.11 or later is required. You can install Send To Kindle via pip from PyPI:

$ pip install stkclient

Creating a Client

To create a client, you must authenticate the user. Currently the only supported authentication mechanism is OAuth2:

import stkclient

a = stkclient.OAuth2()
signin_url = a.get_signin_url()
# Open `signin_url` in a browser, sign in and authorize the application, pass
# the final redirect_url below
client = a.create_client(redirect_url)

Once a client is created, it can be serialized and deserialized using Client.load / Client.loads and client.dump / client.dumps

with open('client.json', 'w') as f:
    client.dump(f)
with open('client.json', 'r') as f:
    client = stkclient.Client.load(f)

Sending a File

Once you have a Client object, you can list devices and send files to specified devices.

devices = client.get_owned_devices()
destinations = [d.device_serial_number for d in devices]
client.send_file(filepath, destinations, author=author, title=title, format="epub")

The format argument describes the input file. PDFs are delivered with their original page layout by default. To convert a PDF to Kindle format, set force_convert=True:

client.send_file(
    filepath, destinations, author=author, title=title,
    format="pdf", force_convert=True,
)

Development

Install the CI tools with Python 3.12, then run the same Nox sessions as CI:

$ python3.12 -m pip install -c .github/workflows/constraints.txt poetry poetry-plugin-export nox nox-poetry
$ nox -s tests-3.12 mypy typeguard xdoctest docs-build pre-commit audit

CI tests Python 3.11 through 3.15 and runs the newest version on Linux, macOS, and Windows. The minimum Python version follows the Python support schedule. Maintenance tools run on Python 3.12. The audit session checks locked runtime, test, and development dependencies against the PyPI vulnerability database. The documentation build treats warnings as errors. Pull requests also build the release distributions; publishing remains limited to pushes to the main branch.

Related Projects

KindBeamer a GUI application implementing the same protocol.

License

Distributed under the terms of the MIT license, Send To Kindle is free and open source software.

Credits

Project structure from @cjolowicz’s Hypermodern Python Cookiecutter template.