feat: implement the two owner decisions from spike week
Requires-Python is now enforced by PipDock, not by the engine. SP-2 found the engines disagree: scipy 1.7.3 declares >=3.7,<3.11, and on Python 3.12 pip refuses it while uv plans to install it. G5 promises one behaviour across heads, so the preview must not change shape because the user flipped the engine radio. crates/pipdock-core/src/compat.rs screens every candidate against the environment's version before any engine command runs; rejects surface as PD-PKG-001 with the required range shown against the found version. This does not weaken "explain, don't reimplement" — resolution stays entirely the engine's. compat.rs only filters candidates the engine should never have been offered, using the slice of PEP 440 that actually appears in Requires-Python: comparison, wildcard and compatible-release operators. Specifiers it cannot parse count as compatible, because PipDock failing to read metadata must never be the reason an installable package is refused. Nine tests, including the exact scipy case the spike captured and the boundary cases where an off-by-one would reject a supported Python. probe.py keeps -I, and the cost is disclosed rather than hidden. Isolated mode is what stops a poisoned environment injecting code into the probe, so it stays; dropping to -E was rejected because a package in user site is part of the untrusted surface the isolation exists to exclude, and probing twice was rejected as a second interpreter start per scan for a non-primary case. Instead probe.py now reports hidden_user_site — the user-site path when it exists, sits off sys.path and is non-empty, else null. Verified: the system Python reports the path (352 dists), a venv reports null. The Installed screen shows a note naming the path only when it is non-null, so users of the affected case are told exactly what is missing while everyone else sees nothing. ERROR-CATALOG PD-PKG-001 changes from a stderr classification to a PipDock-raised code, because engine stderr cannot support it: pip reports it as plain "No matching distribution found", indistinguishable from PD-PKG-002, and uv does not enforce it at all. Docs updated: ARCHITECTURE 3 and 4, DATA-FLOW 2, SECURITY 2, UI-SPEC 4, ERROR-CATALOG 2, ROADMAP, CLAUDE.md, spikes/README.md. EN and VI strings added for both notes. Two non-blocking questions remain in spikes/README.md: search-ranking scope for M1, and how to obtain the five error fixtures this machine cannot produce. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
15 files changed
+417
-17
No files matched your search
@@ -27,6 +27,18 @@ The design is fully specified. Read in this order; do not invent behaviour that
|
||||
Two more that follow from them: every user-visible failure carries exactly one catalog code, and a
|
||||
failed package never aborts a batch (skip-and-continue, then a `"13 successful, 2 failed"` summary).
|
||||
|
||||
## What the spikes proved (read `spikes/README.md` before writing an adapter)
|
||||
|
||||
6. **Every plan must restate the full installed set as explicit requirements.** `install -U <pkg>`
|
||||
ignores installed packages' constraints in **both** engines and will break them at exit 0.
|
||||
7. **Every pip invocation needs `PYTHONIOENCODING=utf-8` + `PYTHONUTF8=1`.** Without it
|
||||
`--dry-run --report -` crashes on Windows/cp1252 (pip 25 *and* 26), data-dependently.
|
||||
8. **uv writes its plan to stderr**, so classify errors only after a plan-parse attempt.
|
||||
9. **`env_hash` lowercases the interpreter path on Windows**, or one env splits its pins and
|
||||
snapshots in two.
|
||||
10. **PipDock enforces `Requires-Python` itself** (`src/compat.rs`) — the engines disagree, and the
|
||||
preview must not depend on which one is selected.
|
||||
|
||||
## Conventions
|
||||
|
||||
- Crates `pipdock-*`; React components prefixed `Pd` (`PdPackageRow`, `PdConflictDialog`)
|
||||
|
||||
@@ -0,0 +1,294 @@
|
||||
//! Requires-Python enforcement.
|
||||
//!
|
||||
//! **Owner decision 2026-07-27 (spike SP-2).** The engines disagree: given `scipy==1.7.3`, which
|
||||
//! declares `Requires-Python >=3.7,<3.11`, pip refuses it on Python 3.12 while uv plans to install
|
||||
//! it. PipDock therefore enforces Requires-Python **itself**, so the preview is the same whichever
|
||||
//! engine is selected. A candidate this module rejects never reaches an engine command, and is
|
||||
//! reported as `PD-PKG-001` with the required range shown against the environment's version.
|
||||
//!
|
||||
//! This is a deliberately narrow slice of PEP 440: enough to evaluate a `Requires-Python`
|
||||
//! specifier set against a concrete interpreter version, and nothing more. Resolution itself is
|
||||
//! still the engine's job (ARCHITECTURE §1.2) — this only filters candidates the engine should
|
||||
//! never have been offered.
|
||||
|
||||
use crate::errors::{Code, PdError, Result};
|
||||
|
||||
/// A release version as an ordered list of numeric segments, e.g. `3.12.4` → `[3, 12, 4]`.
|
||||
///
|
||||
/// Only the release segment matters here. Pre-release, post-release and local segments are
|
||||
/// ignored: no interpreter PipDock manages is identified by them, and `Requires-Python` specifiers
|
||||
/// in the wild do not use them meaningfully.
|
||||
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
|
||||
pub struct PyVersion(Vec<u32>);
|
||||
|
||||
impl PyVersion {
|
||||
/// Parse a dotted numeric version.
|
||||
///
|
||||
/// # Errors
|
||||
/// Returns `PD-ENV-003` when the string is not a dotted sequence of numbers — that can only
|
||||
/// come from a broken `probe.py` reading, which is exactly what that code means.
|
||||
pub fn parse(raw: &str) -> Result<Self> {
|
||||
// Trim any pre/post/local suffix: "3.14.0rc1" -> "3.14.0".
|
||||
let release: &str = raw
|
||||
.split(['a', 'b', 'r', 'c', 'd', 'p', '+', '-'])
|
||||
.next()
|
||||
.unwrap_or("");
|
||||
let trimmed = release.trim_end_matches('.');
|
||||
if trimmed.is_empty() {
|
||||
return Err(PdError::new(
|
||||
Code::EnvProbeFailed,
|
||||
format!("bad version: {raw:?}"),
|
||||
));
|
||||
}
|
||||
let mut parts = Vec::new();
|
||||
for segment in trimmed.split('.') {
|
||||
let n: u32 = segment
|
||||
.parse()
|
||||
.map_err(|_| PdError::new(Code::EnvProbeFailed, format!("bad version: {raw:?}")))?;
|
||||
parts.push(n);
|
||||
}
|
||||
Ok(Self(parts))
|
||||
}
|
||||
|
||||
/// Compare against `other`, treating missing trailing segments as zero so `3.12` == `3.12.0`.
|
||||
fn cmp_padded(&self, other: &Self) -> std::cmp::Ordering {
|
||||
let len = self.0.len().max(other.0.len());
|
||||
for i in 0..len {
|
||||
let a = self.0.get(i).copied().unwrap_or(0);
|
||||
let b = other.0.get(i).copied().unwrap_or(0);
|
||||
match a.cmp(&b) {
|
||||
std::cmp::Ordering::Equal => {}
|
||||
other_ord => return other_ord,
|
||||
}
|
||||
}
|
||||
std::cmp::Ordering::Equal
|
||||
}
|
||||
|
||||
/// True when `self` starts with every segment of `prefix` — the `==3.9.*` / `!=3.9.*` rule.
|
||||
fn has_prefix(&self, prefix: &Self) -> bool {
|
||||
prefix.0.len() <= self.0.len() && self.0[..prefix.0.len()] == prefix.0[..]
|
||||
}
|
||||
}
|
||||
|
||||
impl std::fmt::Display for PyVersion {
|
||||
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
||||
let parts: Vec<String> = self.0.iter().map(u32::to_string).collect();
|
||||
f.write_str(&parts.join("."))
|
||||
}
|
||||
}
|
||||
|
||||
/// Why a candidate was rejected, or that it was accepted.
|
||||
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
|
||||
#[serde(tag = "kind", rename_all = "kebab-case")]
|
||||
pub enum Compatibility {
|
||||
/// The candidate may be offered to the engine.
|
||||
Compatible,
|
||||
/// The candidate declares a `Requires-Python` this interpreter does not satisfy.
|
||||
///
|
||||
/// Both fields are shown to the user, per `docs/ERROR-CATALOG.md` PD-PKG-001's "shows required
|
||||
/// range vs env version".
|
||||
RequiresPython {
|
||||
/// The specifier exactly as the package declared it.
|
||||
required: String,
|
||||
/// The interpreter's version.
|
||||
found: String,
|
||||
},
|
||||
/// The specifier could not be parsed.
|
||||
///
|
||||
/// Treated as compatible by [`check`] — an unreadable specifier is PipDock's problem, not the
|
||||
/// user's, and refusing an installable package would be the worse failure.
|
||||
Unparseable {
|
||||
/// The specifier that could not be read.
|
||||
specifier: String,
|
||||
},
|
||||
}
|
||||
|
||||
impl Compatibility {
|
||||
/// True when the candidate may proceed.
|
||||
#[must_use]
|
||||
pub fn is_ok(&self) -> bool {
|
||||
!matches!(self, Self::RequiresPython { .. })
|
||||
}
|
||||
}
|
||||
|
||||
/// Evaluate a `Requires-Python` specifier set against an interpreter version.
|
||||
///
|
||||
/// `requires_python` is the raw metadata value, e.g. `">=3.7,<3.11"`. `None` or empty means the
|
||||
/// package declares no constraint, which is always compatible.
|
||||
///
|
||||
/// Unknown or malformed specifiers yield [`Compatibility::Unparseable`], which
|
||||
/// [`Compatibility::is_ok`] treats as passing: blocking an install because PipDock could not read
|
||||
/// a specifier would turn a metadata oddity into a broken feature.
|
||||
#[must_use]
|
||||
pub fn check(requires_python: Option<&str>, env_version: &PyVersion) -> Compatibility {
|
||||
let Some(spec) = requires_python.map(str::trim).filter(|s| !s.is_empty()) else {
|
||||
return Compatibility::Compatible;
|
||||
};
|
||||
|
||||
for clause in spec.split(',') {
|
||||
let clause = clause.trim();
|
||||
if clause.is_empty() {
|
||||
continue;
|
||||
}
|
||||
match satisfies_clause(clause, env_version) {
|
||||
Some(true) => {}
|
||||
Some(false) => {
|
||||
return Compatibility::RequiresPython {
|
||||
required: spec.to_owned(),
|
||||
found: env_version.to_string(),
|
||||
};
|
||||
}
|
||||
None => {
|
||||
return Compatibility::Unparseable {
|
||||
specifier: spec.to_owned(),
|
||||
};
|
||||
}
|
||||
}
|
||||
}
|
||||
Compatibility::Compatible
|
||||
}
|
||||
|
||||
/// `Some(true|false)` when the clause was understood, `None` when it was not.
|
||||
fn satisfies_clause(clause: &str, env: &PyVersion) -> Option<bool> {
|
||||
use std::cmp::Ordering::{Equal, Greater, Less};
|
||||
|
||||
// Longest operators first: `>=` must not be read as `>`.
|
||||
let (op, rest) = ["===", "==", "!=", ">=", "<=", "~=", ">", "<"]
|
||||
.iter()
|
||||
.find_map(|op| clause.strip_prefix(*op).map(|rest| (*op, rest.trim())))?;
|
||||
|
||||
// Wildcards are only meaningful for == and !=.
|
||||
let is_wildcard = rest.ends_with(".*");
|
||||
let bare = if is_wildcard {
|
||||
rest.trim_end_matches(".*")
|
||||
} else {
|
||||
rest
|
||||
};
|
||||
let target = PyVersion::parse(bare).ok()?;
|
||||
|
||||
Some(match op {
|
||||
"==" | "===" if is_wildcard => env.has_prefix(&target),
|
||||
"!=" if is_wildcard => !env.has_prefix(&target),
|
||||
"==" | "===" => env.cmp_padded(&target) == Equal,
|
||||
"!=" => env.cmp_padded(&target) != Equal,
|
||||
">=" => matches!(env.cmp_padded(&target), Greater | Equal),
|
||||
"<=" => matches!(env.cmp_padded(&target), Less | Equal),
|
||||
">" => env.cmp_padded(&target) == Greater,
|
||||
"<" => env.cmp_padded(&target) == Less,
|
||||
"~=" => {
|
||||
// PEP 440 compatible release: >= target, and equal on all but the last segment.
|
||||
if target.0.len() < 2 {
|
||||
return None; // `~=3` is invalid per PEP 440.
|
||||
}
|
||||
let prefix = PyVersion(target.0[..target.0.len() - 1].to_vec());
|
||||
matches!(env.cmp_padded(&target), Greater | Equal) && env.has_prefix(&prefix)
|
||||
}
|
||||
_ => return None,
|
||||
})
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
fn v(s: &str) -> PyVersion {
|
||||
PyVersion::parse(s).unwrap_or_else(|e| panic!("{s}: {e}"))
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn the_scipy_case_from_sp2() {
|
||||
// The exact divergence that prompted this module: scipy 1.7.3 declares >=3.7,<3.11.
|
||||
// pip refuses it on Python 3.12; uv planned to install it. PipDock refuses, both engines.
|
||||
let got = check(Some(">=3.7,<3.11"), &v("3.12.10"));
|
||||
assert_eq!(
|
||||
got,
|
||||
Compatibility::RequiresPython {
|
||||
required: ">=3.7,<3.11".into(),
|
||||
found: "3.12.10".into()
|
||||
}
|
||||
);
|
||||
assert!(!got.is_ok());
|
||||
|
||||
// ...and accepts it on an interpreter that does satisfy the range.
|
||||
assert_eq!(
|
||||
check(Some(">=3.7,<3.11"), &v("3.10.13")),
|
||||
Compatibility::Compatible
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn no_constraint_is_always_compatible() {
|
||||
for spec in [None, Some(""), Some(" ")] {
|
||||
assert_eq!(
|
||||
check(spec, &v("3.12")),
|
||||
Compatibility::Compatible,
|
||||
"{spec:?}"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn boundary_comparisons_pad_missing_segments() {
|
||||
// ">=3.8" must accept exactly 3.8.0 — an off-by-one here would reject a supported Python.
|
||||
assert!(check(Some(">=3.8"), &v("3.8.0")).is_ok());
|
||||
assert!(check(Some(">=3.8"), &v("3.8")).is_ok());
|
||||
assert!(!check(Some(">=3.8"), &v("3.7.17")).is_ok());
|
||||
|
||||
// "<3.11" must reject exactly 3.11.0 and accept 3.10.x.
|
||||
assert!(!check(Some("<3.11"), &v("3.11.0")).is_ok());
|
||||
assert!(check(Some("<3.11"), &v("3.10.99")).is_ok());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn wildcard_clauses() {
|
||||
assert!(!check(Some("!=3.9.*"), &v("3.9.7")).is_ok());
|
||||
assert!(check(Some("!=3.9.*"), &v("3.10.0")).is_ok());
|
||||
assert!(check(Some("==3.12.*"), &v("3.12.4")).is_ok());
|
||||
assert!(!check(Some("==3.12.*"), &v("3.13.0")).is_ok());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn compatible_release_operator() {
|
||||
// ~=3.7 means >=3.7, ==3.*
|
||||
assert!(check(Some("~=3.7"), &v("3.12")).is_ok());
|
||||
assert!(!check(Some("~=3.7"), &v("4.0")).is_ok());
|
||||
assert!(!check(Some("~=3.7"), &v("3.6")).is_ok());
|
||||
// ~=3.7.2 means >=3.7.2, ==3.7.*
|
||||
assert!(check(Some("~=3.7.2"), &v("3.7.9")).is_ok());
|
||||
assert!(!check(Some("~=3.7.2"), &v("3.8.0")).is_ok());
|
||||
assert!(!check(Some("~=3.7.2"), &v("3.7.1")).is_ok());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn multiple_clauses_must_all_hold() {
|
||||
let spec = Some(">=3.8,!=3.9.*,<4");
|
||||
assert!(check(spec, &v("3.8.1")).is_ok());
|
||||
assert!(!check(spec, &v("3.9.18")).is_ok());
|
||||
assert!(check(spec, &v("3.12.0")).is_ok());
|
||||
assert!(!check(spec, &v("4.0.0")).is_ok());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn unreadable_specifiers_do_not_block_the_user() {
|
||||
// PipDock failing to read metadata must never be the reason an installable package is
|
||||
// refused — that would turn a metadata oddity into a broken feature.
|
||||
let got = check(Some(">=3.8 or maybe 3.9"), &v("3.12"));
|
||||
assert!(matches!(got, Compatibility::Unparseable { .. }));
|
||||
assert!(got.is_ok());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn prerelease_interpreter_versions_parse_to_their_release() {
|
||||
assert_eq!(v("3.14.0rc1"), v("3.14.0"));
|
||||
assert_eq!(v("3.15.0b4"), v("3.15.0"));
|
||||
assert!(check(Some(">=3.14"), &v("3.14.0rc1")).is_ok());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn malformed_versions_are_rejected_with_the_probe_code() {
|
||||
for bad in ["", "abc", "3..4", "3.x", "."] {
|
||||
let err = PyVersion::parse(bad).expect_err(&format!("{bad:?} must be rejected"));
|
||||
assert_eq!(err.code, Code::EnvProbeFailed, "{bad:?}");
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -156,6 +156,7 @@ mod tests {
|
||||
prefix: r"C:\proj\.venv".into(),
|
||||
python_version: "3.12.4".into(),
|
||||
externally_managed: false,
|
||||
hidden_user_site: None,
|
||||
source: crate::model::EnvSource::VenvScan,
|
||||
};
|
||||
let err = UvEngine
|
||||
|
||||
@@ -23,6 +23,7 @@
|
||||
|
||||
#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
|
||||
|
||||
pub mod compat;
|
||||
pub mod engine;
|
||||
pub mod envs;
|
||||
pub mod errors;
|
||||
@@ -34,6 +35,7 @@ pub mod pins;
|
||||
pub mod plan;
|
||||
pub mod snapshot;
|
||||
|
||||
pub use compat::{Compatibility, PyVersion};
|
||||
pub use errors::{Code, PdError, Result};
|
||||
pub use model::{Dist, EngineId, OutdatedDist, PkgName, PyEnv, Version};
|
||||
|
||||
|
||||
@@ -67,10 +67,26 @@ pub struct PyEnv {
|
||||
/// PEP 668 marker present. When true, mutation is blocked unless the user enabled the
|
||||
/// Settings override (`PD-ENV-002`, SECURITY §3).
|
||||
pub externally_managed: bool,
|
||||
/// User site-packages directory that `probe.py -I` is hiding, when there is one.
|
||||
///
|
||||
/// Owner decision 2026-07-27 (SP-6): the probe keeps running isolated, so on a non-venv
|
||||
/// system Python it reports fewer distributions than `pip list` does. `Some` means packages
|
||||
/// really are hidden and the Installed screen shows a note naming this path; `None` — always
|
||||
/// the case inside a venv — means the listing is complete.
|
||||
#[serde(default)]
|
||||
pub hidden_user_site: Option<PathBuf>,
|
||||
/// Where this env came from.
|
||||
pub source: EnvSource,
|
||||
}
|
||||
|
||||
impl PyEnv {
|
||||
/// True when the installed listing is known to be incomplete, so the UI must say so.
|
||||
#[must_use]
|
||||
pub fn listing_is_partial(&self) -> bool {
|
||||
self.hidden_user_site.is_some()
|
||||
}
|
||||
}
|
||||
|
||||
/// A PEP 503-normalized distribution name.
|
||||
///
|
||||
/// Constructing one is the *only* way a package name reaches an argv array, which is what makes
|
||||
|
||||
@@ -70,6 +70,38 @@ def _externally_managed() -> bool:
|
||||
return any(os.path.isfile(p) for p in candidates)
|
||||
|
||||
|
||||
def _hidden_user_site() -> str | None:
|
||||
"""Return the user site-packages path when it exists but is NOT on this run's sys.path.
|
||||
|
||||
Owner decision 2026-07-27 (spike SP-6): PipDock keeps running the probe with -I, because
|
||||
isolated mode is what stops a poisoned environment injecting code into it (SECURITY section 2).
|
||||
The cost is that -I also disables user site-packages, so on a non-venv system Python the probe
|
||||
reports fewer distributions than `pip list` does -- measured at 352 vs 375 on the dev machine.
|
||||
|
||||
Rather than warn always, report the path only when packages really are being hidden, so the UI
|
||||
can show an accurate note instead of a permanent disclaimer. Returns None inside a venv (no
|
||||
user site applies) and None when the directory is absent or empty.
|
||||
"""
|
||||
if sys.prefix != sys.base_prefix:
|
||||
return None # venv: user site does not apply
|
||||
try:
|
||||
import site
|
||||
|
||||
user_site = site.getusersitepackages()
|
||||
except Exception: # noqa: BLE001 - absence of a user site is not an error
|
||||
return None
|
||||
if not user_site or not os.path.isdir(user_site):
|
||||
return None
|
||||
if user_site in sys.path:
|
||||
return None # not hidden: it is already being read
|
||||
try:
|
||||
if not os.listdir(user_site):
|
||||
return None # exists but empty: nothing is being hidden
|
||||
except OSError:
|
||||
return None
|
||||
return user_site
|
||||
|
||||
|
||||
def _dists() -> list[dict[str, object]]:
|
||||
"""Read installed distribution metadata.
|
||||
|
||||
@@ -126,6 +158,8 @@ def main(argv: list[str] | None = None) -> int:
|
||||
"executable": sys.executable,
|
||||
"is_venv": sys.prefix != sys.base_prefix,
|
||||
"externally_managed": _externally_managed(),
|
||||
# Non-null means -I is hiding packages that pip would list; the UI shows a note.
|
||||
"hidden_user_site": _hidden_user_site(),
|
||||
"dists": _dists(),
|
||||
}
|
||||
except Exception as exc: # noqa: BLE001 - the core turns this into PD-ENV-003
|
||||
|
||||
@@ -60,6 +60,12 @@ Key model types:
|
||||
- `ResolutionReport` — normalized output of the dry-run: `{ changes: Vec<Change>, held_back: Vec<HeldBack{ pkg, resolved, latest, blockers: Vec<Blocker{by, constraint}> }>, impossible: Option<ImpossibleDetail>, raw: String }`. **Both adapters must emit this same shape** — this is the whole point of the trait. The pip adapter fills it from `--dry-run --report` JSON; the uv adapter from its dry-run plan output (format pinned during spike SP-1; fixtures under `crates/pipdock-core/tests/fixtures/`).
|
||||
- `Blocker` computation: the engine's report says *what* was held back; *who* is responsible comes from cross-referencing the reverse-dependency graph (§4) with each blocker's `Requires-Dist` constraints. If attribution is ambiguous, show constraints without a culprit rather than guessing.
|
||||
|
||||
### Requires-Python is enforced by PipDock, not the engine
|
||||
|
||||
**Owner decision 2026-07-27 (spike SP-2).** The two engines disagree: `scipy==1.7.3` declares `Requires-Python >=3.7,<3.11`, and on Python 3.12 pip refuses it while uv plans to install it. Since G5 promises one behavior across heads, the preview must not change shape because the user flipped the engine radio — so `pipdock-core` evaluates `Requires-Python` itself in `src/compat.rs`, before any candidate reaches an engine command, and reports rejects as `PD-PKG-001` with the required range against the environment's version.
|
||||
|
||||
This does not violate "explain, don't reimplement" (§1.2): resolution is still entirely the engine's. `compat.rs` only filters candidates the engine should never have been offered, using a narrow slice of PEP 440 — the comparison, wildcard and compatible-release operators as they appear in `Requires-Python`. Specifiers it cannot parse are treated as **compatible**, because PipDock failing to read metadata must never be the reason an installable package is refused.
|
||||
|
||||
### Engine selection
|
||||
|
||||
`Settings.engine ∈ {pip, uv}`. First run: probe `uv --version` on PATH → preselect uv if present, else pip; user can change any time. The status bar always shows the active engine. Per-env override is P2.
|
||||
@@ -70,11 +76,14 @@ Rust cannot cheaply read a foreign env's installed metadata. PipDock embeds a si
|
||||
|
||||
```json
|
||||
{ "python": "3.12.4", "prefix": "...", "externally_managed": false,
|
||||
"is_venv": true, "hidden_user_site": null,
|
||||
"dists": [ { "name": "requests", "version": "2.32.3",
|
||||
"requires_dist": ["urllib3<3,>=1.21.1", "..."],
|
||||
"requires_python": ">=3.8" } ] }
|
||||
```
|
||||
|
||||
`hidden_user_site` is non-null only when `-I` is actually hiding packages from the listing — see SECURITY §2 for the decision and the UI note it drives.
|
||||
|
||||
From `requires_dist` the core builds the **reverse-dependency graph** used by: held-back attribution, uninstall guard, and pin auto-suggest. The helper is written to a temp file per invocation and never installed into the env. Compatibility floor: Python 3.10 (uses `importlib.metadata` only).
|
||||
|
||||
## 5. Index & metadata
|
||||
|
||||
+8
-1
@@ -15,11 +15,18 @@
|
||||
## 2. Shared preamble (all mutating flows)
|
||||
|
||||
```text
|
||||
[Select env] → probe.py → env facts (python ver, PEP 668, dist metadata)
|
||||
[Select env] → probe.py -I → env facts (python ver, PEP 668, hidden_user_site, dist metadata)
|
||||
│
|
||||
├─ EXTERNALLY-MANAGED detected → BLOCKED banner (PD-ENV-002)
|
||||
│ └─ explicit override in Settings → proceed with persistent warning chip
|
||||
├─ hidden_user_site non-null → Installed screen shows the partial-listing note
|
||||
│ (not a block; see SECURITY §2)
|
||||
└─ ok → flow continues; reverse-dep graph built from probe data
|
||||
|
||||
Every candidate is then screened against the environment's Python version by
|
||||
pipdock-core (ARCHITECTURE §3): incompatible ones are dropped from the plan with
|
||||
PD-PKG-001 before any engine command runs, so the preview is identical under pip
|
||||
and uv even though the engines themselves disagree.
|
||||
```
|
||||
|
||||
## 3. Update flow (state machine)
|
||||
|
||||
@@ -21,7 +21,7 @@
|
||||
| PD-BLD-001 | `Microsoft Visual C++ 14.0 or greater is required` | missing MSVC build tools | Install VS Build Tools, or prefer a wheel-providing version |
|
||||
| PD-BLD-002 | `error in pyproject.toml` / `Backend … failed` / `metadata-generation-failed` | broken sdist build backend | Try previous version; report upstream (owner's example case) |
|
||||
| PD-BLD-003 | `error: Microsoft Visual C++`-absent + `Failed building wheel` generic | sdist-only build failed | Same as above; details in log |
|
||||
| PD-PKG-001 | `No matching distribution found` + requires-python mismatch in metadata | package needs different Python | Shows required range vs env version |
|
||||
| PD-PKG-001 | **Raised by PipDock before the engine runs** — `crates/pipdock-core/src/compat.rs` evaluates the candidate's `Requires-Python` against the env's version. (Engine stderr is not a reliable signal: pip reports it as plain `No matching distribution found`, indistinguishable from PD-PKG-002, and uv does not enforce it at all.) | package needs different Python | Shows required range vs env version |
|
||||
| PD-PKG-002 | `No matching distribution found` (plain) | name/version typo or yanked | Check spelling/version; `pipdock info <pkg>` |
|
||||
| PD-PKG-003 | `File was already yanked` / yanked marker | yanked release requested | Pick a non-yanked version |
|
||||
| PD-PKG-004 | hash mismatch / `THESE PACKAGES DO NOT MATCH THE HASHES` | corrupted download | Purge engine cache (P1 UI; CLI: engine cache purge) and retry |
|
||||
|
||||
+1
-1
@@ -17,7 +17,7 @@ The entire architecture stands on assumptions that must be verified on a real ma
|
||||
| SP-5 | Answered by SP-1 | **No engine reports held-back items at all.** Resolved version, latest version and blocker must all be derived by PipDock — for pip as much as for uv, contrary to ARCHITECTURE §3's implication. |
|
||||
| SP-6 | Answered | `uv python list` returns downloadable entries and duplicate shims; `env_hash` **must lowercase** the interpreter path on Windows or pins and snapshots split in two. `probe.py -I` hides 24 user-site packages on a system Python — open decision. Microsoft Store Python still unverified. |
|
||||
|
||||
Four open questions for the owner are listed at the end of `spikes/README.md`; M1 should not start until at least the Requires-Python and `-I` decisions are made, since both change adapter behaviour.
|
||||
**Both adapter-behaviour questions were decided 2026-07-27** and are implemented: PipDock enforces `Requires-Python` itself so the preview is engine-independent (`crates/pipdock-core/src/compat.rs`, ARCHITECTURE §3), and `probe.py` keeps `-I` while reporting `hidden_user_site` so the Installed screen can disclose the gap accurately (SECURITY §2). Two non-blocking questions remain at the end of `spikes/README.md`: search ranking scope, and how to obtain the five error fixtures this machine cannot produce.
|
||||
|
||||
| # | Spike | Question to answer | Exit criterion |
|
||||
|---|---|---|---|
|
||||
|
||||
@@ -12,6 +12,7 @@ PipDock's job is to run package managers against local environments. The realist
|
||||
- Package names are validated against the PEP 508 name grammar (`^[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?$` after normalization) and version specs against PEP 440 before entering argv; anything else is rejected client-side with PD-PKG-002.
|
||||
- Interpreter paths come only from discovery (registry/launcher/uv) or an explicit user file-pick; they are canonicalized and existence-checked (PD-ENV-001) before use.
|
||||
- `probe.py` is stdlib-only, written to a temp file with a random name, executed with `-I` (isolated mode: ignores `PYTHONPATH`, user site) so a poisoned env cannot inject code into the probe.
|
||||
- **Owner decision 2026-07-27 (spike SP-6): `-I` stays, and the cost is disclosed rather than hidden.** Isolated mode also disables user site-packages, so on a *non-venv* system Python the probe sees fewer distributions than `pip list` does — measured at 352 vs 375 on the reference machine. Virtual environments, the primary target, have no user site and are unaffected. The probe therefore reports `hidden_user_site`: the user-site path when it exists, is off `sys.path`, and is non-empty; `null` otherwise. Only when it is non-null does the Installed screen show a note naming the path (`env.partialListing`), so the disclosure is accurate rather than a permanent disclaimer. Dropping to `-E` was rejected: a package in user site is part of the untrusted surface the isolation exists to exclude.
|
||||
- Child processes run with inherited user privileges only; PipDock never elevates in v1 (PD-PRM-001 blocks instead — elevation broker is P2 with its own review).
|
||||
|
||||
## 3. PEP 668 policy (protecting the system Python)
|
||||
|
||||
+1
-1
@@ -51,7 +51,7 @@ Sidebar is icon+label, collapsible to icons. Status line (mono) always shows env
|
||||
|
||||
**Environments.** Auto-discovered list (source chip: registry / py launcher / uv / manual) with python version and package count; PEP 668 envs carry a red `MANAGED` chip and a disabled state explaining PD-ENV-002. Actions: *Browse…*, *Rescan*, star-as-default.
|
||||
|
||||
**Installed.** Virtualized table: name (mono) · version · latest · size · chips. Up-to-date rows use `--color-text-dim` (owner's "dimmed" requirement); outdated rows show an `UPDATE` badge; pinned rows a 🔒 `--color-info` chip. Row actions: pin/unpin, uninstall, details. Multi-select via checkboxes; bulk action bar appears on selection.
|
||||
**Installed.** Virtualized table: name (mono) · version · latest · size · chips. When the env's `hidden_user_site` is non-null (non-venv system Pythons only — see SECURITY §2), an inline `--color-info` note above the table says user-account packages are not listed and names the path; it is informational, never a block, and never appears for a venv. Up-to-date rows use `--color-text-dim` (owner's "dimmed" requirement); outdated rows show an `UPDATE` badge; pinned rows a 🔒 `--color-info` chip. Row actions: pin/unpin, uninstall, details. Multi-select via checkboxes; bulk action bar appears on selection.
|
||||
|
||||
**Updates.** Same table filtered to outdated, badge count in sidebar. Header: *Select all* (excludes pinned; shows "3 pinned excluded"), *Update selected*. After resolve → **Preview panel** replaces the table: three grouped sections — *Will upgrade* (A `1.2 → 2.0`), *New dependencies*, *Needs decision* (held-back in `--color-warn` with one-line blocker sentence; impossible in `--color-danger`). Each needs-decision row hosts a segmented control: **Keep compatible · Skip · Force latest** (Force opens an inline confirm naming what breaks). Footer: `Confirm (n changes)` / `Back`.
|
||||
|
||||
|
||||
+27
-13
@@ -249,11 +249,15 @@ bites non-venv system Pythons — and `C:\Python314` reports `externally_managed
|
||||
blocks PipDock from managing it. The remaining 376 vs 375 gap is likely a shadowed distribution
|
||||
that `importlib.metadata` reports twice and pip de-duplicates by normalized name.
|
||||
|
||||
**Open decision** — it trades a documented security control against list accuracy:
|
||||
**DECIDED 2026-07-27 (owner): keep `-I`, and disclose the gap.** Dropping to `-E` was rejected —
|
||||
a package in user site is part of the untrusted surface the isolation exists to exclude. Probing
|
||||
twice was rejected as a second interpreter start per scan for a non-primary case.
|
||||
|
||||
- keep `-I` and show a "user-site packages not shown" note on non-venv environments; or
|
||||
- drop to `-E` (ignore `PYTHONPATH` only, keep user site); or
|
||||
- probe twice and reconcile, at the cost of a second interpreter start per scan.
|
||||
Implemented: `probe.py` now reports `hidden_user_site`, the user-site path when it exists, is off
|
||||
`sys.path` and is non-empty, and `null` otherwise. Verified: the system Python reports the path
|
||||
(352 dists), a venv reports `null`. `PyEnv::listing_is_partial()` exposes it, and the Installed
|
||||
screen shows a note naming the path only when it is non-null, so the disclosure is accurate rather
|
||||
than a permanent disclaimer. See SECURITY §2 and UI-SPEC §4.
|
||||
|
||||
### Python 3.14 metadata deprecation (fixed)
|
||||
|
||||
@@ -268,13 +272,23 @@ detected-and-explained before v1.0.
|
||||
|
||||
---
|
||||
|
||||
## Open questions for the owner
|
||||
## Decisions
|
||||
|
||||
1. **Requires-Python divergence (SP-2).** pip refuses `scipy==1.7.3` on Python 3.12; uv plans it.
|
||||
Should PipDock enforce Requires-Python itself so the preview is engine-independent, or show
|
||||
each engine's own verdict?
|
||||
2. **`probe.py -I` (SP-6).** Which of the three options above?
|
||||
3. **Search ranking (SP-3).** Confirm that an exact/prefix boost over nucleo's score is in scope
|
||||
for M1 rather than deferred — the Search screen is unusable without it.
|
||||
4. **`PD-BLD-001` fixture (SP-2).** Capture on a clean VM, or ship a labelled synthetic fixture?
|
||||
`docs/TESTING.md` §2 requires a fixture per code before ship.
|
||||
**1. Requires-Python — DECIDED 2026-07-27: PipDock enforces it itself.** (SP-2: pip refuses
|
||||
`scipy==1.7.3` on Python 3.12; uv plans it.) The preview must not change shape because the user
|
||||
flipped the engine radio, so `crates/pipdock-core/src/compat.rs` screens every candidate against
|
||||
the environment's version before any engine command runs, and rejects surface as `PD-PKG-001` with
|
||||
the required range against the found version. Unparseable specifiers count as **compatible** —
|
||||
PipDock failing to read metadata must never be why an installable package is refused. See
|
||||
ARCHITECTURE §3, ERROR-CATALOG PD-PKG-001, DATA-FLOW §2.
|
||||
|
||||
**2. `probe.py -I` — DECIDED 2026-07-27: keep `-I`, disclose the gap.** See SP-6 above.
|
||||
|
||||
## Still open
|
||||
|
||||
1. **Search ranking (SP-3).** Confirm that an exact/prefix boost over nucleo's score is in scope
|
||||
for M1 rather than deferred — the Search screen is unusable without it (`requests-ntlm` ranks
|
||||
above `requests`).
|
||||
2. **`PD-BLD-001` fixture (SP-2).** Capture on a clean VM, or ship a labelled synthetic fixture?
|
||||
`docs/TESTING.md` §2 requires a fixture per code before ship. Same question for `PD-NET-002`,
|
||||
`PD-PRM-002`, `PD-SYS-001` and `PD-SYS-002`, none of which this machine can produce.
|
||||
@@ -32,6 +32,11 @@
|
||||
"copyLog": "Copy full log",
|
||||
"reportBug": "Report bug"
|
||||
},
|
||||
"env": {
|
||||
"partialListing": "Packages installed for your user account are not shown here.",
|
||||
"partialListingDetail": "PipDock reads this environment in isolated mode, which skips {{path}}. Virtual environments are unaffected.",
|
||||
"requiresPython": "Needs Python {{required}} — this environment is {{found}}."
|
||||
},
|
||||
"phase0": {
|
||||
"heading": "Phase 0 — scaffold",
|
||||
"body": "The shell, design tokens and locale catalogs are in place. Screens land in M2, after the Phase 0 spikes answer how each engine reports its dry-run plan.",
|
||||
|
||||
@@ -32,6 +32,11 @@
|
||||
"copyLog": "Sao chép toàn bộ nhật ký",
|
||||
"reportBug": "Báo lỗi"
|
||||
},
|
||||
"env": {
|
||||
"partialListing": "Các gói cài riêng cho tài khoản của bạn không hiển thị ở đây.",
|
||||
"partialListingDetail": "PipDock đọc môi trường này ở chế độ cách ly nên bỏ qua {{path}}. Môi trường ảo không bị ảnh hưởng.",
|
||||
"requiresPython": "Cần Python {{required}} — môi trường này là {{found}}."
|
||||
},
|
||||
"phase0": {
|
||||
"heading": "Giai đoạn 0 — dựng khung",
|
||||
"body": "Khung ứng dụng, design token và các catalog ngôn ngữ đã sẵn sàng. Các màn hình sẽ có ở M2, sau khi các spike của Giai đoạn 0 trả lời được cách từng engine báo cáo kế hoạch dry-run.",
|
||||
|
||||
Reference in new issue
Block a user