Skip to content

Commit 170d9be

Browse files
lagamuraap--
andauthored
DOC: describe UPath/s3fs behavior with is_dir() (#503)
* scaffold docs for `S3Path.is_dir()` returns `False` instead of raising error when no credentials are provided Fixes #502 * docs: align style with other sections --------- Co-authored-by: Andreas Poehlmann <ap--@users.noreply.github.com>
1 parent 735cf0c commit 170d9be

1 file changed

Lines changed: 32 additions & 0 deletions

File tree

docs/usage.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -166,6 +166,38 @@ if s3path.is_file():
166166
print("It's a file!")
167167
```
168168

169+
### How does UPath handle S3 prefixes that don't exist?
170+
171+
S3 prefixes aren't traditional POSIX directories. UPath follows `pathlib` conventions—checking a non-existent path returns `False`:
172+
173+
```python
174+
from upath import UPath
175+
176+
# Non-existent bucket returns False, just like pathlib
177+
fake_path = UPath("s3://bucket-that-doesnt-exist/my-dir/")
178+
print(fake_path.is_dir())
179+
# False
180+
```
181+
182+
This matches standard `pathlib` behavior:
183+
184+
```python
185+
import pathlib
186+
187+
# pathlib also returns False for non-existent paths
188+
assert pathlib.Path('/path/that/does/not/exist').is_dir() is False
189+
assert pathlib.Path('/path/that/does/not/exist').exists() is False
190+
```
191+
192+
!!! warning "Authentication Required"
193+
If the bucket exists but you lack credentials, an authentication exception will be raised:
194+
195+
```python
196+
# This bucket exists but requires authentication
197+
s3_path = UPath("s3://my-private-bucket/data/")
198+
s3_path.is_dir() # Raises authentication exception
199+
```
200+
169201
### How do I search for files matching a pattern?
170202

171203
Use `glob()` for pattern matching:

0 commit comments

Comments
 (0)