python / python/cpython

Documentation for os.environ should say that os.environ caching behavior is undefined if other threads are setting environment values

Open
#120,513 3 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

docs topic-free-threading
Dominant language
Python
Stars
77.2k
Forks
35.9k
PR merge metrics
PR metrics pending

Description

Documentation

It says here:

This mapping is captured the first time the os module is imported, typically during Python startup as part of processing site.py. Changes to the environment made after this time are not reflected in os.environ, except for changes made by modifying os.environ directly.

It should mention the caveat that such cashing would cause undefined behavior or/and crashes when other threads would be setting environment values. This would be true at least on Linux and FreeBSD.

The same should be mentioned in the documentation of the function that initializes the Python interpreter and caches environment.

These functions are not thread-safe.

Linked PRs
  • gh-152979

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Review the os.environ documentation linked in the issue and the documentation for the interpreter-initialization function that caches the environment. Compare the requested thread-safety caveat with linked PR gh-152979. Done means both relevant documentation areas accurately describe the behavior when other threads modify environment values.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation, operating-systems
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.