jps-ado-pr-utils 0.3.0

Python utils for retrieving pull-request metadata.

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 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) and PR status (active, completed, abandoned, or all)
• 📊 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)
• 🔍 Status Filtering: View active, completed (merged), abandoned, or all pull requests
• ⚙️ Flexible Configuration: Use command-line arguments or YAML config files
• 🔐 Secure Authentication: Personal Access Token (PAT) based authentication

Example Usage

Installation from PyPI

pip install jps-ado-pr-utils

Configuration

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

AZDO_PAT=your_personal_access_token_here
AZDO_USER=[e-mail]

Basic Usage

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

# 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"

Status Filtering

# List all completed/merged PRs
jps-ado-pr-utils --config-file projects.yaml --status completed

# List all abandoned PRs
jps-ado-pr-utils --config-file projects.yaml --status abandoned

# List all PRs regardless of status (active, completed, abandoned)
jps-ado-pr-utils --config-file projects.yaml --status all

# Default behavior (active PRs only)
jps-ado-pr-utils --config-file projects.yaml --status active
# Or simply:
jps-ado-pr-utils --config-file projects.yaml

Filtering Options

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

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

# Combine status and reviewer filters
jps-ado-pr-utils --config-file projects.yaml --status completed --mine-only

Configuration File Format

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

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

pip install jps-ado-pr-utils

From Source

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
  --status TEXT         Filter by PR status: active, completed, abandoned, or all
                        (default: active)
  --required-only      Show only PRs where you're a required reviewer
  --mine-only          Show only PRs where you're assigned as a reviewer
  --help               Show this message and exit

Status Parameter Values

• active (default): Open/active pull requests
• completed: Merged/completed pull requests
• abandoned: Abandoned pull requests
• all: All pull requests regardless of status

🔧 Requirements

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

🧪 Testing

Running Tests

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run with coverage report
pytest --cov=src --cov-report=html --cov-report=term

# Run specific test file
pytest tests/test_list_open_prs.py

# Run specific test class
pytest tests/test_list_open_prs.py::TestGetPrsForProject

Test Structure

• tests/test_constants.py - Tests for module constants
• tests/test_list_open_prs.py - Unit tests for the main module functions
• tests/test_integration.py - Integration tests for the CLI application
• tests/conftest.py - Pytest configuration and shared fixtures

Test Coverage

The test suite includes 50+ test cases covering:

Unit Tests

• Authentication header generation
• Environment variable loading
• PR retrieval with different status filters (active, completed, abandoned, all)
• Project loading from CLI and config files
• Reviewer role identification (required/optional)
• Reviewer vote tracking
• PR record construction
• Vote text rendering
• CLI argument parsing
• Filter operations (mine-only, required-only)

Integration Tests

• Full workflow for active PRs
• Full workflow for completed PRs
• Full workflow for abandoned PRs
• Full workflow for all PRs
• Mine-only and required-only filter integration
• Multiple project handling
• Error handling (authentication failures, missing credentials)
• Output formatting verification
• Empty results handling

🧑‍💻 Development

Setup Development Environment

# Install with development dependencies
make install

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

# Run tests
make test

Development Commands

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
• Issue Tracker
• PyPI Package