gh-85004: Add the printname parameter in os.readlink()

[serhiy-storchaka]

The print name is optional -- [MS-FSCC] only says that it SHOULD be set, and PowerShell's New-Item -ItemType Junction does not set one -- so the substitute name is returned for a link which has none. Converting the \??\ prefix to \\?\ is skipped for the print name, which is not in the NT namespace. On non-Windows platforms the parameter is ignored, as a POSIX symlink has only one target path.

• Issue: [os] readlink should support getting the target's printname in Windows #85004

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #34789240 | 📁 Comparing a4bd7a4 against main (998b890)

  🔍 Preview build  

402 files changed · + 9 added · ± 393 modified

+ Added

• builtins/constants.html
• builtins/exceptions.html
• builtins/functions.html
• builtins/index.html
• builtins/stdtypes.html
• builtins/threadsafety.html
• builtins/time-complexity.html
• library/time-complexity.html
• library/tkinter.dialogs.html

± Modified

• glossary.html
• index.html
• license.html
• py-modindex.html
• c-api/arg.html
• c-api/bool.html
• c-api/buffer.html
• c-api/bytearray.html
• c-api/bytes.html
• c-api/capsule.html
• and 383 more...

[zooba]

The change looks good to me overall - just want to throw out the possibility that a Boolean keyword argument might not be the best option here? Maybe some kind of enum or string literal would read nicer and leave us a better future option?

n = readlink(path, printname=True)
# or
n = readlink(path, kind="print") # or "target" or ...
# or
n = readlink(path, index=1) # defaults to 0, or maybe -1 to preserve current behaviors/errors

I don't know what variations of readlink currently exist, and the os module is meant to be low-level POSIX which would mean we could just add a new function if POSIX were to add a new one, but maybe there's some other variation that would make sense to let the caller choose?

Best example I can think of is that we chose not to support reading appexec aliases with this function, even though on Windows they're the same kind of thing (example code from PyManager). But those have a number of fields you would read out, so a single bool isn't a great field compared to the index or names (which we'd have to choose and hard code, since they're not in the data structure itself).

No big deal. printname is accurate enough for this one case, it just might be something we regret if there's a need to support more than one case.