PyDoctor

The Documentation

Technical specifications for the PyDoctor diagnostic kernel, automation hooks, and environment security protocols.

01

Introduction

PyDoctor is a developer-first CLI tool designed to analyze and diagnose the health of Python environments and projects.

outdated dependencies
security vulnerabilities
unused packages
dependency issues
environment misconfigurations
CI/CD workflow risks
docker container health
github repository audits

PyDoctor acts as "The Doctor for Your Python Environment."

02

System Requirements

PyDoctor is designed to be **cross-platform, lightweight, and fast**. Ensure your environment meets the following minimum requirements.

Core Specs

  • Python 3.9+
  • OS macOS, Linux, Win
  • Environment venv / virtualenv
  • Manager pip

Supported Shells

bashzshfishPowerShellCMD
03

Installation

Primary Install

The fastest way to install PyDoctor is through pip. Post-installation, the command is available globally.

pip install pydoctor-cli

Recommended: pipx

For an isolated global CLI installation, utilizing pipx is the gold standard.

pipx install pydoctor-cli

From Source

GIT SOURCE
$git clone https://github.com/iamAgbaCoder/pydoctor-cli.git
$cd pydoctor-cli && pip install -e .
04

Quick Start

Navigate to any Python project node and initiate a full diagnostic kernel scan.

pydoctor diagnose

Autonomous Report Example

PyDoctor Environment Diagnosis

✔ Python Version: 3.11
✔ Virtual Environment Active
✔ Installed Packages: 124

Dependency Analysis
⚠ 4 Outdated Packages

Security Scan
✖ 1 Critical Vulnerability

Unused Dependencies
⚠ 2 Unused Packages

Diagnosis Complete
05

Environment Analysis

Internal heuristics audit the Python runtime to verify binary integrity and environment health.

pydoctor check-env

CHECKS PERFORMED:

• Python version compatibility

• Active virtual environment status

• Binary PATH validity

06

Vulnerability Scanning

PyDoctor cross-references dependencies against global vulnerability databases (CVE/GHSA).

Urgent: Security Integrity Check

Critical vulnerabilities are automatically tiered into: LOW | MEDIUM | HIGH | CRITICAL.

pydoctor scan-security
07

Package Managers

PyDoctor is engine-agnostic and provides native support for the most popular Python package managers. It automatically detects your project structure and tailors its diagnostic kernel accordingly.

📦

pip

The standard

📜

Poetry

Modern deps

🚀

PDM

Next-gen

⚡

uv

Extremely fast

Note: PyDoctor reads pyproject.toml, setup.py, and requirements.txt dynamically based on the active manager.
08

CLI Commands

Master the PyDoctor CLI with these essential diagnostic flags and commands.

pydoctor diagnoseInitiate full project health scan
pydoctor check-envVerify Python environment integrity
pydoctor scan-securityRun security vulnerability analysis
pydoctor list-depsDisplay deep dependency tree
pydoctor cleanIdentify and purge unused packages
pydoctor check --ciDetect exposed secrets & CI risks
pydoctor dockerDiagnose containers & Dockerfiles
pydoctor githubAudit repository & git configurations
09

Dependency Analysis

PyDoctor builds a directed acyclic graph (DAG) of your dependencies to find conflicts and circular references.

pydoctor list-deps --tree

Graph Logic

The kernel recursively resolves every sub-dependency to ensure version pin compatibility across your entire stack.

Pinning Engine

Automatically suggests optimal version ranges for your requirements.txt or pyproject.toml.

010

Advanced Health Scoring

The v2.0.0 engine introduces a multi-variable scoring algorithm that computes a project health score from 0 to 100.

90DR-INDEX

PENALTY HEURISTICS

Security Flaws: -30pts
Outdated Core: -15pts
Env drift: -5pts
CI Warnings: -10pts

Dynamic Fix Suggestions

The 🚀 Next Steps terminal guide intelligently suggests remediation paths based on your current score. It automatically suppresses irrelevant noisy commands and self-optimizes once you achieve the perfect 100/100 health certificate.

Pro Tip: Aim for a score of 95+ to ensure industrial-grade project stability.
011

Outdated Packages

Stay ahead of the curve. PyDoctor identifies packages with available upstream updates and major version jumps.

pydoctor check-updates
Total Outdated Detected12+
012

Unused Dependencies

Bloated environments are slow and insecure. Our heuristics find packages that are installed but never imported in your source code.

pydoctor find-unused

Scanning Heuristics: Static Analysis + Import Tracking

013

Reporting Engine

Generate machine-readable assets for CI/CD pipelines and security audits.

JSON
Markdown
HTML
pydoctor report --format json
014

CI/CD Integration

Integrate PyDoctor into your GitHub Actions or GitLab CI to fail builds on critical vulnerabilities.

# .github/workflows/verify.yml

- name: PyDoctor Security Scan

  run: pydoctor check --ci --exit-code

015

Configuration

PyDoctor can be configured globally using a `.pydoctorrc` or within your `pyproject.toml` file.

[tool.pydoctor]
severity_threshold = "medium"
exclude_packages = ["pytest", "black"]
report_format = "json"
016

Contributing

PyDoctor is open-source. We welcome contributions to our diagnostic kernel and security heuristics.

GitHub RepositoryRead Guide