fix(utils): ln() creates the link at dest pointing to src

AP
5d ago
+96-10

All Submissions:

  • Have you followed the guidelines stated in CONTRIBUTING.md file?
  • Have you checked to ensure there aren't any other open Pull Requests for the desired changed?

Type of change

  • Bug fix (non-breaking change which fixes an issue)

Description

path_ops.ln(src, dest) documents standard ln -s semantics (a link at dest pointing at src — the docstring, the dest.exists() guard, and the rm(dest) call all assume it), but the implementation called src.symlink_to(dest), which creates the link at src pointing to dest — the inverse:

  • dest is left untouched; src is replaced by a link that points at dest — and for directory sources dest is rm'd first, so the link is dangling from the moment it is created.
  • overwrite=True never worked for file destinations: dest was only removed for directories, so dest.symlink_to(...) raised FileExistsError.

No internal callers exist (verified by search), so the behavior change only affects direct users of the public helper — for whom the current behavior could never have worked as documented.

Fix

Create the link at dest pointing to src, and remove an existing destination (when overwrite=True) for files as well as directories.

Tests

5 new tests in tests/units/utils/test_path_ops.py (the function had none): link created at dest resolving to src for files and directories, refusal without overwrite leaving the destination intact, overwrite replacing the destination, and the same-path refusal. On main, 3 of the 5 fail (inverted link, FileExistsError on overwrite); with the fix they pass on symlink-capable platforms (Linux CI). ruff and pyright clean.

Changes To Core Features:

  • Have you added an explanation of what your changes do and why you'd like us to include them?
  • Have you written new tests for your core changes, as applicable?
  • Have you successfully ran tests with your changes locally?

After these steps, you're ready to open a pull request.

a. Descriptive title above.
b. Description above.
c. No linked issue — self-found via code inspection.