fix: windows drive letters remap to unc paths

[maxnbk]

Closes #2045 and #1438 .
Partial but not complete fix for #1909 (Intentional, I feel that the work that was occurring in the gitbash PR would ultimately resolve this behavior?) .

Explanations:

os.path.realpath on Python 3.8+ Windows silently expands mapped drive letters to their underlying UNC paths. Because canonical_path calls realpath, FileSystemPackageRepository was storing a UNC self.location even when the caller supplied a drive-letter path. This caused make_resource_handle, which does a raw string comparison, to raise ResourceError on every drive-letter handle against a UNC-stored repository.

The fix:

On Windows, canonical_path now uses os.path.abspath instead of os.path.realpath. This preserves path style (drive-letter stays drive-letter, UNC stays UNC) and restores the pre-3.8 normalization behavior without a network-resolution side-effect. A make_resource_handle override is also added to the filesystem plugin to handle residual case or separator mismatches via canonical_path.

Extension of work:

A resolve_links_on_windows config flag (default False) has been added for sites that need some form of symlink/junction resolution on Windows. When enabled, a purpose-built _windows_realpath walks components of the path using os.readlink, resolving real symlinks without actually touching the drive root, in order to avoid the UNC-expansion side-effect entirely. Long-path support (\\?\ prefix handling) is included, with the relevant test skipped on hosts that do not have LongPathsEnabled=1 in the registry. Note: I'm aware that we need to move off of the winreg module, but since we have it for now, might as well use it.

Testing:

This was tested against an actual Drive-letter-map-with-matching-UNC-network-share .

==== EDIT ====

This PR has been extended with a broader real_path migration.

real_path() helper - A new utility function in filesystem.py that replaces os.path.realpath at all call sites where path-style stability is required.
On Windows, it is delegated to os.path.abspath to preserve the drive-letter style.
On all other platforms, it is delegated to os.path.realpath to preserve symlink resolution.
Importantly, no config-flag is required - the correct behavior is derived from the OS, not user preference. canonical_path from the original PR slice now calls real_path internally.

Call-site migration - All non-test os.path.realpath code that touched stored, serialized, or compared paths have been updated:

• filesystem.py - canonical_path, is_subdirectory
• resolved_context.py - _adjust_variant_for_bundling
• serialise.py - open_file_for_write, load_from_file
• suite.py - Suite.save, Suite.load
• system.py - rez_bin_path
• rezplugins/build_system/cmake.py - also corrects a pre-existing dead-code bug (os.path.abspath used as a truthiness check where os.path.isabs was intended)
• utils/py_dist.py - egg-to-rez file path comparisons and copy destinations

Relationship to prior work - Several earlier attempts addressed this problem class but were either incomplete/partial, lacked tests, or relied on opt-in config flags:

• Fix repo location false mismatch #957 - first fix for the make_resource_handle location mismatch; was reverted. This PR restores the intent of that fix.
• Add new use_canonical_path option in rezconfig.py #1543 - introduced use_canonical_path config flag (default True); only patched FileSystemPackageRepository.init and required users to opt out. Superseded by this work.
• fix: realpath on windows changed behavior in python 3.8 to expand mapped drive letters to their UNC path names #1856 - introduced a real_path helper gated on a windows_unc_path config flag; covered three call sites (canonical_path, _adjust_variant_for_bundling, rez_bin_path). The approach here is the same in spirit but unconditional and covers all remaining call sites. Superseded by this work.

==== END EDIT ====

==== EDIT 2 (2026-07-17) ====

This PR has been further extended with two enhancements to _windows_realpath (the opt-in resolve_links_on_windows code path):

Intermediate-directory symlink re-walk - The original component walk resolved symlinks only on the final path component. If an intermediate directory was itself a symlink (e.g., /a/b/target where /a → /x), the intermediate symlink was not resolved. The walk has been converted from a linear for loop to a component-stack while loop: when a symlink resolves to an absolute target, the target's components are pushed back onto the front of the stack so that any symlinks in the target's prefix are re-walked transitively. A total_depth budget of 40 hops guards against symlink loops (the same limit os.path.realpath uses) and is enforced at both the inner resolution loop and the re-walk point.

