Metadata-Version: 2.4
Name: trending-repos
Version: 0.1.1
Summary: CLI tool to fetch trending GitHub repositories
Requires-Python: >=3.10
Requires-Dist: requests>=2.33.0
Requires-Dist: typer>=0.24.1
Description-Content-Type: text/markdown

# trending-repos

A CLI tool to fetch and display trending GitHub repositories, filtered by time range and programming language.

## Installation

### From PyPI

```bash
pip install trending-repos
```

### From source

```bash
git clone https://github.com/abab754/trending-repos.git
cd trending-repos
python -m venv myenv
source myenv/bin/activate
pip install -r requirements.txt
```

## Usage

```bash
trending-repos [OPTIONS]
```

### Options

| Option | Short | Type | Default | Description |
|---|---|---|---|---|
| `--duration` | `-d` | `day \| week \| month \| year` | `week` | Time range to filter repos by |
| `--limit` | `-l` | integer (1–100) | `10` | Number of repositories to display |
| `--language` | `-lang` | string | `python` | Programming language to filter by |
| `--help` | | | | Show help message and exit |

### Examples

```bash
# Top 10 trending Python repos from the past week (defaults)
trending-repos

# Top 5 repos from the past day
trending-repos --duration day --limit 5

# Top 20 JavaScript repos from the past month
trending-repos --duration month --limit 20 --language javascript

# Top trending Go repos from the past year
trending-repos -d year -l 15 -lang go
```

### Example output

```
Trending repos · last week · language: python · top 3
============================================================

#1  some-user/awesome-repo
    ★ 4,231 stars  |  Python
    A really awesome Python project

#2  another-user/cool-tool
    ★ 2,108 stars  |  Python
    A cool tool that does cool things

#3  user/project
    ★ 987 stars  |  Python
    No description

============================================================
```

## Notes

- Uses the [GitHub Search API](https://docs.github.com/en/rest/search/search). No authentication required, but unauthenticated requests are limited to **10 requests per minute**.
- Language names must match GitHub's canonical names (e.g. `javascript` not `js`, `c++` not `cpp`).
