Metadata-Version: 2.4
Name: magnet-scout
Version: 0.1.0
Summary: Discover and assess public BitTorrent metadata without downloading payloads
Project-URL: Homepage, https://github.com/monhoney/magnet-scout
Project-URL: Repository, https://github.com/monhoney/magnet-scout
Project-URL: Issues, https://github.com/monhoney/magnet-scout/issues
Author: MagnetScout contributors
License: MIT
License-File: LICENSE
Keywords: bittorrent,infohash,magnet,metadata,torrent,tracker
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet
Requires-Python: >=3.11
Requires-Dist: bencode-py<5,>=4.1
Requires-Dist: click<8.3,>=8.2
Requires-Dist: defusedxml<1,>=0.7.1
Requires-Dist: httpx<1,>=0.27
Requires-Dist: torf<5,>=4.3.1
Requires-Dist: typer<0.21,>=0.20
Provides-Extra: dev
Requires-Dist: bandit<2,>=1.9; extra == 'dev'
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.15; extra == 'dev'
Requires-Dist: pip-audit<3,>=2.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.11; extra == 'dev'
Requires-Dist: twine<7,>=6.1; extra == 'dev'
Requires-Dist: types-defusedxml>=0.7.0.20240218; extra == 'dev'
Provides-Extra: dht
Requires-Dist: pythontorrentdht<2,>=1.0.3; extra == 'dht'
Description-Content-Type: text/markdown

# MagnetScout

MagnetScout is a lightweight Python CLI and library for discovering BitTorrent metadata from
pluggable providers, normalizing magnet links, checking current swarm signals, and ranking useful
results. It never downloads torrent payloads or sends results to a BitTorrent client.

MagnetScout is intended for public, freely licensed, and otherwise lawfully distributed content.
Metadata is informative rather than a legal determination; users remain responsible for deciding
whether they may access a result.

## Status

The project is alpha software. Provider availability and swarm observations can change at any
time, and a healthy score does not guarantee a successful download.

## Install

MagnetScout requires Python 3.11 or newer.

```console
python -m pip install magnet-scout
```

Until the first PyPI release, install from a checkout:

```console
python -m pip install -e .
```

Optional DHT peer discovery is installed separately:

```console
python -m pip install 'magnet-scout[dht]'
```

## CLI

```console
magnet-scout search ubuntu
magnet-scout search ubuntu --top 10
magnet-scout search ubuntu --verify --top 10
magnet-scout search ubuntu --verify --min-verified-seeders 3
magnet-scout search ubuntu --json
magnet-scout search dataset --provider academic-torrents
```

The default providers are Internet Archive, Academic Torrents, and Fedora. Provider failures are
reported independently, so one unavailable source does not discard results from the others.

`--verify` performs bounded tracker and web-seed observations without requesting payload pieces.
`--dht` adds optional, process-isolated peer discovery. A provider's reported seeder count remains
separate from independently observed values.

## Python API

```python
from magnet_scout import parse_magnet

magnet = parse_magnet("magnet:?xt=urn:btih:0123456789abcdef0123456789abcdef01234567&dn=Example")
print(magnet.info_hash)
print(magnet.canonical_uri)
```

Provider integration uses the asynchronous `SearchProvider` protocol. See
[docs/providers.md](docs/providers.md) for a complete example.

## Evidence, not guarantees

- `reported_seeders` is untrusted metadata supplied by a provider.
- `verified_seeders` is a recent tracker observation when the tracker supports scraping.
- `dht_peers` counts peer endpoints discovered during a bounded lookup; addresses are discarded.
- `UNKNOWN` means there was not enough independent evidence. It does not mean dead.
- No check proves that a complete payload will remain available.

The exact score and ranking rules are documented in
[docs/health-scoring.md](docs/health-scoring.md).

## Documentation

- [Architecture](docs/architecture.md)
- [Providers](docs/providers.md)
- [Health scoring](docs/health-scoring.md)
- [Development](docs/development.md)
- [Release process](docs/releasing.md)

## License

MagnetScout is released under the MIT License.