Junction detection on Python 3.8–3.11 - os.path.islink() does not detect Windows junctions (mount points) on any Python version; it checks IO_REPARSE_TAG_SYMLINK only. os.path.isjunction() was added in Python 3.12 but is unavailable on 3.8–3.11, which rez still supports. A _is_link_or_junction helper now provides three-tier detection: os.path.islink → os.path.isjunction (3.12+) -> st_reparse_tag == 0xA0000003 fallback (the IO_REPARSE_TAG_MOUNT_POINT value from the Windows SDK, exposed via os.lstat().st_reparse_tag on Python 3.8+). This allows _windows_realpath to resolve junctions via os.readlink on all supported Python versions. Note: os.readlink on a junction returns the substitute name with a \??\ device-namespace prefix, which CPython internally converts to \\?\ - the existing extended-length prefix stripping handles this correctly.

==== END EDIT 2 ====

==== EDIT 3 2026-07-29 ====

Three rounds of adversarial self-review were performed against the branch, with findings verified against the codebase. Many valid findings were addressed, and some deliberate non-fixes are documented below with rationale.

Addressed:

• serialize.py file_cache key mismatch. open_file_for_write used os-path.realpath(real_path(filepath)) for the cache key, which on Windows expands driver letters to UNC. load_from_fileusedreal_path(filepath), preserving the drive letter. Write stored under\server\share\foo.py, while read looked it up as N:\foo.py, creating a cache miss. Fixed by usingreal_pathfor the cache key (matching the read side) andresolve_path` separately for the physical write target.
• Suite.save() re-introduced UNC expansion. os.path.realpath(path) was used before safe_rmtree, expanding N:\suites\mysuiteto\nas\studio\stuites\mysuite. Replaced with a new resolve_path()` function (see below).
• test_save_through_symlink_uses_samefile would fail on Windows CI. On Windows default config, resolve_path returns abspath (no symlink resolution), so rmtree_arg would be the unresolved alias path. Fixed by mocking rez.suite.resolve_path to return the symlink target, so the test verifies rmtree-call-wiring identically on all platforms.
• _add_extended_length_prefix didn't guard against already-prefixed paths. Calling it on \\?\C:\foo would produce \\?UNC\?\C:\foo. Added a case-sensitive already-prefixed guard.
• samefile fallback did filesystem IO on every mismatch. A 50-package resolve with legacy UNC handle would do 150 network stats. Added class-level _location_aliases memoization on FileSystemPackageRepository. The first mismatch still hits, but subsequent lookups for the same path-pair are fast.
• To the above, stale False results in the memoization cache. Only True results are cached. A False (genuine mismatch) is re-checked every time, so a repo moved away and back in the same process is detected correctly.
• Useless test assertion: os.path.islink(alias) was always True (the test created the symlink), so the or short-circuited. Replaced with an assertNotIn("alias_suite", rmtree_arg) / assertIn("actual_suite", rmtree_arg).
• resolve_path imported locally inside open_file_for_write. Moved to module-level alongside real_path.
• Misleading Suite.save() comment, claiming that symlink resolution happens, but on Windows default config, it doesn't. Updated to accurately describe the Windows default-config behavior.

New function: resolve_path()

• This was added to utils.filesystem.py to fill the gap between real_path (no symlink resolution) and os.path.realpath (UNC expansion on Windows). This resolves symlinks in a form-preserving way. It uses _windows_realpath when resolve_links_on_windows is configured true, otherwise abspath. Used by serialize.py (write target) and suite.py (rmtree target).

Identified but not addressed:

