qBittorrent Web API Client¶
Introduction¶
Python client implementation for qBittorrent Web API.
Currently supports up to qBittorrent v4.2.5 (Web API v2.5.1) released on April 24, 2020.
Features¶
- The entire qBittorent Web API is implemented.
- qBittorrent version checking for an endpoint’s existence/features is automatically handled.
- All Python versions are supported.
- If the authentication cookie expires, a new one is automatically requested in line with any API call.
Installation¶
- Install via pip from PyPI:
pip install qbittorrent-api
- Install specific release:
pip install git+https://github.com/rmartin16/qbittorrent-api.git@v2020.6.4#egg=qbittorrent-api
- Install direct from master:
pip install git+https://github.com/rmartin16/qbittorrent-api.git#egg=qbittorrent-api
- Ensure urllib3, requests, and attrdict are installed. (These are installed automatically using the methods above.)
- Enable WebUI in qBittorrent: Tools -> Preferences -> Web UI
- If the Web API will be exposed to the Internet, follow the recommendations.
Getting Started¶
import qbittorrentapi
# instantiate a Client using the appropriate WebUI configuration
qbt_client = qbittorrentapi.Client(host='localhost:8080', username='admin', password='adminadmin')
# the Client will automatically acquire/maintain a logged in state in line with any request.
# therefore, this is not necessary; however, you many want to test the provided login credentials.
try:
qbt_client.auth_log_in()
except qbittorrentapi.LoginFailed as e:
print(e)
# display qBittorrent info
print(f'qBittorrent: {qbt_client.app.version}')
print(f'qBittorrent Web API: {qbt_client.app.web_api_version}')
for k,v in qbt_client.app.build_info.items(): print(f'{k}: {v}')
# retrieve and show all torrents
for torrent in qbt_client.torrents_info():
print(f'{torrent.hash[-6:]}: {torrent.name} ({torrent.state})')
# pause all torrents
qbt_client.torrents.pause.all()
Usage¶
First, the Web API endpoints are organized in to eight namespaces.
- Authentication (auth)
- Application (app)
- Log (log)
- Sync (sync)
- Transfer (transfer)
- Torrent Management (torrents)
- RSS (rss)
- Search (search)
Second, this client has two modes of interaction with the qBittorrent Web API.
Each Web API endpoint is implemented one-to-one as a method of the instantiated client.
import qbittorrentapi
qbt_client = qbittorrentapi.Client(host='localhost:8080', username='admin', password='adminadmin')
qbt_client.app_version()
qbt_client.rss_rules()
qbt_client.torrents_info()
qbt_client.torrents_resume(torrent_hashes='...')
# and so on
However, a more robust interface to the endpoints is available via each namespace. This is intended to provide a more seamless and intuitive interface to the Web API.
import qbittorrentapi
qbt_client = qbittorrentapi.Client(host='localhost:8080', username='admin', password='adminadmin')
# changing a preference
is_dht_enabled = qbt_client.app.preferences.dht
qbt_client.app.preferences = dict(dht=not is_dht_enabled)
# stopping all torrents
qbt_client.torrents.pause.all()
# retrieve different views of the log
qbt_client.log.main.warning()
qbt_client.log.main.normal()
Finally, some of the objects returned by the client support methods of their own. This is most pronounced for torrents themselves.
import qbittorrentapi
qbt_client = qbittorrentapi.Client(host='localhost:8080', username='admin', password='adminadmin')
for torrent in qbt_client.torrents.info.active():
torrent.set_location(location='/home/user/torrents/')
torrent.reannounce()
torrent.upload_limit = -1