Metadata-Version: 2.4
Name: pytail
Version: 0.1.5
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Archiving :: Mirroring
Summary: Incremental PyPI Simple API caching mirror
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# PyTail

[![CI](https://img.shields.io/github/actions/workflow/status/AndPuQing/PyTail/ci.yml?branch=main&label=CI)](https://github.com/AndPuQing/PyTail/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/actions/workflow/status/AndPuQing/PyTail/release.yml?label=Release)](https://github.com/AndPuQing/PyTail/actions/workflows/release.yml)
[![PyPI](https://img.shields.io/pypi/v/pytail.svg)](https://pypi.org/project/pytail/)
[![Python](https://img.shields.io/pypi/pyversions/pytail.svg)](https://pypi.org/project/pytail/)

`pytail` is a small PyPI caching proxy. It exposes a Python Simple Repository
API endpoint, fetches packages from upstream on demand, and keeps downloaded
files in a local cache.

It is useful when you want faster repeated installs, a simple shared package
cache, or a local endpoint for PyPI and PyTorch wheel indexes.

## Features

- PyPI-compatible `/simple/` endpoint for `pip` and `uv`
- lazy caching of project pages and package files
- optional cache size limit with least-recently-used cleanup
- PyTorch wheel index proxy under `/pytorch-wheels/`
- HTML and JSON Simple API responses

## Run

```sh
cargo run -- \
  --bind 127.0.0.1:3141 \
  --cache-dir .cache/pytail
```

Then use it as the package index:

```sh
uv pip install --index-url http://127.0.0.1:3141/simple/ requests
pip install --index-url http://127.0.0.1:3141/simple/ requests
```

Open the local index in a browser:

```text
http://127.0.0.1:3141/simple/
```

## PyTorch Wheels

PyTorch wheel indexes are available under `/pytorch-wheels/`.

For example, this upstream command:

```sh
pip install torch --index-url https://download.pytorch.org/whl/cu126
```

can use the local cache instead:

```sh
pip install torch --index-url http://127.0.0.1:3141/pytorch-wheels/cu126
```

If a package needs both PyTorch wheels and normal PyPI packages:

```sh
pip install torch \
  --index-url http://127.0.0.1:3141/pytorch-wheels/cu126 \
  --extra-index-url http://127.0.0.1:3141/simple/
```

## Options

Common options:

- `--bind`: listen address, default `127.0.0.1:3141`
- `--cache-dir`: cache directory, default `.cache/pytail`
- `--cache-max-size`: max file cache size, default `0` for unlimited; examples:
  `512MiB`, `2G`, `10GB`
- `--upstream-base-url`: PyPI-compatible upstream, default `https://pypi.org`
- `--torch-url`: PyTorch wheel upstream, default
  `https://download.pytorch.org/whl/`
- `--project-cache-ttl-secs`: project page refresh interval, default `900`
- `--request-timeout-secs`: upstream request timeout, default `15`
- `--verbose`: enable debug logs

## Build

Build the Rust binary:

```sh
cargo build --release
```

Build a Python wheel with `maturin`:

```sh
maturin build --release
```

The wheel installs the `pytail` command.

