pathlib and Filesystem Paths

`pathlib` has been in the standard library since Python 3.4, and it exists because a filesystem path is not really a string: it has structure, its separator is platform-dependent, and almost every bug in hand-rolled path code comes from treating it as text. ### Pure paths and concrete paths `Path("exports")` returns a concrete path for the host you are running on — a `PosixPath` on Unix and macOS, a `WindowsPath` on Windows. Both inherit from `PurePath`, which holds every operation that is pure string algebra: joining, splitting, comparing, matching. `PurePosixPath` and `PureWindowsPath` let you manipulate a foreign-flavoured path on any host, which is the only sane way to parse a Windows path inside a test running on Linux. The split matters because it tells you which calls hit the filesystem: anything on `PurePath` cannot, anything added by `Path` (`exists`, `is_file`, `read_text`, `mkdir`, `glob`, `resolve`) can. ### Joining with / `PurePath.__truediv__` is why `/` works, and `__rtruediv__` is why `"exports" / Path("schedule.json")` works too. Each `/` returns a brand-new path object; paths are immutable and hashable, so you can use them as dict keys and share them freely. `joinpath("a", "b")` is the method form, useful when the segments arrive as a list you want to splat. One rule surprises people, and it matches `os.path.join`: **an absolute right-hand segment discards everything on the left.** `Path("/srv/data") / "/etc/hosts"` is `Path("/etc/hosts")`, not a path under `/srv/data`. So concatenating a caller-supplied segment does not by itself keep the result inside your base directory. Joining normalises separators but not semantics: `Path("a//b")` and `Path("a/b/")` both collapse to `a/b`, so `Path("a/b/").name` is `"b"` and not `""`. But `..` and `.` are left alone — `Path("a/b/..").parent` is `Path("a/b")`, not `Path(".")`. Only `resolve()` eliminates `..`. ### Decomposing - `.parts` — the components as a tuple, e.g. `('exports', '2026-03-01', 'schedule.json')`. - `.name` — the last component. It is `''` for a root path such as `Path("/")`. - `.suffix` — the **last** dot-extension only. For `schedule.tar.gz` that is `'.gz'`. - `.suffixes` — the full list, `['.tar', '.gz']`. - `.stem` — `.name` with exactly one suffix removed, so `'schedule.tar'` for that file. - `.parent` — the path minus its last component; it never climbs above what it was given, so `Path("schedule.json").parent` is `Path(".")` and `Path(".").parent` is `Path(".")`. - `.parents` — a lazy sequence of ancestors, and the classic off-by-one lives here: `parents[0]` is the parent, not the path itself. Since 3.10 it accepts slices and negative indices. - `.anchor`, `.drive`, `.root` — the platform prefix, mostly interesting on Windows. A leading dot is not a suffix: `Path(".gitignore").suffix` is `''` and its `.stem` is `'.gitignore'`. That single rule fixes the most common naive `splitext` bug. For rewriting a name there are three helpers rather than string surgery: `with_name`, `with_suffix` (replaces the last one, or appends if there is none) and `with_stem` (added in 3.9). ### Equality is lexical, not filesystem truth Two paths compare equal when their string forms match under their flavour — case-sensitively on POSIX, case-insensitively on Windows — and paths of different flavours are never equal. `Path("a/b")` and `Path("a/c/../b")` are different objects even though they name one file: redundant separators and single-dot components are dropped when the path is parsed, but `..` never is. `==` never performs a syscall. To ask whether two paths point at the same file, call `Path.samefile()`, which stats both and compares device and inode. ### Interoperating with older APIs `Path` implements the `os.PathLike` protocol, so `open(p)`, `os.stat(p)`, `os.scandir(p)` and essentially every stdlib function that takes a filename accepts one directly; `os.fspath(p)` is the explicit conversion to `str`. Only a third-party library that predates that protocol, or code that does string formatting on the value, needs `str(p)` — and `as_posix()` is the right call when you need forward slashes in output regardless of host.