Metadata-Version: 2.4
Name: pptrend
Version: 0.1.2
Summary: A zero-dependency CLI tool to track and visualize PyPI package download trends.
Author-email: cphotor <cphotor@example.com>
License: MIT
Keywords: pypi,downloads,stats,cli,trends
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# pptrend

[![PyPI version](https://img.shields.io/pypi/v/pptrend.svg?v=2)](https://pypi.org/project/pptrend/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A zero-dependency command-line tool to track and visualize PyPI package download trends directly in your terminal.

## ✨ Features

- **Zero Dependencies**: Built entirely with Python standard libraries. No `pip install` required for dependencies.
- **Adaptive ASCII Charts**: Automatically adjusts the chart granularity (daily, weekly, monthly, or yearly) based on the data range.
- **Smart Caching**: Stores data locally to minimize API calls. Skips network requests if data is recent.
- **Cross-Platform**: Works on macOS, Linux, and Windows.

## 📡 Data Source & Limitations

- **Primary Source**: [PePy.tech](https://pepy.tech/) API.
- **Fallback Source**: [PyPIStats.org](https://pypistats.org/) API (used if PePy is unavailable).
- **Data Range**: APIs provide statistics for the last **180 days**. However, `pptrend` stores data locally, allowing you to build a historical record that extends far beyond 180 days by running the tool periodically.
- **Data Continuity**: If a package hasn't been updated in the database for more than 180 days, its historical data is considered "disconnected" and can no longer be extended.
- **Accuracy**: Download counts are aggregated from PyPI statistics. Note that these figures may include automated systems (like CI/CD pipelines) and might not represent unique human users.

## 🚀 Installation

### Option 1: Using uv (Recommended)
First, install [uv](https://github.com/astral-sh/uv):
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Then, choose one of the following ways to run `pptrend`:

**A. Run directly with `uvx` (No installation required):**
```bash
uvx pptrend requests
```

**B. Install permanently with `uv tool`:**
```bash
uv tool install pptrend
pptrend requests
```

### Option 2: Using pipx
`pipx` installs the tool in an isolated virtual environment, keeping your system clean.
```bash
pipx install pptrend
pptrend requests
```

### Option 3: Manual Install
Download `pptrend.py` and run it directly:
```bash
./pptrend.py <package_name>
```

## 📖 Usage

Track the download history of any PyPI package:

```bash
pptrend requests
pptrend flask
pptrend numpy
```

**Check version:**
```bash
pptrend --version
```

**Clean disconnected data:**
If a package hasn't been tracked for over 180 days, its history can no longer be extended. Use this command to automatically scan and remove such stale records for all packages:
```bash
pptrend --clean
```

## 📊 Example Output

```text
requests - Week view (180 days of data)
======================================================================
10-13 │                                             │   180.4M
10-20 │██████████████████████████████████████       │   306.2M
...
04-06 │█████████████████████████████████████████████│   326.7M
======================================================================
Total records: 180 | Periods shown: 26 weeks
Min: 178,740,886 | Max: 326,665,297 | Avg: 247,929,848
```

## ⚙️ Data Storage

`pptrend` stores its database in the standard application data directory for your OS:

- **macOS**: `~/Library/Application Support/pptrend/pptrend.db`
- **Linux**: `~/.local/share/pptrend/pptrend.db`
- **Windows**: `%APPDATA%\pptrend\pptrend.db`

## 🛠️ Development

To run the script from source using `uv`:

```bash
git clone https://github.com/cphotor/pptrend.git
cd pptrend
uv run pptrend.py requests
```

## 📄 License

MIT License
