gh-149473: Emit audit event on calling os.environ.clear()

[vstinner]

• Issue: os.environ.clear() (via posix._clearenv) bypasses os.unsetenv audit hooks (PEP 578) #149473

[vstinner]

cc @picnixz

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #32670664 | 📁 Comparing f86414a against main (94df625)

  🔍 Preview build  

3 files changed

± library/audit_events.html
± library/os.html
± whatsnew/changelog.html

[picnixz]

The event is only emitted if we use the C implementation right? Otherwise os.environ.clear() is implemented in pure Python. I don't know if you want to update the Python implementation as well though.

[vstinner]

If os._clearenv() is not available, os.environ.clear() emits one audit event os.unsetenv per removed variable. Example:

import os, sys

os.environ.clear()
os.environ['key1'] = 'value1'
os.environ['key2'] = 'value2'

def hook(*args):
    print("audit:", args)
sys.addaudithook(hook)
os.environ.clear()

Output with os._clearenv() and this change:

audit: ('os._clearenv', ())

Output without os._clearenv():

audit: ('os.unsetenv', (b'key1',))
audit: ('os.unsetenv', (b'key2',))

[picnixz]

I think this should be explicitly documented actually. With the new docs, I think people could expect os.environ.clear() to emit _clearenv unconditionally. I also see that we say that unsetenv is called whenever we call os.environ.clear() but that's not entirely accurate either.