jps-ado-pr-utils 1.4.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.

Azure DevOps Terminology:

• Organization: Your Azure DevOps organization (e.g., mycompany)
• Project: Top-level container within the organization (e.g., Engineering Team)
• Repository: Git repository within a project (e.g., backend-api)

This tool queries Azure DevOps projects to retrieve PRs, and can optionally filter by specific repositories.

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 with Azure DevOps project name
jps-ado-pr-utils --project "Engineering Team"

# Filter by specific repositories within a project
jps-ado-pr-utils --project "Engineering Team" --repos "backend-api,frontend-app"

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

# Filter by specific repositories
jps-ado-pr-utils --project "Engineering Team" --repos "backend-api,frontend-app,mobile-app"

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

# Filter by repositories and reviewer status
jps-ado-pr-utils --project "Engineering Team" --repos "backend-api" --mine-only

Configuration File Format

Create a YAML file (e.g., projects.yaml) with your Azure DevOps project and optional repository filters:

# Specify the Azure DevOps project (required, single value)
project: "Engineering Team"

# Optional: Filter by specific repositories within the project
repositories:
  - "backend-api"
  - "frontend-app"
  - "mobile-app"

Example configs:

# Config 1: All repositories in the project
project: "Engineering Team"

# Config 2: Only specific repositories
project: "Engineering Team"
repositories:
  - "backend-api"
  - "frontend-app"

Note:

• The --repos CLI parameter takes precedence over the repositories list in the config file
• You can combine config and CLI: config file specifies the project, --repos filters repositories

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        Azure DevOps project name (e.g., 'Engineering Team')
  --repos TEXT          Comma-separated list of repository names to filter
  --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
  --outdir PATH        Output directory for logs
                        (default: /tmp/[user]/jps-ado-pr-utils/[timestamp])
  --logfile PATH       Log file path (default: [outdir]/list_prs.log)
  --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

� Logging and Troubleshooting

The tool includes comprehensive logging to help diagnose issues. By default, logs are written to /tmp/[user]/jps-ado-pr-utils/[timestamp]/list_prs.log.

Viewing Logs

# Run with default logging
jps-ado-pr-utils --project "MyProject"

# The log file location will be displayed in the output
# View the log file
tail -f /tmp/$USER/jps-ado-pr-utils/*/list_prs.log

Custom Log Location

# Specify custom output directory
jps-ado-pr-utils --project "MyProject" --outdir /path/to/logs

# Specify custom log file
jps-ado-pr-utils --project "MyProject" --logfile /path/to/my.log

Common Issues

404 Error - Project not found:

• You must specify the Azure DevOps project name, not the repository name
• Project names are case-sensitive
• Example: Use --project "Engineering Team" not --project "backend-api"
• To filter by repository, use: --project "Engineering Team" --repos "backend-api"

No PRs showing up:

• Check the log file for API errors
• Verify your project name is correct (case-sensitive)
• Ensure your PAT has Code (Read) permissions
• Try different status filters (--status completed, --status all)
• If filtering by --repos, verify the repository names are correct

Authentication errors:

• Verify AZDO_PAT is set correctly in ~/.config/jps-ado-pr-utils/.env
• Check that your PAT hasn't expired
• Ensure AZDO_USER matches your Azure DevOps email

�🔧 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