Improve toolchain and environment missing error messages #4596

zanieb · 2024-06-27T18:25:57Z

The journey here can be seen in:

I collapsed all the commits here because only the last one in the stack got us to a "correct" error message.

There are a few architectural changes:

We have a dedicated MissingEnvironment and EnvironmentNotFound type for PythonEnvironment::find allowing different error messages when searching for environments
ToolchainNotFound becomes a struct with the ToolchainRequest which greatly simplifies missing toolchain error formatting
ToolchainNotFound tracks the EnvironmentPreference so it can accurately report the locations checked

The messages look like this now, instead of the bland (and often incorrect): "No Python interpreter found in system toolchains".

❯ cargo run -q -- pip sync requirements.txt
error: No virtual environment found
❯ UV_TEST_PYTHON_PATH="" cargo run -q -- pip sync requirements.txt --system
error: No system environment found
❯ UV_TEST_PYTHON_PATH="" cargo run -q -- pip sync requirements.txt --python 3.12
error: No virtual environment found for Python 3.12
❯ UV_TEST_PYTHON_PATH="" cargo run -q -- pip sync requirements.txt --python 3.12 --system
error: No system environment found for Python 3.12
❯ UV_TEST_PYTHON_PATH="" cargo run -q -- toolchain find 3.12 --preview
error: No toolchain found for Python 3.12 in system path
❯ UV_TEST_PYTHON_PATH="" cargo run -q -- pip compile requirements.in
error: No toolchain found in virtual environments or system path

I'd like to follow this with hints, suggesting creating an environment or using system in some cases.

zanieb · 2024-06-27T18:33:27Z

crates/uv-toolchain/src/discovery.rs

 #[derive(Clone, Debug, Error)]
