home / skills / wdm0006 / python-skills / library-review

library-review skill

safe

This skill reviews Python libraries across structure, packaging, tests, security, docs, API design, and CI/CD to deliver actionable improvement guidance.

npx playbooks add skill wdm0006/python-skills --skill library-review

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.8 KB

---
name: reviewing-python-libraries
description: Comprehensively reviews Python libraries for quality across project structure, packaging, code quality, testing, security, documentation, API design, and CI/CD. Provides actionable feedback and improvement recommendations. Use when evaluating library health, preparing for major releases, or auditing dependencies.
---

# Python Library Review

## Quick Health Check (5 min)

```bash
git clone https://github.com/user/package && cd package
cat pyproject.toml | head -50        # Modern config?
ls tests/ && pytest --collect-only   # Tests exist?
pytest --cov=package | tail -20      # Coverage?
pip install bandit && bandit -r src/ # Security?
```

## Review Dimensions

| Area | Check For |
|------|-----------|
| Structure | src/ layout, py.typed marker |
| Packaging | pyproject.toml (not setup.py) |
| Code | Type hints, docstrings, no anti-patterns |
| Tests | 80%+ coverage, edge cases |
| Security | No secrets, input validation, pip-audit clean |
| Docs | README, API docs, changelog |
| API | Consistent naming, sensible defaults |
| CI/CD | Tests on PR, multi-Python, security scans |

## Red Flags 🚩

- No tests
- No type hints
- setup.py only (no pyproject.toml)
- Pinned exact versions for all deps
- No LICENSE file
- Last commit > 1 year ago

## Green Flags ✅

- Active maintenance (recent commits)
- High test coverage (>85%)
- Comprehensive CI/CD
- Type hints throughout
- Clear documentation
- Semantic versioning

## Report Template

```markdown
# Library Review: [package]

**Rating:** [Excellent/Good/Needs Work/Significant Issues]

## Strengths
- [Strength 1]

## Areas for Improvement
- [Issue 1] - Severity: High/Medium/Low

## Category Scores
| Category | Score |
|----------|-------|
| Structure | ⭐⭐⭐⭐⭐ |
| Testing | ⭐⭐⭐☆☆ |
| Security | ⭐⭐⭐⭐☆ |

## Recommendations
1. [High priority action]
2. [Medium priority action]
```

For detailed checklists, see:
- **[CHECKLIST.md](CHECKLIST.md)** - Full review checklist
- **[REPORT_TEMPLATE.md](REPORT_TEMPLATE.md)** - Complete report template

## Best Practices Checklist

```
Essential:
- [ ] pyproject.toml valid
- [ ] Tests exist and pass
- [ ] README has install/usage
- [ ] LICENSE present
- [ ] No hardcoded secrets

Important:
- [ ] Type hints on public API
- [ ] CI runs tests on PRs
- [ ] Coverage > 70%
- [ ] Changelog maintained

Recommended:
- [ ] src/ layout
- [ ] py.typed marker
- [ ] Security scanning in CI
- [ ] Contributing guide
```

## Learn More

This skill is based on the [Guide to Developing High-Quality Python Libraries](https://mcginniscommawill.com/guides/python-library-development/) by [Will McGinnis](https://mcginniscommawill.com/). See the full guide for detailed quality criteria and best practices across all dimensions of library development.

Overview

This skill comprehensively reviews Python libraries for maintainability, correctness, and security. It inspects project structure, packaging, code quality, testing, documentation, API design, and CI/CD to produce actionable recommendations. Use it to evaluate library health before releases, audits, or dependency adoption.

How this skill works

It runs a quick health check (repo layout, pyproject.toml, test presence, coverage, basic security scans) and then performs deeper inspections across eight dimensions: structure, packaging, code, tests, security, docs, API design, and CI/CD. The output is a concise report with strengths, categorized scores, and prioritized recommendations you can act on. Checks include static analysis, type hint coverage, test coverage thresholds, dependency hygiene, and CI configuration review.

When to use it

Before a major release or public announcement
When auditing dependencies for security and maintainability
During an open-source quality improvement initiative
As part of a pre-merge checklist for library PRs
When preparing a package for PyPI distribution

Best practices

Keep pyproject.toml as the authoritative build config and prefer src/ layout
Provide type hints on the public API and include a py.typed marker
Maintain automated tests with target coverage (aim >80%) and test edge cases
Run CI on PRs across supported Python versions and include security scans
Ship a clear README, changelog, LICENSE, and contribution guide

Example use cases

Audit a third-party dependency before adding it to production
Prepare an internal library for semantic versioning and release
Create a prioritized action plan to raise a library from ‘Needs Work’ to ‘Good’
Perform recurring health checks on core libraries as part of engineering hygiene
Review community contributions to ensure they meet project quality standards

FAQ

What quick checks will you run first?

A five-minute health check: verify pyproject.toml, ensure tests exist and collect, run pytest with coverage, and run a basic security scan (bandit/pip-audit).

What constitutes a blocking issue?

Blocking issues include no tests, no license, hardcoded secrets, pinned exact dependency versions across the board, or an unmaintained repo (last commit >1 year) — these require immediate remediation.