From b931967e5f880393274afe3cf2198e36f3fa124d Mon Sep 17 00:00:00 2001
From: lagarass <stelios.lagaras@vito.be>
Date: Sun, 14 Dec 2025 12:11:40 +0100
Subject: [PATCH 1/2] scaffold docs for `S3Path.is_dir()` returns `False`
 instead of raising error when no credentials are provided Fixes #502

---
 docs/usage.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/docs/usage.md b/docs/usage.md
index a53f062b..06725914 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -166,6 +166,45 @@ if s3path.is_file():
     print("It's a file!")
 ```
 
+### Following pathlib behavior for listing virtual directories on S3
+Prefixes (PRE) on S3 protocol are not posix directories with the traditional meaning.
+
+When `is_dir()` is invoked from a UPath object, it will use `s3fs` lower level handling
+when trying to list a PRE for a non-existing bucket:
+
+```python
+from upath import UPath
+
+fake_uri_dir = "s3://one-bucket-that-doesnt-exists-for-sure/my-dir/"
+_s3_obj = UPath(
+    fake_uri_dir,
+)
+print(_s3_obj.is_dir())
+> False
+```
+The former behavior aligns with how `pathlib` handles non-existing directories:
+```python
+import pathlib
+assert pathlib.Path('/some-path/that-does-not-exist').is_dir() is False  # unix
+assert pathlib.Path('Y:/some-drive-and-path/that-does-not-exist').is_dir() is False  # windows
+
+assert pathlib.Path('/some-path/that-does-not-exist').exists() is False  # unix
+assert pathlib.Path('Y:/some-drive-and-path/that-does-not-exist').exists() is False  # windows
+```
+
+Though, if the bucket exists but authentication is not provided an Auth exception will be raised
+```python
+from upath import UPath
+
+uri_dir = "s3://my-bucket/my-dir/"
+#my-bucket exists and requires auth at: https://my-bucket.s3.eu-central-1.amazonaws.com
+
+_s3_obj = UPath(
+    uri_dir,
+)
+print(_s3_obj.is_dir()) #This raises an Auth exception
+```
+
 ### How do I search for files matching a pattern?
 
 Use `glob()` for pattern matching:

From 8a283355ed2d459516238f7690f77d817d4156ba Mon Sep 17 00:00:00 2001
From: Andreas Poehlmann <ap--@users.noreply.github.com>
Date: Sat, 20 Dec 2025 00:53:47 +0100
Subject: [PATCH 2/2] docs: align style with other sections

---
 docs/usage.md | 45 +++++++++++++++++++--------------------------
 1 file changed, 19 insertions(+), 26 deletions(-)

diff --git a/docs/usage.md b/docs/usage.md
index 06725914..ee8e6a94 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -166,44 +166,37 @@ if s3path.is_file():
     print("It's a file!")
 ```
 
-### Following pathlib behavior for listing virtual directories on S3
-Prefixes (PRE) on S3 protocol are not posix directories with the traditional meaning.
+### How does UPath handle S3 prefixes that don't exist?
 
-When `is_dir()` is invoked from a UPath object, it will use `s3fs` lower level handling
-when trying to list a PRE for a non-existing bucket:
+S3 prefixes aren't traditional POSIX directories. UPath follows `pathlib` conventions—checking a non-existent path returns `False`:
 
 ```python
 from upath import UPath
 
-fake_uri_dir = "s3://one-bucket-that-doesnt-exists-for-sure/my-dir/"
-_s3_obj = UPath(
-    fake_uri_dir,
-)
-print(_s3_obj.is_dir())
-> False
+# Non-existent bucket returns False, just like pathlib
+fake_path = UPath("s3://bucket-that-doesnt-exist/my-dir/")
+print(fake_path.is_dir())
+# False
 ```
-The former behavior aligns with how `pathlib` handles non-existing directories:
+
+This matches standard `pathlib` behavior:
+
 ```python
 import pathlib
-assert pathlib.Path('/some-path/that-does-not-exist').is_dir() is False  # unix
-assert pathlib.Path('Y:/some-drive-and-path/that-does-not-exist').is_dir() is False  # windows
 
-assert pathlib.Path('/some-path/that-does-not-exist').exists() is False  # unix
-assert pathlib.Path('Y:/some-drive-and-path/that-does-not-exist').exists() is False  # windows
+# pathlib also returns False for non-existent paths
+assert pathlib.Path('/path/that/does/not/exist').is_dir() is False
+assert pathlib.Path('/path/that/does/not/exist').exists() is False
 ```
 
-Though, if the bucket exists but authentication is not provided an Auth exception will be raised
-```python
-from upath import UPath
-
-uri_dir = "s3://my-bucket/my-dir/"
-#my-bucket exists and requires auth at: https://my-bucket.s3.eu-central-1.amazonaws.com
+!!! warning "Authentication Required"
+    If the bucket exists but you lack credentials, an authentication exception will be raised:
 
-_s3_obj = UPath(
-    uri_dir,
-)
-print(_s3_obj.is_dir()) #This raises an Auth exception
-```
+    ```python
+    # This bucket exists but requires authentication
+    s3_path = UPath("s3://my-private-bucket/data/")
+    s3_path.is_dir()  # Raises authentication exception
+    ```
 
 ### How do I search for files matching a pattern?