Feature or enhancement

Proposal:

(flagging as a feature, since it isn't really a bug report, just revisiting an API design detail for 3.15 where we had to make a design decision with less time for consideration than we might have wished)

The initial PEP 829 implementation relies on hidden global state in site.py to allow deferring site directory processing until several directories have been added:

known_paths = sys.path[:]
for dir_to_add in site_dirs_to_add:
    site.addsitedir(dir_to_add, known_paths, defer_processing_start_files=True)
site.process_startup_files()  # Defined, but not covered in the API docs yet

The hidden global state is a mixed blessing, as it means we can transparently make any site.addsitedir calls participate in a currently active batch (as was done to resolve #149504), but also makes the management and documentation of that hidden state a bit finicky.

With a slight tweak to the implementation of site._StartupState to also cover the known_paths functionality, the batch processing API could instead look like:

site_batch = site.StartupState(sys.path)
for dir_to_add in site_dirs_to_add:
    site.addsitedir(dir_to_add, startup_state=site_batch)
site_batch.process()

(passing both known_paths and startup_state would be an error)

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Links to previous discussion of this feature:

The previous discussion was in the initial PEP 829 PR, where we settled for the boolean option in the public API because it was the simplest way to solve the problem before the beta 1 implementation deadline.

The fix for #149504 has subsequently done most of the work needed to enable switching the public API over to a state object rather than the boolean flag.