Metadata-Version: 2.4
Name: jps-ado-pr-utils
Version: 0.1.0
Summary: Python utils for retrieving pull-request metadata.
Author-email: Jaideep Sundaram <jai.python3@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/jai-python3/jps-ado-pr-utils
Project-URL: Repository, https://github.com/jai-python3/jps-ado-pr-utils
Project-URL: Issues, https://github.com/jai-python3/jps-ado-pr-utils/issues
Keywords: Azure DevOps,Azure,pull-request,automation
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12.3
Requires-Dist: requests>=2.31.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: rich>=13.7.0
Provides-Extra: dev
Requires-Dist: flake8>=7.0.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: build>=1.2.1; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: isort>=5.13.0; extra == "dev"
Requires-Dist: codecov>=2.1.13; extra == "dev"
Requires-Dist: autoflake>=2.3.1; extra == "dev"
Requires-Dist: pre-commit>=3.8.0; extra == "dev"
Requires-Dist: bandit>=1.7.9; extra == "dev"
Requires-Dist: vulture>=2.11; extra == "dev"
Requires-Dist: flynt>=1.0.1; extra == "dev"
Requires-Dist: pydocstyle>=6.3.0; extra == "dev"
Requires-Dist: darglint>=1.8.1; extra == "dev"
Requires-Dist: mypy>=1.12.1; extra == "dev"
Requires-Dist: bump-my-version>=1.0.1; extra == "dev"
Requires-Dist: git-changelog>=2.7.0; extra == "dev"
Dynamic: license-file

# jps-ado-pr-utils

![Build](https://github.com/jai-python3/jps-ado-pr-utils/actions/workflows/test.yml/badge.svg)
![Publish to PyPI](https://github.com/jai-python3/jps-ado-pr-utils/actions/workflows/publish-to-pypi.yml/badge.svg)
[![codecov](https://codecov.io/gh/jai-python3/jps-ado-pr-utils/branch/main/graph/badge.svg)](https://codecov.io/gh/jai-python3/jps-ado-pr-utils)

Python utilities for retrieving and managing Azure DevOps pull request metadata with rich CLI output.

## 🚀 Overview

`jps-ado-pr-utils` is a command-line tool that helps you track and manage open pull requests across multiple Azure DevOps projects. It provides a clean, color-coded interface to view PRs where you're assigned as a reviewer, helping you prioritize your code review workload.

### Features

- 📋 **Multi-Project Support**: Query PRs across multiple Azure DevOps projects simultaneously
- 🎯 **Smart Filtering**: Filter PRs by your reviewer status (required vs. optional)
- 📊 **Rich CLI Output**: Beautiful, color-coded tables with clear PR metadata
- 🗓️ **Age Sorting**: PRs sorted by creation date (oldest first) to identify review debt
- ✅ **Vote Tracking**: See approval status at a glance (APPROVED, REJECTED, WAITING)
- ⚙️ **Flexible Configuration**: Use command-line arguments or YAML config files
- 🔐 **Secure Authentication**: Personal Access Token (PAT) based authentication

### Example Usage

#### Installation from PyPI

```bash
pip install jps-ado-pr-utils
```

#### Configuration

Create a configuration file at `~/.config/jps-ado-pr-utils/.env`:

```bash
AZDO_PAT=your_personal_access_token_here
AZDO_USER=your.email@example.com
```

#### Basic Usage

List all open PRs where you're a reviewer across specified projects:

```bash
# Using a config file
jps-ado-pr-utils --config-file projects.yaml

# Using command-line project specification
jps-ado-pr-utils --project "Project1,Project2,Project3"
```

#### Filtering Options

```bash
# Show only PRs where you're a REQUIRED reviewer
jps-ado-pr-utils --config-file projects.yaml --required

# Show only PRs where you're assigned as a reviewer (required or optional)
jps-ado-pr-utils --config-file projects.yaml --mine
```

#### Configuration File Format

Create a YAML file (e.g., `projects.yaml`) with your projects:

```yaml
projects:
  - "Platform Team"
  - "Mobile Apps"
  - "Backend Services"
  - "Infrastructure"
```

#### Sample Output

The tool displays PRs organized by project with the following information:

- PR number
- Creation date (to identify old PRs)
- Author name
- Repository name
- Your reviewer role (REQUIRED/OPTIONAL)
- Current vote status (APPROVED/REJECTED/WAITING)
- PR title
- Direct link to PR

## 📦 Installation

### From PyPI

```bash
pip install jps-ado-pr-utils
```

### From Source

```bash
git clone https://github.com/jai-python3/jps-ado-pr-utils
cd jps-ado-pr-utils
make install
```

## 🛠️ CLI Reference

```
Usage: jps-ado-pr-utils [OPTIONS]

Options:
  --config-file PATH    Path to YAML config file with projects list
  --project TEXT        Comma-separated list of project names
  --required           Show only PRs where you're a required reviewer
  --mine               Show only PRs where you're assigned as a reviewer
  --help               Show this message and exit
```

## 🔧 Requirements

- Python >= 3.10
- Azure DevOps Personal Access Token with Code (Read) permissions
- Internet connection to access Azure DevOps REST API

## 🧪 Development

### Setup Development Environment

```bash
# Install with development dependencies
make install

# Run code quality checks
make fix && make format && make lint

# Run tests
make test
```

### Development Commands

```bash
make format    # Format code with black and isort
make lint      # Run flake8, mypy, and other linters
make test      # Run pytest with coverage
make build     # Build distribution packages
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📝 Configuration Details

### Environment Variables

The tool reads configuration from `~/.config/jps-ado-pr-utils/.env`:

- `AZDO_PAT`: Your Azure DevOps Personal Access Token
- `AZDO_USER`: Your Azure DevOps username/email

### Generating a Personal Access Token

1. Go to Azure DevOps → User Settings → Personal Access Tokens
2. Create a new token with **Code (Read)** permissions
3. Copy the token and add it to your `.env` file

## 📜 License

MIT License © Jaideep Sundaram

## 🔗 Links

- [GitHub Repository](https://github.com/jai-python3/jps-ado-pr-utils)
- [Issue Tracker](https://github.com/jai-python3/jps-ado-pr-utils/issues)
- [PyPI Package](https://pypi.org/project/jps-ado-pr-utils/)
