🧭 Navigation

• Project Description
• Release History
• Quick Start
• Usage
• Development

Project Description

PyDoctor isn't just a scanner; it's a complete remediation tool that performs static analysis on your project files and cross-references your environment against live security databases.

Key Features

• Environment Analysis: Detects missing virtualenvs, outdated pip, or deprecated Python versions.
• Dependency Fix: Automatically resolves conflicts and installs missing packages.
• Security: Integrates with OSV.dev API to check against known CVEs/GHSAs.
• Unused Detection: Identifies declared packages that are never imported.
• Multi-Manager: Intelligent support for pip, Poetry, uv, and pdm.
• Rich UI: Beautiful progress spinners, icons, and color-coded severities.

📦 Installation

PyDoctor requires Python 3.10+. For the best experience, we recommend using pipx.

# Recommended: Install globally in an isolated environment
pipx install pydoctor-cli

# Standard pip installation
pip install pydoctor-cli

⚡ Usage

Full Diagnosis

Run a comprehensive check-up on your project.

pydoctor diagnose

Automated Fixes

Let PyDoctor perform the heavy lifting. It will offer to install missing packages, upgrade outdated ones, and clean up your environment.

pydoctor fix

Release History

v2.1.0

• pydoctor fix reports what really happened: upgrades are verified against the installed version. If a pin in pyproject.toml blocks an upgrade, pydoctor says so and shows the constraint instead of printing "fixed".
• One prompt per package: vulnerable packages are offered once, with the advisory count, and upgraded to the lowest version that fixes every advisory.
• No accidental removals: pydoctor fix <package> no longer offers to uninstall it. Removal only runs with --remove.
• Fewer false "unused" reports: packages imported under a different name (decouple), loaded from strings (Django INSTALLED_APPS, MIDDLEWARE, backends), or run from a Procfile/Dockerfile (gunicorn) are recognised as used. Remaining findings are labelled "Possibly unused".

v2.0.1

• Security scans fail closed: if the OSV database can't be reached, pydoctor now reports SEC_SCAN_INCOMPLETE (error, exit 1) instead of a clean result.
• No more double-counted advisories: advisories listed under several IDs (e.g. GHSA and PYSEC) are reported and scored once.

v2.0.0

• 🚀 Major UI/UX Revamp: Introduced a premium "kernel/hacker" aesthetic with boxed reports, dynamic progress animations, and improved readability.
• 🛡️ CI/CD Guard Mode: New pydoctor check --ci command to detect exposed secrets (AWS, GitHub, PyPI tokens) and insecure workflow patterns in GitHub Actions/GitLab CI.
• 🐳 Docker Support: New pydoctor docker command to diagnose Python issues inside containers and audit Dockerfiles.
• 🐙 GitHub Integration: New pydoctor github command for repository-wide health scans and local git configuration audits.
• 📈 Advanced Health Scoring: Refined the 0-100 scoring algorithm with granular penalties for security vulnerabilities and CI/CD risks.
• ⚡ Performance Boost: Parallel execution engine for scanning large codebases faster.
• 🔍 Smart Environment Detection: Now automatically prompts users when no venv is found, preventing accidental system-wide changes.
• 🎯 Context-Aware Reporting: Targeted commands (like pydoctor scan-unused or pydoctor github) now intelligently suppress unrelated scanner noise.
• 🧠 OSV Deep-Fetching: Overcame upstream OSV API batch limits by implementing dynamic real-time fetching and caching of full vulnerability advisories natively.
• 🔗 Transitive Dependency Tracking: PyDoctor now uniquely segregates mathematical/transitive dependencies from pure unused bloat, effectively preventing pydoctor fix from uninstalling required sub-packages.
• 🛠️ Refined Git Discovery: Utilizes native git heuristics (--is-inside-work-tree & --show-toplevel) to flawlessly map out project roots and repository states, even when scanning from deeply nested sub-directories.
• 🔮 Dynamic Fix Suggestions: The 🚀 Next Steps terminal guide now dynamically rules out the currently running command and gracefully self-hides when a project achieves a perfect 100/100 health rating.

v0.1.3

• Enhanced Package Detection: Pydoctor now intelligently detects and uses your project's specific virtual environment (Poetry, UV, PDM, or standard venv) to run all scans and diagnoses.
• Improved Architecture: Refactored core modules to reduce complexity and improve maintainability (resolved C901 linting errors).
• Fix Rendering Errors: Resolved issues with undefined verbose detail renderers in the CLI.

v0.1.2

• Maintenance: Minor internal fixes and linting improvements for CI/CD stability.
• Professional Meta: Revamped pyproject.toml with complete author metadata and SEO keywords.

v0.1.1

• Bug Fixes: Minor improvements to dependency scanning reliability.
• Metadata Update: Initial professional README branding.

v0.1.0

• Initial Release: Core diagnostic engine with support for Environment, Dependencies, Outdated Packages, Security, and Unused Package scans.
• Remediation: Initial support for auto-fixing issues via pydoctor fix.

Verified Details

• Homepage: GitHub Repository
• Issue Tracker: GitHub Issues
• Repository: iamAgbaCoder/pydoctor-cli

👥 Maintainers

• Favour Bamgboye (@iamAgbaCoder)

📄 Meta

• License: Apache License 2.0
• Author: Favour Bamgboye
• Requires: Python >=3.10
• Classifiers:
  • Development Status :: 4 - Beta
  • Intended Audience :: Developers
  • License :: OSI Approved :: Apache Software License
  • Operating System :: OS Independent
  • Programming Language :: Python :: 3
  • Programming Language :: Python :: 3.10
  • Programming Language :: Python :: 3.11
  • Programming Language :: Python :: 3.12
  • Topic :: Software Development :: Quality Assurance