<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
_Tested on `Python 3.11` but it should work on `Python ^3.9` versions just fine._
1. **Dependencies:** The only 2 dependencies which are needed for aiotorrent to work are [`fast-bencode`](https://pypi.org/project/fast-bencode/) and [`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 python-aiotorrent
```
In order to use the streaming feature, you can install the dependencies using:
```
$ pip install python-aiotorrent[stream-support]
```
<br />
# Quickstart
### Initialisation
```python
# Import the Torrent class and pass a torrent file to it:
from aiotorrent import Torrent
torrent = Torrent('path/to/file.torrent')
# To initialise the torrent, you need to call the init() coroutine.
await torrent.init()
```
## 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)
```
<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": "python-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/c8/28/8acade5e855833ad3490d42984d212e4fef6fb2e487d117a75bdbb32422f/python_aiotorrent-0.8.3.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\n_Tested on `Python 3.11` but it should work on `Python ^3.9` versions just fine._\n\n1. **Dependencies:** The only 2 dependencies which are needed for aiotorrent to work are [`fast-bencode`](https://pypi.org/project/fast-bencode/) and [`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 python-aiotorrent\n```\n\nIn order to use the streaming feature, you can install the dependencies using:\n\n```\n$ pip install python-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:\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## 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<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.8.3",
"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": "",
"digests": {
"blake2b_256": "a8c673d6510e6e883dcfdfffb2d58a93a3b6e37209462a3c020c094d93f004fc",
"md5": "d34fb3d86cacefc84b6800fed7e22b78",
"sha256": "0567770371ed638cfebf4a176485da091b4fd016af285ef35285bcd218a7b6c8"
},
"downloads": -1,
"filename": "python_aiotorrent-0.8.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d34fb3d86cacefc84b6800fed7e22b78",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 21750,
"upload_time": "2024-12-30T14:25:10",
"upload_time_iso_8601": "2024-12-30T14:25:10.714342Z",
"url": "https://files.pythonhosted.org/packages/a8/c6/73d6510e6e883dcfdfffb2d58a93a3b6e37209462a3c020c094d93f004fc/python_aiotorrent-0.8.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c8288acade5e855833ad3490d42984d212e4fef6fb2e487d117a75bdbb32422f",
"md5": "d95f46b6a84d0796d5a3f9ffc9efdf26",
"sha256": "e3137b8b966cfd48aece93c5fce9c5104d39d7adfbd05f93cadc0e1e5fd739c7"
},
"downloads": -1,
"filename": "python_aiotorrent-0.8.3.tar.gz",
"has_sig": false,
"md5_digest": "d95f46b6a84d0796d5a3f9ffc9efdf26",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 18403,
"upload_time": "2024-12-30T14:25:12",
"upload_time_iso_8601": "2024-12-30T14:25:12.098123Z",
"url": "https://files.pythonhosted.org/packages/c8/28/8acade5e855833ad3490d42984d212e4fef6fb2e487d117a75bdbb32422f/python_aiotorrent-0.8.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-30 14:25:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Mys7erio",
"github_project": "aiotorrent",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "python-aiotorrent"
}
JSON
