<h1 align="center"><b>Aiotorrent</b></h1>
Aiotorrent is an asynchronous, ultra-lightweight torrent library written in pure Python with support for unique features such as serving of files over HTTP without downloading to disk & more.
<br>
A comprehensive list of features supported by aiotorrent as of now are:
- Complete asyncio support
- Connecting to various types of torrent trackers (HTTP & UDP)
- Specifying an appropriate piece download strategy (default and sequential downloading)
- Downloading files to disk
- Serving files over HTTP without saving them to disk
<br>
> [!NOTE]
> This library is still in active development and many additional features such as downloading files from a magnet link, resuming torrent downloads, etc are yet to (but soon will) be implemented.
<br />
# Requirements
1. **Dependencies:** aiotorrent is built to be extremely lite-weight, only 3 dependencies required for the core functionality:
- [`fastbencode`](https://pypi.org/project/fastbencode/)
- [`bitstring`](https://pypi.org/project/bitstring/)
2. **Streaming dependencies:** built-in support for streaming files over HTTP. To use this feature, you need to install extra streaming dependencies.
<br />
# Installation
Install aiotorrent from PyPI using:
```
$ pip install aiotorrent
```
In order to use the streaming feature, you can install the dependencies using:
```
$ pip install aiotorrent[stream-support]
```
<br />
# Quickstart
### Initialisation
```python
# Import the Torrent class and pass a torrent file to it:
# You can either pass the file path or a file-like object. aiotorrent will handle it internally.
from aiotorrent import Torrent
torrent = Torrent('path/to/file.torrent')
# To initialise the torrent, you need to call the init() coroutine.
await torrent.init()
```
## Getting peers via DHT
While it is not a requirement, it is highly recommended to do use DHT (Distributed Hash Table) for peer discovery, which in turn can lead to better file retrieval speeds. To let aiotorrent perform peer discovery via DHT, you can pass the `dht_enabled=True` parameter to the `init()` coroutine, as follows:
```python
await torrent.init(dht_enabled=True)
```
> [!NOTE]
> The current implementation of DHT is hardcoded to fetch a minimum of 100 peers
> [!CAUTION]
In some cases this can prevent the torrent from initializing when there are not enough peers available. This behavior will be fixed in a future release.
## Downloading & Streaming
Torrent files are stored inside `Torrent.files` as a list. We can access them by sub-scripting the `Torrent.files` attribute, like as follows:
### Example to download and stream files
```python
# To download the third file
await torrent.download(torrent.files[2])
```
Similarly, to serve a torrent file over HTTP, you can call the `stream()` coroutine, as follows:
```python
# To stream the second file, etc
await torrent.stream(torrent.files[1])
```
This starts up a [`uvicorn`](https://github.com/encode/uvicorn) server on `localhost:8080` which uses [`starlette`](https://github.com/encode/starlette) behind the scenes as the ASGI framework to stream files over http.
### Piece downloading strategy
You can also change how pieces of a particular file are being downloaded. Currently, this library offers two download strategies:
- *Default*: This strategy is used when the `strategy` parameter is not specified to the `Torrent.download()` function. It downloads file pieces in a pseudo-sequential manner. For instance, it will start fetching pieces in order, but **it may or may not yield the pieces in order**.
- *Sequential*: This strategy is straight forward, and it **always yields pieces in a sequential manner**.
> [!IMPORTANT]
> The `stream()` coroutine always uses the SEQUENTIAL download strategy, and this behaviour cannot be changed.
```python
from aiotorrent import DownloadStrategy
from aiotorrent import Torrent
torrent = Torrent("path/to/file.torrent")
file = torrent.files[1]
# The download strategies available are: DownloadStrategy.DEFAULT and DownloadStrategy.SEQUENTIAL
await torrent.download(file, strategy=DownloadStrategy.SEQUENTIAL)
```
### Getting the download progress
Each torrent file inside `Torrent.files` has the following functions to get useful statistics about the download progress:
1. `get_bytes_downloaded()`: Returns the total number of bytes downloaded so far for a particular file. This also includes the number of bytes which may not be written to disk (ie the piece validation failed, and the piece was discarded).
2. `get_bytes_written()`: Returns the number of bytes written to disk for a particular file.
3. `get_download_progress(precision=2)`: Returns the download progress in percentage for a particular file. The precision parameter specifies the number of decimal places to round off the result to
```python
file = torrent.files[0]
print(f"Total bytes downloaded: {file.get_bytes_downloaded()} bytes")
# Output: Total bytes downloaded: 1048576 bytes
print(f"Download progress: {file.get_bytes_written()} / {file.size} bytes")
# Output: Download progress: 1048576 / 5242880 bytes
print(f"Download progress: {file.get_download_progress(precision=3)}%")
# Output: Download progress: 20.152%
```
# aiotorrent CLI
Starting from versions 0.9.0, aiotorrent ships with a cli which can be directly invoked from the terminal, if PYTHONPATH is set correctly. The usage is fairly simple, and self explanatory:
```bash
$ aiotorrent
usage: aiotorrent [-h] [-v] {download,stream,info} ...
aiotorrent CLI for downloading and streaming torrents.
positional arguments:
{download,stream,info}
Available commands
download Download torrent files
stream Stream files over HTTP
info Parse and show torrent metadata
options:
-h, --help show this help message and exit
-v, --verbose Show verbose output. Use -vv, -vvv, etc for increased verbosity
```
# Contribution Guidelines
This project is open to contributions. Feel free to open issues on bug reports or feature requests.
Please ensure that you open an issue before submitting a pull request. Also refrain from making pull requests directly to the main branch.
<br>
_The above methods can take additional parameters to customize the behaviour of this library. [Read the documentation]() to know more._
Raw data
{
"_id": null,
"home_page": "https://github.com/Mys7erio/aiotorrent",
"name": "aiotorrent",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "python, python3, bittorrent, bittorrent-client, downloading, streaming",
"author": "Shakir",
"author_email": "shakirali.sacube@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a1/b0/bd70edb706e2f370f4fb3f9921db425dd3435be1b0038f877827f4e8ee89/aiotorrent-0.9.1.tar.gz",
"platform": null,
"description": "<h1 align=\"center\"><b>Aiotorrent</b></h1>\nAiotorrent is an asynchronous, ultra-lightweight torrent library written in pure Python with support for unique features such as serving of files over HTTP without downloading to disk & more. \n\n<br>\nA comprehensive list of features supported by aiotorrent as of now are:\n\n - Complete asyncio support\n - Connecting to various types of torrent trackers (HTTP & UDP)\n - Specifying an appropriate piece download strategy (default and sequential downloading)\n - Downloading files to disk\n - Serving files over HTTP without saving them to disk\n\n<br>\n\n> [!NOTE]\n> This library is still in active development and many additional features such as downloading files from a magnet link, resuming torrent downloads, etc are yet to (but soon will) be implemented.\n\n<br />\n\n# Requirements\n\n1. **Dependencies:** aiotorrent is built to be extremely lite-weight, only 3 dependencies required for the core functionality:\n - [`fastbencode`](https://pypi.org/project/fastbencode/)\n - [`bitstring`](https://pypi.org/project/bitstring/)\n\n2. **Streaming dependencies:** built-in support for streaming files over HTTP. To use this feature, you need to install extra streaming dependencies.\n\n<br />\n\n# Installation\n\nInstall aiotorrent from PyPI using:\n\n```\n$ pip install aiotorrent\n```\n\nIn order to use the streaming feature, you can install the dependencies using:\n\n```\n$ pip install aiotorrent[stream-support]\n```\n\n<br />\n\n# Quickstart\n\n### Initialisation\n\n```python\n# Import the Torrent class and pass a torrent file to it:\n# You can either pass the file path or a file-like object. aiotorrent will handle it internally.\nfrom aiotorrent import Torrent\ntorrent = Torrent('path/to/file.torrent')\n\n# To initialise the torrent, you need to call the init() coroutine.\nawait torrent.init()\n```\n\n\n## Getting peers via DHT\nWhile it is not a requirement, it is highly recommended to do use DHT (Distributed Hash Table) for peer discovery, which in turn can lead to better file retrieval speeds. To let aiotorrent perform peer discovery via DHT, you can pass the `dht_enabled=True` parameter to the `init()` coroutine, as follows:\n\n```python\nawait torrent.init(dht_enabled=True)\n```\n\n> [!NOTE]\n> The current implementation of DHT is hardcoded to fetch a minimum of 100 peers\n\n> [!CAUTION]\nIn some cases this can prevent the torrent from initializing when there are not enough peers available. This behavior will be fixed in a future release.\n\n## Downloading & Streaming\n\nTorrent files are stored inside `Torrent.files` as a list. We can access them by sub-scripting the `Torrent.files` attribute, like as follows:\n\n### Example to download and stream files\n\n```python\n# To download the third file\nawait torrent.download(torrent.files[2])\n```\n\nSimilarly, to serve a torrent file over HTTP, you can call the `stream()` coroutine, as follows:\n\n```python\n# To stream the second file, etc\nawait torrent.stream(torrent.files[1])\n```\n\nThis starts up a [`uvicorn`](https://github.com/encode/uvicorn) server on `localhost:8080` which uses [`starlette`](https://github.com/encode/starlette) behind the scenes as the ASGI framework to stream files over http.\n\n\n### Piece downloading strategy\nYou can also change how pieces of a particular file are being downloaded. Currently, this library offers two download strategies:\n - *Default*: This strategy is used when the `strategy` parameter is not specified to the `Torrent.download()` function. It downloads file pieces in a pseudo-sequential manner. For instance, it will start fetching pieces in order, but **it may or may not yield the pieces in order**.\n\n - *Sequential*: This strategy is straight forward, and it **always yields pieces in a sequential manner**.\n \n > [!IMPORTANT]\n > The `stream()` coroutine always uses the SEQUENTIAL download strategy, and this behaviour cannot be changed.\n\n\n```python\nfrom aiotorrent import DownloadStrategy\nfrom aiotorrent import Torrent\n\ntorrent = Torrent(\"path/to/file.torrent\")\nfile = torrent.files[1]\n\n# The download strategies available are: DownloadStrategy.DEFAULT and DownloadStrategy.SEQUENTIAL\nawait torrent.download(file, strategy=DownloadStrategy.SEQUENTIAL)\n```\n\n\n### Getting the download progress\n\nEach torrent file inside `Torrent.files` has the following functions to get useful statistics about the download progress:\n\n1. `get_bytes_downloaded()`: Returns the total number of bytes downloaded so far for a particular file. This also includes the number of bytes which may not be written to disk (ie the piece validation failed, and the piece was discarded).\n\n2. `get_bytes_written()`: Returns the number of bytes written to disk for a particular file.\n\n3. `get_download_progress(precision=2)`: Returns the download progress in percentage for a particular file. The precision parameter specifies the number of decimal places to round off the result to\n\n```python\nfile = torrent.files[0]\n\nprint(f\"Total bytes downloaded: {file.get_bytes_downloaded()} bytes\")\n# Output: Total bytes downloaded: 1048576 bytes\n\nprint(f\"Download progress: {file.get_bytes_written()} / {file.size} bytes\")\n# Output: Download progress: 1048576 / 5242880 bytes\n\nprint(f\"Download progress: {file.get_download_progress(precision=3)}%\")\n# Output: Download progress: 20.152%\n```\n\n# aiotorrent CLI\nStarting from versions 0.9.0, aiotorrent ships with a cli which can be directly invoked from the terminal, if PYTHONPATH is set correctly. The usage is fairly simple, and self explanatory:\n\n```bash\n$ aiotorrent\nusage: aiotorrent [-h] [-v] {download,stream,info} ...\n\naiotorrent CLI for downloading and streaming torrents.\n\npositional arguments:\n {download,stream,info}\n Available commands\n download Download torrent files\n stream Stream files over HTTP\n info Parse and show torrent metadata\n\noptions:\n -h, --help show this help message and exit\n -v, --verbose Show verbose output. Use -vv, -vvv, etc for increased verbosity\n```\n\n# Contribution Guidelines\nThis project is open to contributions. Feel free to open issues on bug reports or feature requests.\n\nPlease ensure that you open an issue before submitting a pull request. Also refrain from making pull requests directly to the main branch.\n\n<br>\n\n_The above methods can take additional parameters to customize the behaviour of this library. [Read the documentation]() to know more._\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "An ultra-lightweight torrent library written in pure Python.",
"version": "0.9.1",
"project_urls": {
"Homepage": "https://github.com/Mys7erio/aiotorrent",
"Repository": "https://github.com/Mys7erio/aiotorrent"
},
"split_keywords": [
"python",
" python3",
" bittorrent",
" bittorrent-client",
" downloading",
" streaming"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e3f5e44234f15c27740ba5180d9c61be14f122dd18f8d7021c36e8602c032d67",
"md5": "cc95a4be18dc08013763e029a0c8ad5e",
"sha256": "41cdf3e8c964dd96c6fba3e832d681bcd218cd41dc4db93fe7ea43a17e2dd5fc"
},
"downloads": -1,
"filename": "aiotorrent-0.9.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cc95a4be18dc08013763e029a0c8ad5e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 28117,
"upload_time": "2025-09-12T10:39:00",
"upload_time_iso_8601": "2025-09-12T10:39:00.783995Z",
"url": "https://files.pythonhosted.org/packages/e3/f5/e44234f15c27740ba5180d9c61be14f122dd18f8d7021c36e8602c032d67/aiotorrent-0.9.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a1b0bd70edb706e2f370f4fb3f9921db425dd3435be1b0038f877827f4e8ee89",
"md5": "6fc442042fe7540ea029f4cad4a6f5ea",
"sha256": "0c6462bf81927e9119f02d4811c33868907fea4f357b99e05651091d6045105a"
},
"downloads": -1,
"filename": "aiotorrent-0.9.1.tar.gz",
"has_sig": false,
"md5_digest": "6fc442042fe7540ea029f4cad4a6f5ea",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 24472,
"upload_time": "2025-09-12T10:39:02",
"upload_time_iso_8601": "2025-09-12T10:39:02.374234Z",
"url": "https://files.pythonhosted.org/packages/a1/b0/bd70edb706e2f370f4fb3f9921db425dd3435be1b0038f877827f4e8ee89/aiotorrent-0.9.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-12 10:39:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Mys7erio",
"github_project": "aiotorrent",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "aiotorrent"
}
JSON