-pub enum ToolchainNotFound {


The enum is now a struct which contains the ToolchainRequest instead of de-structuring the request here.

zanieb · 2024-06-27T18:34:31Z

crates/uv-toolchain/src/discovery.rs

-    /// The requested directory path does not exist.
-    DirectoryNotFound(PathBuf),
-    /// No Python executables could be found in the requested directory.
-    ExecutableNotFoundInDirectory(PathBuf, PathBuf),


We lose the ability to distinguish between these cases in error messages, but I don't think it's particularly critical.

By "these cases", do you mean file vs. directory vs. executable?

Specifically whether its a missing directory or a missing executable in the directory. We'll always raise the latter now.

It would also be harder to encode things like "this exists but is not an executable" in the future. In practice, I don't think we were even using the variant right now.

charliermarsh · 2024-06-27T21:32:20Z

crates/uv/tests/venv.rs

@@ -264,7 +264,7 @@ fn create_venv_unknown_python_minor() {
        ----- stdout -----

        ----- stderr -----
-          × No interpreter found for Python 3.100 in system toolchains
+          × No toolchain found for Python 3.100 in system path or `py` launcher


What are your thoughts on "toolchain" as user-facing copy vs. interpreter? I feel like interpreter is more familiar to folks but seeing that you proactively changed it here.

I'm not sure, but I'd like to be consistent. We're going to talk about managed toolchains a lot going forward so I think we might want to move in that direction.

A nuance is that we look for an interpreter in order to discover a toolchain. I guess that leans towards using "interpreter" here.

I weakly prefer interpreter I think. It seems likely to land better with Python users. But the inconsistency with using "toolchain" in written docs does seem unfortunate. How crazy would it be to switch to "interpreter" everywhere?

Well.. I talked about that in the initial design and @konstin did clarify that there's much more than the interpreter involved e.g. the managed toolchains include the standard library.

For this change, I'll use "interpreter" because I want to get these changes out asap.

Ah yeah I hear ya. If y'all already dug into the naming here then I defer to you. :)

I have yet to be convinced that "toolchain" is the best user-facing concept :) we should all chat more.

charliermarsh · 2024-06-27T21:36:15Z

crates/uv-toolchain/src/discovery.rs

+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        let sources = match self.environment_preference {
+            EnvironmentPreference::Any => {
+                format!("virtual environments or {}", self.toolchain_preference)


Would this be "virtual environments or managed or system toolchains"? I feel like it should be Oxford comma'd but I know that's tedious...

😬 I know right. I considered doing an extra match to fix this.... but I didn't have it in me. Think it's worth it? I might want to construct a test covering this so I know it matters if I do it.

charliermarsh

So the basic idea here is that rather than creating a ToolchainNotFound variant, we base the error message on the request itself? Makes sense to me.

What ToolchainRequest was being returned such that I saw that "error: No Python interpreters found in system toolchains" message in my ruff-lsp PR?

zanieb · 2024-06-27T21:43:22Z

So the basic idea here is that rather than creating a ToolchainNotFound variant, we base the error message on the request itself? Makes sense to me.

Yep, though that kind of just fell out of me making some other changes to actually propagate the information for correct error messages.

What ToolchainRequest was being returned such that I saw that "error: No Python interpreters found in system toolchains" message in my ruff-lsp PR?

This was because the ToolchainNotFound didn't track EnvironmentPreference so when constructing the error message we only had the ToolchainPreference and did something dumb. In your case, it was probably ToolchainRequest::Any, EnvironmentPreference::ExplicitSystem, and ToolchainPreference::OnlySystem (because we don't allow mutation of managed toolchains).

BurntSushi · 2024-06-28T12:08:55Z

crates/uv/tests/venv.rs

@@ -264,7 +264,7 @@ fn create_venv_unknown_python_minor() {
        ----- stdout -----

        ----- stderr -----
-          × No interpreter found for Python 3.100 in system toolchains
+          × No toolchain found for Python 3.100 in system path or `py` launcher


I weakly prefer interpreter I think. It seems likely to land better with Python users. But the inconsistency with using "toolchain" in written docs does seem unfortunate. How crazy would it be to switch to "interpreter" everywhere?

zanieb added the error messages Messaging when something goes wrong label Jun 27, 2024

zanieb force-pushed the zb/toolchain-errors branch from c45acd8 to 8e56c42 Compare June 27, 2024 18:32

zanieb commented Jun 27, 2024

View reviewed changes

zanieb marked this pull request as ready for review June 27, 2024 18:40

zanieb force-pushed the zb/toolchain-errors branch 2 times, most recently from 24c9f0d to 1e84c62 Compare June 27, 2024 18:49

zanieb requested a review from charliermarsh June 27, 2024 19:02

zanieb force-pushed the zb/toolchain-errors branch from 1e84c62 to d78ba43 Compare June 27, 2024 19:03

zanieb requested a review from BurntSushi June 27, 2024 19:03

zanieb force-pushed the zb/toolchain-errors branch from d78ba43 to 6183da7 Compare June 27, 2024 21:18

charliermarsh reviewed Jun 27, 2024

View reviewed changes

charliermarsh approved these changes Jun 27, 2024

View reviewed changes

konstin approved these changes Jun 28, 2024

View reviewed changes

BurntSushi approved these changes Jun 28, 2024

View reviewed changes

zanieb force-pushed the zb/toolchain-errors branch from 6183da7 to b1893d9 Compare June 28, 2024 15:00

Improve toolchain and environment missing error messages

42479bd

zanieb force-pushed the zb/toolchain-errors branch from b1893d9 to 42479bd Compare June 28, 2024 15:10

zanieb enabled auto-merge (squash) June 28, 2024 15:10

zanieb merged commit 3a62ba3 into main Jun 28, 2024
47 checks passed

zanieb deleted the zb/toolchain-errors branch June 28, 2024 15:17

zanieb mentioned this pull request Jun 28, 2024

Bad experience: Mac, python from brew, pip install uv #4624

Closed

BrewTestBot mentioned this pull request Jun 29, 2024

uv 0.2.18 Homebrew/homebrew-core#175964

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve toolchain and environment missing error messages #4596

Improve toolchain and environment missing error messages #4596

zanieb commented Jun 27, 2024 •

edited

Loading

zanieb Jun 27, 2024

zanieb Jun 27, 2024

charliermarsh Jun 27, 2024

zanieb Jun 27, 2024

zanieb Jun 27, 2024

charliermarsh Jun 27, 2024

zanieb Jun 27, 2024

BurntSushi Jun 28, 2024

zanieb Jun 28, 2024

zanieb Jun 28, 2024

BurntSushi Jun 28, 2024

zanieb Jun 28, 2024

charliermarsh Jun 27, 2024

zanieb Jun 27, 2024

charliermarsh left a comment

zanieb commented Jun 27, 2024 •

edited

Loading

BurntSushi Jun 28, 2024

Improve toolchain and environment missing error messages #4596

Improve toolchain and environment missing error messages #4596

Conversation

zanieb commented Jun 27, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

charliermarsh left a comment

Choose a reason for hiding this comment

zanieb commented Jun 27, 2024 • edited Loading

Choose a reason for hiding this comment

zanieb commented Jun 27, 2024 •

edited

Loading

zanieb commented Jun 27, 2024 •

edited

Loading