gh-125873: Improve error message when PYTHONHOME is invalid

[refeed]

• Issue: Show a better error message when PYTHONHOME is wrong #125873

[cpython-cla-bot]

All commit authors signed the Contributor License Agreement.

[bedevere-app]

Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool.

If this change has little impact on Python users, wait for a maintainer to apply the skip news label instead.

[bedevere-app]

Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool.

If this change has little impact on Python users, wait for a maintainer to apply the skip news label instead.

[ZeroIntensity]

This is user-facing, so it needs a NEWS entry. Something like "Improved error message when PYTHONHOME is invalid" should work.

[refeed]

Hi @ZeroIntensity , thanks for that! Just added it through the heroku blurb, please let me know if there's something I need to do, thanks

[ZeroIntensity]

Thank you! It's good to see new contributors :)

[skirpichev]

I doubt that we need a special treatment just for one environment variable. Same error happens if you wrongly override other PYTHON* variables.

[skirpichev]

@refeed, please avoid rebase/force-pushes/etc next time. Just add new commits while your pr being reviewed.

[konstin]

Can we tell the user what the (wrong) value of PYTHONHOME is?

[ZeroIntensity]

We could, but that significantly complicates things, because the error message has to get put on the heap (PyStatus can't do that, AFAIK). There's also a chance it's unset in the case of embedding.

[ZeroIntensity]

Eh, I disagree. I've encountered this error myself, it's common when embedding the interpreter because if PYTHONHOME is unset this error comes up. I'm happy to make this more general though (maybe instead of specifying PYTHONHOME we could just point to the env var docs).

[refeed]

Alright, for the env link can I use this: https://docs.python.org/3/using/cmdline.html#environment-variables ?

I'm thinking that the final error message will be:

Failed to import encodings module. Are you sure PYTHONHOME or other variable is correct? Docs on environment variables can be found here: https://docs.python.org/3/using/cmdline.html#environment-variables

I think we still have to mention the PYTHONHOME there because for most cases, I think the culprit is going to be the PYTHONHOME

What do you think?

[ZeroIntensity]

If we're going to go the route of casing this for all invalid variables (I'm not fully convinced, but let's go with it for now), then I don't think actually putting a link to the docs is the right way to do it. We should sort of hint where to look in the docs, something like this should work:

Failed to import encodings module. Your environment probably has misconfigured variables!

There's some contention about what should happen here. I'm dismissing my review until that gets solved.

[ZeroIntensity]

@skirpichev This is a more extensive message now, do you like this better?

[skirpichev]

Yes, looks better. Perhaps we could add some reference to --help-env, that will list such variables?

[refeed]

Alright, how about this?

Failed to import encodings module. Your environment probably has misconfigured variables! Please refer to `--help-env`

[konstin]

I believe mentioning PYTHONHOME explicitly is important, see the examples in #125873. As a user, the error message links me to --help-env, but then --help-env doesn't provide any guidance on how to fix the problem nor does it mention the import error i just encountered.

[refeed]

Alright, how about this?

Failed to import encodings module. Your environment probably has misconfigured variables! Please check PYTHONHOME otherwise refer to `--help-env`