Skip to content

rename() into an existing directory returns the directory for file:// paths #569

Open

Description

@adenzhou1350

On current main (827574045b1fecad52f7af3cfeeab3ecd9a0d0e8), FilePath.rename() moves a file inside an existing directory and returns the directory rather than the moved file. A plain local UPath rejects the same operation with FileExistsError on my Windows machine.

from pathlib import Path
from tempfile import TemporaryDirectory

from upath import UPath

with TemporaryDirectory() as directory:
    root = UPath(Path(directory).as_uri())
    source = root / 'source.txt'
    target = root / 'destination'
    source.write_text('payload')
    target.mkdir()

    returned = source.rename(target)
    print(type(source).__name__)                  # FilePath
    print(source.exists())                       # False
    print(returned == target, returned.is_dir())  # True True
    print((target / 'source.txt').read_text())     # payload

Environment: Windows, CPython 3.14.3, universal_pathlib built from the commit above (0.3.10.post2+g827574045), fsspec 2026.7.0. I also reproduced the directory-return behavior with MemoryPath on Windows. The exact script above also reproduces on isolated Linux CPython 3.12.10 with the same UPath commit and fsspec 2026.7.0. The five original core/registry/relative/local/memory test modules pass there (1,002 passed, 5 skipped, 1 original xfail); this is not full Nox or cloud-backend validation.

FilePath uses UPath.rename(), which calls fs.mv() and returns the requested target. The local backend uses shutil.move(), so an existing directory is interpreted as a container. Renaming to a fresh filename works and returns the moved file.

I saw the warning about nonstandard recursive/maxdepth arguments and the recommendation to use move() or move_into(). Is moving a file into an existing directory also intentional for rename()? I expected it to reject that target, matching pathlib, rather than move the file and return its parent. If this behavior is kept for compatibility, documenting this distinction would help.

Found during AI-assisted source review and independently reproduced through the public API. No backend implementation was mocked or extracted for execution.

Activity

  1. ap-- commented on Nov 10, 2026

    @ap--
    Collaborator

    Thanks for the detailed report and reproducer @adenzhou1350! 🙏

    This isn't intentional. UPath.rename() currently forwards to fsspec's mv(), which has
    cp/mv-like "move into an existing directory" semantics, and then returns the requested
    target rather than the actual destination. This differs from pathlib.Path.rename() in
    several cases:

    src → dst pathlib.Path (POSIX) UPath file:// / memory:// / s3://
    file → existing dir IsADirectoryError moved into dst, returns dst
    dir → existing dir replaces if empty, else OSError moved into dst
    dir → missing ✅ ✅ file://, ❌ memory:// raised, ❌ s3:// silently did nothing

    While investigating we found the last row: renaming directories raised on memory://
    and was a silent no-op on s3:// unless the deprecated recursive=True keyword was passed.
    That is fixed for the next release (0.3.11). Note that with fsspec>=2026.6.0 directory moves
    on object stores currently hit an upstream regression (link to fsspec issue).

    rename() already deviates from pathlib (the recursive/maxdepth keywords are
    deprecated), and we want to align it fully with pathlib.Path.rename() in a future
    release. Since changing the "move into an existing directory" behaviour could break code
    that relies on it, we'll do that with a deprecation period rather than in a patch release.

    In the meantime, if you want pathlib-like semantics today, use:

    • source.move(target): raises IsADirectoryError if target is an existing directory
    • source.move_into(target_dir): explicitly moves into an existing directory and returns
      the actual new path

    Keeping this issue open to track the alignment.

    xref: #575

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions