pydoctor-cli 2.0.1__tar.gz → 2.2.0__tar.gz

{pydoctor_cli-2.0.1 → pydoctor_cli-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydoctor-cli
-Version: 2.0.1
+Version: 2.2.0
 Summary: Premium Python environment diagnostic CLI — your project's personal physician.
 Author-email: Favour Bamgboye <demiladebamgboye@gmail.com>
 Maintainer-email: Favour Bamgboye <demiladebamgboye@gmail.com>
@@ -206,9 +206,9 @@ License:                                  Apache License
         See the License for the specific language governing permissions and
         limitations under the License.
         
-Project-URL: Homepage, https://pydoctor.vercel.app
+Project-URL: Homepage, https://pydoctor-docs.thally.app
 Project-URL: Repository, https://github.com/iamAgbaCoder/pydoctor-cli
-Project-URL: Documentation, https://pydoctor.vercel.app/docs
+Project-URL: Documentation, https://pydoctor-docs.thally.app
 Project-URL: Bug Tracker, https://github.com/iamAgbaCoder/pydoctor-cli/issues
 Project-URL: Changelog, https://github.com/iamAgbaCoder/pydoctor-cli/releases
 Keywords: pydoctor,diagnosis,dependency-checker,vulnerability-scanner,python-health,cli-tool,security-audit,static-analysis
@@ -253,6 +253,7 @@ Dynamic: license-file
 
 **PyDoctor** is a standalone, developer-friendly diagnostic assistant for Python environments. It acts like a personal physician for your code — scanning your project and environment to prescribe fixes for misconfigurations, dependencies, and security vulnerabilities.
 
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/pydoctor-cli?period=total&units=INTERNATIONAL_SYSTEM&left_color=GREY&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/pydoctor-cli)
 [![CI Status](https://github.com/iamAgbaCoder/pydoctor-cli/actions/workflows/publish.yml/badge.svg)](https://github.com/iamAgbaCoder/pydoctor-cli/actions)
 [![PyPI version](https://img.shields.io/pypi/v/pydoctor-cli.svg?color=blue&style=flat-square)](https://pypi.org/project/pydoctor-cli/)
 [![Python versions](https://img.shields.io/pypi/pyversions/pydoctor-cli.svg?style=flat-square)](https://pypi.org/project/pydoctor-cli/)
@@ -299,6 +300,16 @@ pipx install pydoctor-cli
 pip install pydoctor-cli
 ```
 
+> Install `pydoctor-cli`, not `pydoctor`: that is an unrelated project (Twisted's API doc generator) that installs a command with the same name.
+
+PyDoctor scans your **project's** Python, wherever PyDoctor itself is installed. It uses the active virtualenv, or a `.venv`/`venv` in the project, and tells you which interpreter it chose. To choose one yourself:
+
+```bash
+pydoctor diagnose --python .venv/bin/python   # or set PYDOCTOR_PYTHON
+```
+
+📖 Full documentation: **https://pydoctor-docs.thally.app**
+
 ---
 
 ## ⚡ Usage
@@ -323,6 +334,25 @@ pydoctor fix
 
 ## Release History
 
+### v2.2.0
+Results you can trust: every fix in this release removes a case where PyDoctor reported a problem as fine, or got a severity wrong.
+
+- **Scans the right environment:** facts come from your project's interpreter, not PyDoctor's. Under pipx or `uv tool`, and in uv environments (which have no pip), 2.1.0 saw 0 packages and reported everything as OK. Works without pip (package metadata, `uv pip list --outdated`). New `--python` / `PYDOCTOR_PYTHON`; the report shows which interpreter was scanned and why.
+- **Fails loudly:** `ENV_PACKAGES_UNAVAILABLE` (error) when the environment can't be read, `ENV_DEPS_NOT_INSTALLED` when the scanned Python has none of your dependencies, and outdated checks that can't run say so instead of "all up to date".
+- **Virtualenv detection works:** it was always "active". The `diagnose` no-venv prompt now appears, and never blocks CI or piped runs.
+- **Real CVSS scores:** severity is computed from the CVSS v3 vector. Previously a 3.1 (Low) and a 9.8 (Critical) vulnerability were both shown as critical. GitHub's `MODERATE` is now medium.
+- **Right fix version:** for advisories with one fix per release line, `fix` targets your line (Django 5.1.2 → 5.1.4, not 4.2.17).
+- **CI guard finds real leaks:** scans every committed text file, adds Stripe, OpenAI, Anthropic, Slack, Google, private-key, database-URL and `SECRET_KEY` rules, flags committed `.env` files, and checks workflows for `pull_request_target` "pwn requests", script injection and `write-all` permissions. Findings have line numbers; add `# pydoctor: ignore` to silence one. Zero findings on Flask, Django, requests, httpx, FastAPI, DRF and pip.
+- **A score that moves:** a package's advisories count once, categories have diminishing returns, and any critical issue keeps the score below "Good". Expect different (usually higher) scores than 2.1.0.
+- **JSON:** includes `health`; `scan-security --json` reports advisory IDs, aliases, fixed version and CVSS score.
+- Smaller: database drivers, hashers and cache clients picked by Django settings count as used; faster advisory fetching; `--no-cache` no longer wipes the cache; circular import fixed; `github <repo>` and `docker` describe what they actually do.
+
+### 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.

{pydoctor_cli-2.0.1 → pydoctor_cli-2.2.0}/README.md

@@ -4,6 +4,7 @@
 
 **PyDoctor** is a standalone, developer-friendly diagnostic assistant for Python environments. It acts like a personal physician for your code — scanning your project and environment to prescribe fixes for misconfigurations, dependencies, and security vulnerabilities.
 
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/pydoctor-cli?period=total&units=INTERNATIONAL_SYSTEM&left_color=GREY&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/pydoctor-cli)
 [![CI Status](https://github.com/iamAgbaCoder/pydoctor-cli/actions/workflows/publish.yml/badge.svg)](https://github.com/iamAgbaCoder/pydoctor-cli/actions)
 [![PyPI version](https://img.shields.io/pypi/v/pydoctor-cli.svg?color=blue&style=flat-square)](https://pypi.org/project/pydoctor-cli/)
 [![Python versions](https://img.shields.io/pypi/pyversions/pydoctor-cli.svg?style=flat-square)](https://pypi.org/project/pydoctor-cli/)
@@ -50,6 +51,16 @@ pipx install pydoctor-cli
 pip install pydoctor-cli
 ```
 
+> Install `pydoctor-cli`, not `pydoctor`: that is an unrelated project (Twisted's API doc generator) that installs a command with the same name.
+
+PyDoctor scans your **project's** Python, wherever PyDoctor itself is installed. It uses the active virtualenv, or a `.venv`/`venv` in the project, and tells you which interpreter it chose. To choose one yourself:
+
+```bash
+pydoctor diagnose --python .venv/bin/python   # or set PYDOCTOR_PYTHON
+```
+
+📖 Full documentation: **https://pydoctor-docs.thally.app**
+
 ---
 
 ## ⚡ Usage
@@ -74,6 +85,25 @@ pydoctor fix
 
 ## Release History
 
+### v2.2.0
+Results you can trust: every fix in this release removes a case where PyDoctor reported a problem as fine, or got a severity wrong.
+
+- **Scans the right environment:** facts come from your project's interpreter, not PyDoctor's. Under pipx or `uv tool`, and in uv environments (which have no pip), 2.1.0 saw 0 packages and reported everything as OK. Works without pip (package metadata, `uv pip list --outdated`). New `--python` / `PYDOCTOR_PYTHON`; the report shows which interpreter was scanned and why.
+- **Fails loudly:** `ENV_PACKAGES_UNAVAILABLE` (error) when the environment can't be read, `ENV_DEPS_NOT_INSTALLED` when the scanned Python has none of your dependencies, and outdated checks that can't run say so instead of "all up to date".
+- **Virtualenv detection works:** it was always "active". The `diagnose` no-venv prompt now appears, and never blocks CI or piped runs.
+- **Real CVSS scores:** severity is computed from the CVSS v3 vector. Previously a 3.1 (Low) and a 9.8 (Critical) vulnerability were both shown as critical. GitHub's `MODERATE` is now medium.
+- **Right fix version:** for advisories with one fix per release line, `fix` targets your line (Django 5.1.2 → 5.1.4, not 4.2.17).
+- **CI guard finds real leaks:** scans every committed text file, adds Stripe, OpenAI, Anthropic, Slack, Google, private-key, database-URL and `SECRET_KEY` rules, flags committed `.env` files, and checks workflows for `pull_request_target` "pwn requests", script injection and `write-all` permissions. Findings have line numbers; add `# pydoctor: ignore` to silence one. Zero findings on Flask, Django, requests, httpx, FastAPI, DRF and pip.
+- **A score that moves:** a package's advisories count once, categories have diminishing returns, and any critical issue keeps the score below "Good". Expect different (usually higher) scores than 2.1.0.
+- **JSON:** includes `health`; `scan-security --json` reports advisory IDs, aliases, fixed version and CVSS score.
+- Smaller: database drivers, hashers and cache clients picked by Django settings count as used; faster advisory fetching; `--no-cache` no longer wipes the cache; circular import fixed; `github <repo>` and `docker` describe what they actually do.
+
+### 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.

{pydoctor_cli-2.0.1 → pydoctor_cli-2.2.0}/pydoctor/__init__.py

@@ -9,6 +9,6 @@ Author: Favour Bamgboye
 License: MIT
 """
 
-__version__ = "2.0.1"
+__version__ = "2.2.0"
 __author__ = "Favour Bamgboye"
 __description__ = "Python environment diagnostic CLI — your project's doctor."

{pydoctor_cli-2.0.1 → pydoctor_cli-2.2.0}/pydoctor/analysis/health_score.py

@@ -6,6 +6,7 @@ Calculates the numerical project health score and verdict.
 
 from __future__ import annotations
 
+import math
 from dataclasses import dataclass
 
 from pydoctor.core.report import DiagnosisReport, Issue
@@ -18,20 +19,62 @@ class HealthMetrics:
     message: str
 
 
+# Each category can cost at most this many points. Within a category every
+# extra issue still lowers the score, but by less (diminishing returns), so
+# fixing issues in a project with dozens of them visibly moves the score.
+CATEGORY_CAPS: dict[str, float] = {
+    "security": 60,
+    "ci": 50,
+    "dependencies": 40,
+    "environment": 30,
+    "outdated": 15,
+    "unused": 10,
+}
+
+# A project with any critical issue can't be rated Good or Excellent.
+CRITICAL_CEILING = 69
+
+# Issues that mean part of the scan didn't run.
+INCOMPLETE_CODES = {"ENV_PACKAGES_UNAVAILABLE", "SEC_SCAN_INCOMPLETE"}
+
+
 def calculate_health(report: DiagnosisReport) -> HealthMetrics:
     """
     Calculate project health score (0-100) based on identified issues.
     """
     score = _compute_score(report)
-    categories = list({i.category for i in report.issues})
-    return _get_verdict(score, categories)
+    categories = list({i.category for i in report.issues if i.code not in INCOMPLETE_CODES})
+    metrics = _get_verdict(score, categories)
+    if any(i.code in INCOMPLETE_CODES for i in report.issues):
+        metrics.verdict = "Incomplete"
+        metrics.message = (
+            "Some checks couldn't run, so this score only covers what was checked. "
+            "See the errors above."
+        )
+    return metrics
 
 
 def _compute_score(report: DiagnosisReport) -> int:
-    score = 100
+    raw: dict[str, float] = {}
+    # One upgrade usually fixes every advisory for a package, so a package
+    # costs the penalty of its worst advisory, not one penalty per advisory.
+    per_package: dict[str, int] = {}
     for issue in report.issues:
-        score -= _calculate_issue_penalty(issue)
-    return max(0, score)
+        penalty = _calculate_issue_penalty(issue)
+        if issue.code == "SEC_VULNERABILITY" and issue.package:
+            per_package[issue.package] = max(per_package.get(issue.package, 0), penalty)
+            continue
+        raw[issue.category] = raw.get(issue.category, 0) + penalty
+    if per_package:
+        raw["security"] = raw.get("security", 0) + sum(per_package.values())
+    lost = 0.0
+    for category, points in raw.items():
+        cap = CATEGORY_CAPS.get(category)
+        lost += cap * (1 - math.exp(-points / cap)) if cap else points
+    score = max(0, round(100 - lost))
+    if any(i.severity.lower() == "critical" for i in report.issues):
+        score = min(score, CRITICAL_CEILING)
+    return score
 
 
 def _calculate_issue_penalty(issue: Issue) -> int:

{pydoctor_cli-2.0.1 → pydoctor_cli-2.2.0}/pydoctor/cache/cache_manager.py

@@ -79,7 +79,7 @@ class CacheManager:
 
         return entry.get("value")
 
-    def set(self, key: str, value: Any) -> None:
+    def set(self, key: str, value: Any, save: bool = True) -> None:
         """
         Store a value in the cache with the current timestamp.
 
@@ -87,8 +87,15 @@ class CacheManager:
         ----------
         key:   Cache key.
         value: Any JSON-serialisable value.
+        save:  Write to disk now. Pass False when setting many keys, then call
+               ``save()`` once (writing the whole file per key is quadratic).
         """
         self._data[key] = {"_ts": time.time(), "value": value}
+        if save:
+            self._save()
+
+    def save(self) -> None:
+        """Persist the cache to disk."""
         self._save()
 
     def invalidate(self, key: str) -> None: