FilePath returns incorrect name and parts for relative paths (first character missing)

[hburrichter]

Bug summary

Using FilePath with a relative path strips the first character of the filename in name and parts.

Reproduction

from upath.implementations.local import FilePath
from upath import UPath

fp = FilePath("relative/path.zip")
print(fp.name)   # actual: "ath.zip"
print(fp.parts)  # actual: ("/", "relative", "ath.zip")

up = UPath("relative/path.zip")
print(up.name)   # actual: "path.zip"
print(up.parts)  # actual: ("relative", "path.zip")

Expected

FilePath("relative/path.zip").name   == "path.zip"
FilePath("relative/path.zip").parts  == ("relative", "path.zip")

All relative paths affected

Path	Expected .name	Actual .name
a/b.txt	b.txt	.txt
./relative/path.zip	path.zip	ath.zip
../parent/file.txt	file.txt	ile.txt
single.txt	single.txt	ingle.txt
deep/nested/path/file.doc	file.doc	ile.doc

Exactly 1 character is always truncated from the filename.

Notes / hypothesis

I believe the issue is in WrappedFileSystemFlavour.split() (upath/_flavour.py).
For relative paths, parent() returns a head with a leading / while stripped_path does not, leading to an off-by-one when slicing the tail.

Example debug:

head = "/relative"            # len = 9
stripped_path = "relative/path.zip"
tail = stripped_path[len(head) + 1:]  # "ath.zip"

Environment

• universal-pathlib: 0.3.8
• Python: 3.12
• OS: macOS (likely affects Linux too)

Related

• PR Fix behaviour of UPath.parent and UPath.parents #529 (anchor handling changes in split())
• Issue .parents returns an empty path as the last element #525 (parent/parts issues)

[ap--]

Thanks for reporting.

There definitely seems to be a regression.

currently FilePath() instantiation via a relative path string should either error or return an absolute path, with the latter being besst aligned to fsspec behavior.

Only PosixUPath and WindowsUPath support instantiation with relative paths directly.
All other fsspec backed UPath subclasses need to go via explicitly defining a root via relative_to().

this is mostly because paths are absolute in fsspec.

relates to #142

Could you bisect to the exact commit that caused the regression? (or is that exactly what you did?)

[hburrichter]

Thanks for the quick response!

I ran a git bisect between 0.2.6 and 0.3.8. The first bad commit is:

Commit: ed559a0d59c18c98f1a69706dd98ab5300c3f9d6
PR: #346 - "wip: start implementing chain functionality"
Author: @ap--
Date: September 5, 2025

The commit before (ba1bd48) returns correct results:

FilePath("relative/path.zip").name  # "path.zip" ✓

The first bad commit (ed559a0) returns incorrect results:

FilePath("relative/path.zip").name  # "ath.zip" ✗
FilePath("relative/path.zip").parts  # ('/', 'relative', 'ath.zip') ✗

The chain functionality refactoring appears to have affected the path parsing logic in a way that breaks relative paths - treating them as absolute (note the leading / in parts) and dropping the first character of the filename.

In the meantime, we're working around this by patching WrappedFileSystemFlavour.split() to use os.path.split() for local filesystems, which handles relative paths correctly.

[ap--]

Thanks!

In the meantime, we're working around this by patching WrappedFileSystemFlavour.split() to use os.path.split() for local filesystems, which handles relative paths correctly.

It would be extremely valuable to understand why you're using FilePath directly with relative paths. The fsspec LocalFileSystem works with absolute paths, and for relative paths automatically resolves them from the current working directory. Previously this raised a big warning, which now seems to be suppressed. So likely this will go away and error in a future version, or show slightly different behavior.

Can you provide a sketch of your code explaining your usage and ideally explain to me how you arrived at your implementation? I could use that to figure out how to improve the documentation and ensure correct error messages and warnings to direct users intuitively to the recommended way of using this library.

[hburrichter]

Thanks for the quick fix in v0.3.9!

To answer your question: our main use case is actually relative_to() - we use it to get relative paths from absolute paths, and those resulting paths need correct .name/.parts/.parent properties.

We don't rely on direct instantiation like FilePath("relative/path") in production. If that errors or warns in the future, that's fine for us - as long as paths returned by relative_to() continue to work correctly.

Our tests covered direct instantiation for completeness, which is how we discovered the bug.