• is_subdirectory / relpath case inconsistency: is_subdirectory now canonicalizes (lowercases on Windows), but the subsequent os.path.relpath in _adjust_variant_for_bundling uses real_path (preserves case). If paths differ only in case, is_subdirectory returns True but relpath could produce a different result. Rationale: Same-case is the norm in practice. The inconsistency only manifests with mixed-case paths that are otherwise identical. Not worth the complexity of threading canonical paths through relpath at this time. Recommend addressing only if a real-world case mismatch is reported.
• Windows default config behavior with resolve_path does not resolve symlinks. When resolve_links_on_windows=False (default), resolve_path returns abspath (no symlink resolution). This means Suite.save() through a symlink alias will sever the symlink, and _windows_realpath long-path probe prefixing only helps when the flag is enabled. Rationale: This is the inherent tradeoff of the opt-in flag design. The alternative, always resolving symlinks on Windows, is exactly the behavior os.path.realpath provides, which this PR exists to avoid. The comment in Suite.save() now accurately documents this. Recommend leaving as-is. Users who need symlink resolution on Windows should enable the resolve_links_on_windows flag, and after this behavior is proven out, the flag could be removed and behavior defaulted-on. Documented in the config-setting comment.
• probe vs candidate asymmetry for long paths. probe is prefixed for filesystem IO. candidate, used for os.path.join and os.path.dirname, is not. Rationale: os.path.join and dirname are pure string operations with no filesystem access, so the unprefixed candidate works fine. No current code does filesystem IO on candidate directly. Recommend leaving as-is. If future code adds filesystem IO on candidate, prefix it at that point.
• make_resource_handle can't bridge drive-letter <-> UNC paths. The override canonicalizes via canonical_path, which preserves form. A drive-letter N:\Packages and UNC \\nas\studio\Packages canonicalize to different strings. Rationale: get_resource_from_handle (the resolution side) has the same samefile fallback that covers this. Handle creation is less critical. If the handle is created in the wrong form, the fallback catches it on resolution. Recommend leaving as acceptable for now. If handle-creation mismatches become a problem, add a samefile check to make_resource_handle as well.

New behaviors have reasonably comprehensive test coverage, and some test fixes are genuine test fixes for previous behavior that was effectively self-asserting.

==== END EDIT 3 ====

Disclosure:

This PR was AI-assisted with Claude Code, Sonnet 4.6, primarily for diagnostics, logic-tracing, documentation and edge-case verification.

This PR was AI-assisted with GLM-5.2, primarily for python-version-specific research and edge-case detection.

[codecov]

Codecov Report

❌ Patch coverage is 81.81818% with 26 lines in your changes missing coverage. Please review.
✅ Project coverage is 61.46%. Comparing base (3a50d1b) to head (30f9a41).
⚠️ Report is 6 commits behind head on main.

Files with missing lines	Patch %	Lines
src/rez/utils/filesystem.py	90.42%	5 Missing and 4 partials ⚠️
src/rezplugins/package_repository/filesystem.py	57.14%	4 Missing and 5 partials ⚠️
src/rez/utils/py_dist.py	0.00%	4 Missing ⚠️
src/rezplugins/build_system/cmake.py	33.33%	1 Missing and 1 partial ⚠️
src/rez/rezconfig.py	0.00%	1 Missing ⚠️
src/rez/suite.py	91.66%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2104      +/-   ##
==========================================
+ Coverage   61.29%   61.46%   +0.16%     
==========================================
  Files         164      164              
  Lines       20568    20692     +124     
  Branches     3575     3605      +30     
==========================================
+ Hits        12607    12718     +111     
- Misses       7089     7092       +3     
- Partials      872      882      +10     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[JeanChristopheMorinPerso]

@maxnbk What's the relationship to #1856?

During the TSC, @instinct-vfx said that the expected default behavior is that the style should stay consistent based on how the repo was configured?

[cfxegbert]

Can you please look at #1856. There are a few other places that realpath needs to be replaced.

[maxnbk]

I'll take a look and see what else needs resolving. I may have to add some more tests to find all the edge-cases. Goal is to incorporate all solutions from all mismatched PRs, as I think there were approximately 3 all trying to solve the same problem with partial/incomplete solutions, and nobody got all corners.

Evidently that extends to me, so I'll re-evaluate and see what I need to do to extend.
Might be this weekend though. :)

[cfxegbert]

@JeanChristopheMorinPerso Looks like this didn't get merged into the 3.4.0. What can we do to get this out there?

[JeanChristopheMorinPerso]

Hey @cfxegbert, this was intentional. We had a few more questions to answer and decided to push this to a follow up release. We are planning to do a 3.4.1 release soon-ish to get this PR out.

When I reviewed the PR, I noticed that os.path.islink doesn't do what we thought it would on windows. At least I think.

[herronelou]

adding comment here too for visibility, but we've been running rez 3.3 with a patch of #1856 in production since January and that has solved the issues we'd been having since changing python versions.