Metadata-Version: 2.4
Name: pooch-rattler
Version: 0.3.1
Summary: Pooch downloader powered by Rattler
Keywords: data,download,caching,http
Author: hingebase
Author-email: hingebase <zcliu@pku.edu.cn>
License-Expression: BSD-3-Clause
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AnyIO
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: anyio>=4.12.0,<5.0.0
Requires-Dist: pooch>=1.9.0,<2.0.0
Requires-Dist: py-rattler>=0.23.1,<2.0.0
Requires-Dist: typing-extensions>=4.14.0,<5.0.0
Requires-Dist: uvloop>=0.22.1,<2.0.0 ; platform_python_implementation != 'PyPy' and sys_platform != 'cygwin' and sys_platform != 'win32'
Requires-Dist: winloop>=0.3.1,<2.0.0 ; platform_python_implementation != 'PyPy' and sys_platform == 'win32'
Requires-Python: >=3.9
Project-URL: Homepage, https://github.com/hingebase/pooch-rattler
Project-URL: Source Code, https://github.com/hingebase/pooch-rattler
Project-URL: Issue Tracker, https://github.com/hingebase/pooch-rattler/issues
Description-Content-Type: text/markdown

# pooch-rattler

[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/hingebase/pooch-rattler/publish-pypi.yml?label=ci&logo=github)](https://github.com/hingebase/pooch-rattler/actions)
[![PyPI - Version](https://img.shields.io/pypi/v/pooch-rattler)](https://pypi.org/project/pooch-rattler)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pooch-rattler)
![BSD-3-Clause License](https://img.shields.io/pypi/l/pooch-rattler)  
![basedpyright](https://img.shields.io/endpoint?url=https://docs.basedpyright.com/latest/badge.json)
![pyrefly](https://img.shields.io/endpoint?url=https://pyrefly.org/badge.json)
![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)
![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)
![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)
![Pixi](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/prefix-dev/pixi/main/assets/badge/v0.json)

[Pooch downloader][1] powered by [Rattler][2].
## Features
- Native Rust performance
- Work with `anyio`, `asyncio` and `trio`
- Drop-in replacement of the global default Pooch downloader
- [Reqwest middlewares][3] which bring the missing [GCS][4], [S3][5] and
  [retry][6] support in Pooch

## Get started
``` py
import anyio.to_thread
import pooch
import pooch_rattler

# Register global default
pooch_rattler.install()

# Synchronous download
downloaded_file = pooch.retrieve("https://example.com/index.html")

# Asynchronous download
async def async_download():
    # We still need a worker thread to look for existing cache,
    # validate checksums and decompress downloaded files
    return await anyio.to_thread.run_sync(
        pooch.retrieve, "https://example.com/index.html")

cached_file = anyio.run(async_download)
assert cached_file == downloaded_file
```

Downloaders can also be created and invoked explicitly.
Examples can be found in the [unit tests][7].
## Resumable downloader
Resumable downloader provides functionality like `curl -C -` ([man page][8]).
It's not the default behavior due to the following limitations:
- The server must know how to handle HTTP range requests, otherwise the
  downloaded file can be corrupted since there is no way to read response
  headers into Python from Rattler.
- Resumable downloader also introduces slightly more Python overhead even if no
  actual resumption takes place.

Resumable downloader supports most of the features described in the previous
sections. To use it, replace your `pooch_rattler.Downloader` with
`pooch_rattler.ResumableDownloader`.

[1]: https://www.fatiando.org/pooch/latest/downloaders.html
[2]: https://github.com/conda/rattler
[3]: https://rattler.prefix.dev/py-rattler/client/
[4]: https://github.com/fatiando/pooch/issues/398
[5]: https://github.com/fatiando/pooch/issues/363
[6]: https://github.com/fatiando/pooch/issues/464
[7]: https://github.com/hingebase/pooch-rattler/tree/main/tests
[8]: https://curl.se/docs/manpage.html#--continue-at
