@@ -111,7 +111,11 @@ And of course, contributions for new filesystems are welcome!
111111
112112The class hierarchy for ` UPath ` implementations and their relation to base classes
113113in ` pathlib_abc ` and the stdlib ` pathlib ` classes are visualized in the following
114- diagram:
114+ diagram. Please be aware that the ` pathlib_abc.JoinablePath ` ,
115+ ` pathlib_abc.ReadablePath ` , and ` pathlib_abc.WritablePath ` classes are currently
116+ not actual parent classes of the stdlib pathlib classes. This might occur in
117+ later Python releases, but for now, the mental model you should keep is represented
118+ by the diagram.
115119
116120``` mermaid
117121flowchart TB
@@ -122,14 +126,14 @@ flowchart TB
122126 end
123127
124128 subgraph s0[pathlib]
125- X --> A
129+ X -. -> A
126130
127131 A----> B
128132 A--> AP
129133 A--> AW
130134
131- Y --> B
132- Z --> B
135+ Y -. -> B
136+ Z -. -> B
133137
134138 B--> BP
135139 AP----> BP
@@ -184,6 +188,19 @@ flowchart TB
184188 style s1 fill:none,stroke:#d02,stroke-width:3px,stroke-dasharray:3,color:#d02
185189```
186190
191+ To be concrete this currently means:
192+
193+ ``` python
194+ # for all supported Python versions:
195+ from pathlib import Path
196+ from upath import UPath
197+ from upath.types import JoinablePath
198+
199+ assert isinstance (Path(), JoinablePath) is False
200+ assert isinstance (UPath(), JoinablePath) is True
201+ ```
202+
203+
187204When instantiating ` UPath ` the returned instance type is determined by the path,
188205or better said, the "protocol" that was provided to the constructor. The ` UPath `
189206class will return a registered implementation for the protocol, if available. If
@@ -255,6 +272,113 @@ with fs.open(p.path) as f:
255272 data = f.read()
256273```
257274
275+ ## Supported Interface
276+
277+ Universal Pathlib provides an implementation of the ` pathlib.Path ` interface
278+ across different Python versions. The following table shows the compatibility
279+ matrix for stdlib pathlib.Path attributes and methods. Methods supported in
280+ UPath should correctly work for all supported Python versions. If not, we consider
281+ it a bug.
282+
283+ | Method/Attribute | py3.9 | py3.10 | py3.11 | py3.12 | py3.13 | py3.14 | UPath |
284+ | ---------------------------| -------| --------| --------| --------| --------| --------| -------|
285+ | ** Pure Paths** | | | | | | | |
286+ | _ Operators_ | | | | | | | |
287+ | ` __truediv__ ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
288+ | ` __rtruediv__ ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
289+ | _ Access individual Parts_ | | | | | | | |
290+ | ` parts ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
291+ | _ Methods and Properties_ | | | | | | | |
292+ | ` parser ` | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
293+ | ` drive ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
294+ | ` root ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
295+ | ` anchor ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
296+ | ` parents ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
297+ | ` parent ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
298+ | ` name ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
299+ | ` suffix ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
300+ | ` suffixes ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
301+ | ` stem ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
302+ | ` as_posix() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
303+ | ` is_absolute() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
304+ | ` is_relative_to() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
305+ | ` is_reserved() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
306+ | ` joinpath() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
307+ | ` full_match() ` | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
308+ | ` match() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
309+ | ` relative_to() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
310+ | ` with_name() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
311+ | ` with_stem() ` | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ |
312+ | ` with_suffix() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
313+ | ` with_segments() ` | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ |
314+ | ** Concrete Paths** | | | | | | | |
315+ | _ Parsing URIs_ | | | | | | | |
316+ | ` from_uri() ` | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
317+ | ` as_uri() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
318+ | _ Expanding Paths_ | | | | | | | |
319+ | ` home() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
320+ | ` expanduser() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
321+ | ` cwd() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
322+ | ` absolute() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
323+ | ` resolve() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
324+ | ` readlink() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ |
325+ | _ Querying File status_ | | | | | | | |
326+ | ` stat() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
327+ | ` lstat() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
328+ | ` exists() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
329+ | ` is_file() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
330+ | ` is_dir() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
331+ | ` is_symlink() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
332+ | ` is_junction() ` | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ |
333+ | ` is_mount() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
334+ | ` is_socket() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
335+ | ` is_fifo() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
336+ | ` is_block_device() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
337+ | ` is_char_device() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
338+ | ` samefile() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
339+ | ` info ` | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
340+ | _ Reading & Writing Files_ | | | | | | | |
341+ | ` open() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
342+ | ` read_text() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
343+ | ` read_bytes() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
344+ | ` write_text() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
345+ | ` write_bytes() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
346+ | _ Reading Directories_ | | | | | | | |
347+ | ` iterdir() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
348+ | ` glob() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
349+ | ` rglob() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
350+ | ` walk() ` | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ |
351+ | _ Creating Files & Dirs_ | | | | | | | |
352+ | ` touch() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
353+ | ` mkdir() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
354+ | ` symlink_to() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ |
355+ | ` hardlink_to() ` | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ |
356+ | _ Copying & Moving_ | | | | | | | |
357+ | ` copy() ` | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
358+ | ` copy_into() ` | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
359+ | ` rename() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
360+ | ` replace() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ |
361+ | ` move() ` | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
362+ | ` move_into() ` | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
363+ | ` unlink() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
364+ | ` rmdir() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
365+ | _ Permission & Owner_ | | | | | | | |
366+ | ` owner() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ |
367+ | ` group() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ |
368+ | ` chmod() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ |
369+ | ` lchmod() ` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ |
370+ | ** UPath interface** | | | | | | | |
371+ | ` protocol ` | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
372+ | ` storage_options ` | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
373+ | ` path ` | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
374+ | ` fs ` | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
375+ | ` joinuri() ` | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
376+
377+ ** Key:**
378+ - ✅ = Available/Supported
379+ - ❌ = Not available in this version
380+ - ⚠️ = Currently raises unsupported error for UPath implementations
381+
258382## Advanced Usage
259383
260384If you want to create your own UPath implementations, there are multiple ways to
0 commit comments