# TurboDL
## 🚀 Overview
TurboDL is an extremely smart, fast, and efficient download manager designed to optimize your downloading experience.
## ✨ Key Features
- **Smart Connection Management**: Dynamically calculates the optimal number of connections based on file size and network speed
- **Intelligent Acceleration**: Built-in sophisticated download acceleration techniques that split downloads into multiple parallel streams
- **Automatic Retry System**: Efficiently retries failed requests with exponential backoff strategy
- **Pre-Download Intelligence**: Automatically detects file information, size, and type before download begins
- **Seamless Redirection**: Handles HTTP redirects automatically for successful downloads
- **Memory Optimization**: Intelligently uses RAM buffering to reduce disk I/O overhead
- **Data Integrity**: Supports post-download hash verification (MD5, SHA256, etc.)
- **Real-time Feedback**: Provides an elegant, accurate progress bar with detailed statistics
- **Cross-platform Compatibility**: Works consistently across all major operating systems
### Additional Built-in Features
- **YouTube Support**: Download YouTube videos in the highest available quality and automatically merge audio and video streams using [StreamSnapper](https://github.com/henrique-coder/streamsnapper) library
## 📦 Installation
```bash
# Install the stable version of TurboDL from PyPI
pip install --upgrade turbodl
# Install the beta version of TurboDL from GitHub
pip install --upgrade git+https://github.com/henrique-coder/turbodl.git@main
# Install the development version of TurboDL from GitHub
pip install --upgrade git+https://github.com/henrique-coder/turbodl.git@dev
```
> [!Warning]
> If you already have a version installed and want to switch to a different branch (for example, to test new features or fix bugs), you must use the `--force-reinstall` parameter to ensure the upgrade occurs correctly.
## 🔍 Examples
### Basic Usage
```python
from turbodl import TurboDL
turbodl = TurboDL()
turbodl.download(
url="https://example.com/file.txt", # Your download URL
output_path="path/to/file" # The file/path to save the downloaded file
)
# Access the absolute path to the downloaded file
print(turbodl.output_path)
```
### Advanced Usage
```python
from turbodl import TurboDL
turbodl = TurboDL(
max_connections="auto",
connection_speed_mbps=100,
show_progress_bar=True,
)
turbodl.download(
url="https://example.com/file.txt",
output_path="path/to/file",
pre_allocate_space=False,
use_ram_buffer="auto",
overwrite=True,
headers=None,
inactivity_timeout=120,
timeout=None,
expected_hash=None,
hash_type="md5",
)
# Access the absolute path to the downloaded file
print(turbodl.output_path)
```
## Command Line Interface
```bash
# Show help for all commands
turbodl --help
# Show help for the download command
turbodl download --help
# Download a file
turbodl download [...] https://example.com/file.txt path/to/file
```
## 📊 CLI Demo
[](https://asciinema.org/a/NxnwCG6DOlJKhGxXRuYXbpTPx)
## 📋 Parameters
### `TurboDL` Class Parameters
| Parameter | Type | Default | Description |
| ----------------------- | -------------------- | ------- | ----------------------------------------------------------------------------- |
| `max_connections` | int, Literal["auto"] | "auto" | Maximum connections for parallel downloading. Minimum is 1 and maximum is 32. |
| `connection_speed_mbps` | float | 100 | Your current internet connection speed in Mbps. |
| `show_progress_bar` | bool | True | Whether to display a progress bar. |
### `Download` Method Parameters
| Parameter | Type | Default | Description |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url` | str | - | The URL of the file to download. |
| `output_path` | str, PathLike, None | None | The path to save the downloaded file. If it is a directory, filename is derived from server response. If None, the current working directory is used. |
| `pre_allocate_space` | bool | False | Whether to pre-allocate disk space for the file. |
| `use_ram_buffer` | bool, Literal["auto"] | "auto" | Use RAM buffer for download. If set to False, the file will be downloaded continuously to disk. If set to True, the file will be downloaded with the help of RAM memory. If set to "auto", the RAM buffer will be disabled if the output path is a RAM directory and enabled otherwise. |
| `overwrite` | bool | True | Whether to overwrite the file if it already exists. |
| `headers` | dict[str, str], None | None | A dictionary of headers to include in the request. |
| `inactivity_timeout` | int | 120 | Timeout in seconds after the connection is considered idle. None means no timeout. |
| `timeout` | int | None | Overall timeout in seconds. None means no timeout. |
| `expected_hash` | str, None | None | The expected hash value of the downloaded file. If provided, the file will be verified after download. |
| `hash_type` | Literal["md5", "sha1", "sha224", "sha256", "sha384", "sha512", "blake2b", "blake2s", "sha3_224", "sha3_256", "sha3_384", "sha3_512", "shake_128", "shake_256"] | "md5" | Hash algorithm to use for verification. Available: md5, sha1, sha224, sha256, sha384, sha512, blake2b, blake2s, sha3_224, sha3_256, sha3_384, sha3_512, shake_128, shake_256. |
## 🛠️ Development
```bash
# [!] Make sure you have git, make and uv installed
# Clone the repository
git clone https://github.com/henrique-coder/turbodl.git
# Enter the project directory
cd turbodl
# Install project dependencies (using uv)
make install
# Lint and format code
make lint
make format
# Run tests
make tests
```
## 🤝 Contributing
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## 👥 Contributors
<a href="https://github.com/henrique-coder/turbodl/graphs/contributors">
<img src="https://contrib.rocks/image?repo=henrique-coder/turbodl" />
</a>
## 📄 License
Distributed under the MIT License. See `LICENSE` for more information.
## 📊 Project Status
TurboDL is in active development. Check the [releases page](https://github.com/henrique-coder/turbodl/releases) for the latest updates.
## 🌟 Star the Project
If you find this project useful, please consider giving it a star on [GitHub](https://github.com/henrique-coder/turbodl).
Raw data
{
"_id": null,
"home_page": null,
"name": "turbodl",
"maintainer": "henrique-coder",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "henrique-coder <henriquemoreira10fk@gmail.com>",
"keywords": "dl, downloader, manager, python, smart, turbodl, download, fast, efficient, cli, tool, utility",
"author": "henrique-coder",
"author_email": "henrique-coder <henriquemoreira10fk@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/10/5d/3b4234658109d14eed7a387f9dd1b648a2d666053475ad85ee70275d4316/turbodl-0.7.0.tar.gz",
"platform": null,
"description": "# TurboDL\n\n\n\n\n\n\n## \ud83d\ude80 Overview\n\nTurboDL is an extremely smart, fast, and efficient download manager designed to optimize your downloading experience.\n\n## \u2728 Key Features\n\n- **Smart Connection Management**: Dynamically calculates the optimal number of connections based on file size and network speed\n- **Intelligent Acceleration**: Built-in sophisticated download acceleration techniques that split downloads into multiple parallel streams\n- **Automatic Retry System**: Efficiently retries failed requests with exponential backoff strategy\n- **Pre-Download Intelligence**: Automatically detects file information, size, and type before download begins\n- **Seamless Redirection**: Handles HTTP redirects automatically for successful downloads\n- **Memory Optimization**: Intelligently uses RAM buffering to reduce disk I/O overhead\n- **Data Integrity**: Supports post-download hash verification (MD5, SHA256, etc.)\n- **Real-time Feedback**: Provides an elegant, accurate progress bar with detailed statistics\n- **Cross-platform Compatibility**: Works consistently across all major operating systems\n\n### Additional Built-in Features\n\n- **YouTube Support**: Download YouTube videos in the highest available quality and automatically merge audio and video streams using [StreamSnapper](https://github.com/henrique-coder/streamsnapper) library\n\n## \ud83d\udce6 Installation\n\n```bash\n# Install the stable version of TurboDL from PyPI\npip install --upgrade turbodl\n\n# Install the beta version of TurboDL from GitHub\npip install --upgrade git+https://github.com/henrique-coder/turbodl.git@main\n\n# Install the development version of TurboDL from GitHub\npip install --upgrade git+https://github.com/henrique-coder/turbodl.git@dev\n```\n\n> [!Warning]\n> If you already have a version installed and want to switch to a different branch (for example, to test new features or fix bugs), you must use the `--force-reinstall` parameter to ensure the upgrade occurs correctly.\n\n## \ud83d\udd0d Examples\n\n### Basic Usage\n\n```python\nfrom turbodl import TurboDL\n\nturbodl = TurboDL()\nturbodl.download(\n url=\"https://example.com/file.txt\", # Your download URL\n output_path=\"path/to/file\" # The file/path to save the downloaded file\n)\n\n# Access the absolute path to the downloaded file\nprint(turbodl.output_path)\n```\n\n### Advanced Usage\n\n```python\nfrom turbodl import TurboDL\n\nturbodl = TurboDL(\n max_connections=\"auto\",\n connection_speed_mbps=100,\n show_progress_bar=True,\n)\nturbodl.download(\n url=\"https://example.com/file.txt\",\n output_path=\"path/to/file\",\n pre_allocate_space=False,\n use_ram_buffer=\"auto\",\n overwrite=True,\n headers=None,\n inactivity_timeout=120,\n timeout=None,\n expected_hash=None,\n hash_type=\"md5\",\n)\n\n# Access the absolute path to the downloaded file\nprint(turbodl.output_path)\n```\n\n## Command Line Interface\n\n```bash\n# Show help for all commands\nturbodl --help\n\n# Show help for the download command\nturbodl download --help\n\n# Download a file\nturbodl download [...] https://example.com/file.txt path/to/file\n```\n\n## \ud83d\udcca CLI Demo\n\n[](https://asciinema.org/a/NxnwCG6DOlJKhGxXRuYXbpTPx)\n\n## \ud83d\udccb Parameters\n\n### `TurboDL` Class Parameters\n\n| Parameter | Type | Default | Description |\n| ----------------------- | -------------------- | ------- | ----------------------------------------------------------------------------- |\n| `max_connections` | int, Literal[\"auto\"] | \"auto\" | Maximum connections for parallel downloading. Minimum is 1 and maximum is 32. |\n| `connection_speed_mbps` | float | 100 | Your current internet connection speed in Mbps. |\n| `show_progress_bar` | bool | True | Whether to display a progress bar. |\n\n### `Download` Method Parameters\n\n| Parameter | Type | Default | Description |\n| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `url` | str | - | The URL of the file to download. |\n| `output_path` | str, PathLike, None | None | The path to save the downloaded file. If it is a directory, filename is derived from server response. If None, the current working directory is used. |\n| `pre_allocate_space` | bool | False | Whether to pre-allocate disk space for the file. |\n| `use_ram_buffer` | bool, Literal[\"auto\"] | \"auto\" | Use RAM buffer for download. If set to False, the file will be downloaded continuously to disk. If set to True, the file will be downloaded with the help of RAM memory. If set to \"auto\", the RAM buffer will be disabled if the output path is a RAM directory and enabled otherwise. |\n| `overwrite` | bool | True | Whether to overwrite the file if it already exists. |\n| `headers` | dict[str, str], None | None | A dictionary of headers to include in the request. |\n| `inactivity_timeout` | int | 120 | Timeout in seconds after the connection is considered idle. None means no timeout. |\n| `timeout` | int | None | Overall timeout in seconds. None means no timeout. |\n| `expected_hash` | str, None | None | The expected hash value of the downloaded file. If provided, the file will be verified after download. |\n| `hash_type` | Literal[\"md5\", \"sha1\", \"sha224\", \"sha256\", \"sha384\", \"sha512\", \"blake2b\", \"blake2s\", \"sha3_224\", \"sha3_256\", \"sha3_384\", \"sha3_512\", \"shake_128\", \"shake_256\"] | \"md5\" | Hash algorithm to use for verification. Available: md5, sha1, sha224, sha256, sha384, sha512, blake2b, blake2s, sha3_224, sha3_256, sha3_384, sha3_512, shake_128, shake_256. |\n\n## \ud83d\udee0\ufe0f Development\n\n```bash\n# [!] Make sure you have git, make and uv installed\n\n# Clone the repository\ngit clone https://github.com/henrique-coder/turbodl.git\n\n# Enter the project directory\ncd turbodl\n\n# Install project dependencies (using uv)\nmake install\n\n# Lint and format code\nmake lint\nmake format\n\n# Run tests\nmake tests\n```\n\n## \ud83e\udd1d Contributing\n\nContributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.\n\n1. Fork the Project\n2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the Branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## \ud83d\udc65 Contributors\n\n<a href=\"https://github.com/henrique-coder/turbodl/graphs/contributors\">\n <img src=\"https://contrib.rocks/image?repo=henrique-coder/turbodl\" />\n</a>\n\n## \ud83d\udcc4 License\n\nDistributed under the MIT License. See `LICENSE` for more information.\n\n## \ud83d\udcca Project Status\n\nTurboDL is in active development. Check the [releases page](https://github.com/henrique-coder/turbodl/releases) for the latest updates.\n\n## \ud83c\udf1f Star the Project\n\nIf you find this project useful, please consider giving it a star on [GitHub](https://github.com/henrique-coder/turbodl).\n",
"bugtrack_url": null,
"license": null,
"summary": "TurboDL is an extremely smart, fast, and efficient download manager designed to optimize your downloading experience.",
"version": "0.7.0",
"project_urls": {
"Bug Reports": "https://github.com/henrique-coder/turbodl/issues",
"Bug Tracker": "https://github.com/henrique-coder/turbodl/issues",
"Changelog": "https://github.com/henrique-coder/turbodl/releases",
"Documentation": "https://github.com/henrique-coder/turbodl/blob/main/README.md",
"Download": "https://pypi.org/project/turbodl",
"Homepage": "https://github.com/henrique-coder/turbodl",
"Issues": "https://github.com/henrique-coder/turbodl/issues",
"Releases": "https://github.com/henrique-coder/turbodl/releases/latest",
"Repository": "https://github.com/henrique-coder/turbodl",
"Source Code": "https://github.com/henrique-coder/turbodl"
},
"split_keywords": [
"dl",
" downloader",
" manager",
" python",
" smart",
" turbodl",
" download",
" fast",
" efficient",
" cli",
" tool",
" utility"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "aeb8b8c221b55fc32aed4e6400eed0ebf0c1f0dfcd91fffbd4963e0293f3b96a",
"md5": "9e19c82ffd8650da5ca5f1589e31e48c",
"sha256": "65a8f810af328ec7bb3374126d58b5e0db8e47128071504acde5b3f157aef842"
},
"downloads": -1,
"filename": "turbodl-0.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9e19c82ffd8650da5ca5f1589e31e48c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 25691,
"upload_time": "2025-08-19T18:39:52",
"upload_time_iso_8601": "2025-08-19T18:39:52.137346Z",
"url": "https://files.pythonhosted.org/packages/ae/b8/b8c221b55fc32aed4e6400eed0ebf0c1f0dfcd91fffbd4963e0293f3b96a/turbodl-0.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "105d3b4234658109d14eed7a387f9dd1b648a2d666053475ad85ee70275d4316",
"md5": "471b63286fdef02bd93d7a17009592e5",
"sha256": "005810f57330597aaec5fc305d9ed56553e2359b4f01735818e1d191397d4bef"
},
"downloads": -1,
"filename": "turbodl-0.7.0.tar.gz",
"has_sig": false,
"md5_digest": "471b63286fdef02bd93d7a17009592e5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 21205,
"upload_time": "2025-08-19T18:39:53",
"upload_time_iso_8601": "2025-08-19T18:39:53.638442Z",
"url": "https://files.pythonhosted.org/packages/10/5d/3b4234658109d14eed7a387f9dd1b648a2d666053475ad85ee70275d4316/turbodl-0.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-19 18:39:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "henrique-coder",
"github_project": "turbodl",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "turbodl"
}
JSON
