Add os.reload_environ() function

[vstinner]

Feature or enhancement

When the environment is modified outside Python, os.environ is not updated. I propose adding a new os.environ.refresh() method to manually update os.environ.

Discussion: https://discuss.python.org/t/method-to-refresh-os-environ/54774

Linked PRs

• gh-120057: Add os.environ.refresh() method #120059
• gh-120057: Add os.get_user_default_environ() function #120494
• Revert "gh-120057: Add os.environ.refresh() method (#120059)" #120789
• Revert "gh-120057: Add os.environ.refresh() method (#120059)" #120790
• gh-120057: Rename os.environ.refresh() to invalidate_cache() #120808
• gh-120057: Add os.reload_environ() function #126268

[eryksun]

Note that on Windows the C runtime's Unicode and multibyte environments -- _wenviron and _environ -- can get out of sync with the process environment -- GetEnvironmentStringsW() -- due to code that directly calls WinAPI SetEnvironmentVariableW(). It's possible to implement a function to fresh the C environment on Windows, which unsets the variables in _wenviron and sets the variables from GetEnvironmentStringsW(), but that's probably not something that the Python runtime needs to worry about.

[vstinner]

but that's probably not something that the Python runtime needs to worry about

As soon as there are different "caches", it's hard to keep everything in sync and consistent :-(

[erlend-aasland]

I'm not sure if this is a good idea. I suspect it will be a hard feature to get right, and as noted in the forum discussion, most beginners will misunderstand the feature.

[vstinner]

I suspect it will be a hard feature to get right

Would you mind to elaborate?

[vstinner]

and as noted in the forum discussion, most beginners will misunderstand the feature.

I added "in the same process" to reduce misunderstanding.

[picnixz]

FYI, there was this issue: #119737 (so you may want to close it to avoid duplicates)

[vstinner]

I closed issue #119737 as a duplicate of this issue.

[vstinner]

Implemented by the commit 7aff2de.

[WolfDWyc]

@vstinner

As I noted in the discourse thread, and was mentioned in the comment on the PR, I still feel like this name will be confusing for new users, even with docs clarifying it. Can we maybe re-discuss this? Or at least choose another name?

Should we continue here or in the discourse thread?

[WolfDWyc]

I've elaborated on this concern here: https://discuss.python.org/t/method-to-refresh-os-environ/54774/24

[picnixz]

Since we had a bunch of closed PRs, should this issue be closed for now? or are there other pending discussions?

[serhiy-storchaka]

There was other ongoing discussion: https://discuss.python.org/t/bikeshedding-a-method-to-refresh-os-environ/57628/22

I think that @ncoghlan's idea about a module level os.reload_environment() function addresses most of concerns about os.environ.refresh(). But the discussion did not stop here, so not all see it so.

Somebody need to put a period here. Either reimplement this feature as a module level function, or keep all as is, -- these are two most probable options.

[vstinner]

Python 3.14 alpha 1 was released with os.environ.refresh() method. What's the status of this issue?

[erlend-aasland]

Python 3.14 alpha 1 was released with os.environ.refresh() method. What's the status of this issue?

You tell me; you created the issue :)

[vstinner]

I closed the issue, I'm not the one who reopened it.

[vstinner]

@serhiy-storchaka: What's the status of this issue?

[serhiy-storchaka]

You should ask @zooba, the author of the discussion. According to the results of the poll, the majority prefers a module level function. Voting is not binding, and not only core developers voted, but this should still be taken into account. I do not see a vote of @zooba. Is he satisfied with proposed variants and what does he propose?

[vstinner]

@zooba: What's the status of this issue?

[vstinner]

I would suggest to close the issue and keep the os.environ.refresh() method.

[WolfDWyc]

I think if reload_environment is preferred by more people we should go with that.

[zooba]

I posted on the discussion, but the majority liked the module-level function instead of putting it on the object, and I personally think reload_environ() is slightly more accurate than reload_environment(), since it is environ that is being reloaded. (There was no poll option for other module-level functions, so I'm assuming people liked os.reload... and disliked os.environ.....)

So as much as anyone wants to keep me happy, os.reload_environ() is probably the best option. Documentation will have to deal with people who read the name and misunderstand what it's for, but that is basically documentation's job.

[serhiy-storchaka]

On other hand, it reloads the process environment to the os.environ and os.environb mappings.

[ncoghlan]

I think @zooba's point was that this function doesn't reload the system wide environment variable settings into the running application process, which os.reload_environment() could be taken to mean.

That misreading doesn't seem particularly likely to me though, and the fact this operation reloads both os.environ and os.environb (not just os.environ) makes me wary of the shorter os.reload_environ() name (it feels misleading to me in the same way that the os.environ.refresh() spelling is misleading).

[zooba]

I can't reasonably see os.reload_environ() implying that os.environb wouldn't also be reloaded. Certainly not as much as I can see someone thinking that os.reload_environment() implies something other than "os.environ will be reloaded".

Whereas os.environ.refresh() could quite reasonably be assumed to have no impact on os.environb. So I think that's another argument in favour of the module-level function.

Perhaps os.reload_environs() feels more comfortable for covering both os.environ and os.environb? I don't have a strong preference about the s. My main concern is still the same as at the start - this function doesn't impact the (generic) environment of the process at all, it only affects what is contained in Python's cache of the environment, otherwise known as os.environ.

[vstinner]

I created PR gh-126268 to replace the os.environ.refresh() method with a new os.reload_environ() function.

IMO reload_environ() is a good name since it reminds os.environ. I don't think that we should bother with the fact that os.environb is also reloaded to name the function. And reload_environment() is too long :-)

[vstinner]

I created PR #126268 to replace the os.environ.refresh() method with a new os.reload_environ() function.

Done: I merged the PR. I close the issue.