docs: clarify storage entry points and S3 usage

Author: PsiACE

docs/index.md

@@ -56,7 +56,7 @@ Find examples backed by the repository's integration tests.
 :link: reference/api
 :link-type: doc
 
-Inspect the public classes and registration helpers provided by `opendalfs`.
+Inspect the public filesystem classes provided by `opendalfs`.
 :::
 ::::
 

docs/integrations/pandas.md

@@ -32,13 +32,52 @@ pd.testing.assert_frame_equal(result, frame)
 See {doc}`../user-guide/connecting-to-storage` for path and authority handling
 with bucket-scoped services.
 
+## Read and write CSV with S3 URLs
+
+Register `S3FileSystem` before using pandas with `s3://` URLs. This selects OpenDAL for subsequent fsspec S3 lookups in the current process; it is not required for `opendal+s3://` URLs.
+
+This example uses the local MinIO service and existing bucket described in {doc}`../user-guide/connecting-to-storage`. Set the environment variables below to connect to your own storage. The default credentials are only for local development.
+
+```python
+import os
+
+import fsspec
+import pandas as pd
+from opendalfs import S3FileSystem
+
+fsspec.register_implementation("s3", S3FileSystem, clobber=True)
+
+bucket = os.environ.get("OPENDAL_S3_BUCKET", "test-bucket")
+storage_options = {
+    "key": os.environ.get("OPENDAL_S3_ACCESS_KEY_ID", "minioadmin"),
+    "secret": os.environ.get("OPENDAL_S3_SECRET_ACCESS_KEY", "minioadmin"),
+    "client_kwargs": {
+        "endpoint_url": os.environ.get("OPENDAL_S3_ENDPOINT", "http://127.0.0.1:9000"),
+        "region_name": os.environ.get("OPENDAL_S3_REGION", "us-east-1"),
+    },
+}
+url = f"s3://{bucket}/docs/scores.csv"
+frame = pd.DataFrame({"name": ["Alice", "Bob"], "score": [90, 85]})
+
+frame.to_csv(url, index=False, storage_options=storage_options)
+result = pd.read_csv(url, storage_options=storage_options)
+pd.testing.assert_frame_equal(result, frame)
+
+fs, path = fsspec.core.url_to_fs(url, **storage_options)
+fs.rm(path)
+```
+
+Each OpenDAL S3 filesystem is scoped to one bucket. See {doc}`../reference/configuration` for the supported s3fs configuration options; not every s3fs feature is available.
+
 ## Test coverage
 
 The repository tests:
 
 - CSV and Parquet URL operations through `opendal+s3`
 - Parquet round trips with an explicit filesystem
 
+The documentation example checker also executes the `s3://` CSV round trip above.
+
 The test runs against memory, local filesystem, and MinIO-backed S3 fixtures.
 See
 [`tests/integration/pandas/test_pandas.py`](https://github.com/fsspec/opendalfs/blob/main/tests/integration/pandas/test_pandas.py).

docs/reference/configuration.md

@@ -48,7 +48,9 @@ fs = OpendalFileSystem(
 Use the [OpenDAL service directory](https://opendal.apache.org/services/) as the
 configuration reference. Option names pass through unchanged.
 
-The `S3FileSystem` adapter accepts these common `s3fs` aliases:
+## S3 compatibility options
+
+The `S3FileSystem` adapter for `s3://` accepts the following `s3fs` aliases. These aliases do not apply to `OpendalFileSystem` or the `opendal+...` protocols, which use OpenDAL option names.
 
 | s3fs option | OpenDAL S3 option |
 | --- | --- |
@@ -66,11 +68,16 @@ The `S3FileSystem` adapter accepts these common `s3fs` aliases:
 
 OpenDAL option names take precedence when both forms are provided.
 Unsupported nested `client_kwargs` raise `TypeError`.
+`client_kwargs` must be a mapping. Top-level aliases take precedence over aliases inside `client_kwargs`.
+
+`default_block_size` sets the filesystem's default block size in bytes. It is an adapter setting, not an OpenDAL service option. Other s3fs-specific options and features are not guaranteed to be compatible.
 
 ## URL-derived settings
 
 Registered service adapters can derive one setting from the URL authority. For
 example, `opendal+s3://my-bucket/path` supplies `bucket="my-bucket"`.
 Explicit filesystem construction requires the bucket keyword instead.
 
+For `s3://my-bucket/path`, `S3FileSystem` uses `my-bucket` even when a different `bucket` is present in the storage options. Paths passed to this filesystem include the bucket, such as `my-bucket/path`; the underlying OpenDAL operator receives the bucket-relative key.
+
 Do not provide conflicting values through the URL and keyword arguments.

docs/reference/protocols.md

@@ -29,8 +29,8 @@ from opendalfs import S3FileSystem
 fsspec.register_implementation("s3", S3FileSystem, clobber=True)
 ```
 
-This explicit process-wide operation is the only way opendalfs changes the meaning of a standard protocol.
+Installing or importing opendalfs does not replace fsspec's S3 implementation. The explicit registration above replaces it for subsequent lookups in the current process.
 The adapter accepts the common s3fs constructor options listed in {doc}`configuration`.
-Each adapter instance is scoped to one bucket; a multi-path operation spanning buckets raises `ValueError`.
+Each adapter instance is scoped to one bucket; paths belonging to another bucket raise `ValueError`. This is not a complete replacement for every s3fs feature.
 
 See {doc}`../user-guide/connecting-to-storage` for complete examples.

docs/user-guide/connecting-to-storage.md

@@ -4,6 +4,12 @@ An `opendalfs` filesystem needs an OpenDAL service name and that service's
 configuration. Choose the construction style that matches the library you are
 using.
 
+| Your application accepts | Use |
+| --- | --- |
+| A filesystem, mapping, or file-like object | `OpendalFileSystem("service", ...)` |
+| An explicit OpenDAL URL | `opendal+s3://`, `opendal+gcs://`, or `opendal+azblob://` |
+| An `s3://` URL | Register `S3FileSystem` with fsspec before using it |
+
 ## Construct the filesystem directly
 
 Use {class}`opendalfs.OpendalFileSystem` when your code controls the filesystem
@@ -23,6 +29,19 @@ fs = OpendalFileSystem(
 The first argument selects the OpenDAL service. Remaining service-specific
 keyword arguments are passed to the OpenDAL Python binding.
 
+This also works for services without a URL adapter. For example, the local filesystem service needs no credentials:
+
+```python
+from tempfile import TemporaryDirectory
+
+with TemporaryDirectory() as directory:
+    fs = OpendalFileSystem("fs", root=directory)
+    fs.pipe_file("hello.txt", b"Hello from OpenDAL!")
+    assert fs.cat_file("hello.txt") == b"Hello from OpenDAL!"
+```
+
+Available services depend on the installed OpenDAL Python binding. Pass the filesystem, its mapping, or an opened file to libraries that accept these objects; no protocol registration is needed.
+
 ## Ask fsspec for a registered filesystem
 
 The package installs fsspec entry points for S3, Google Cloud Storage, and Azure
@@ -38,31 +57,70 @@ fs = fsspec.filesystem(
 )
 ```
 
-## Keep an existing S3 URL
+## Use S3 URLs
 
-Applications that cannot rewrite existing `s3://` URLs can explicitly replace fsspec's S3 implementation:
+Register `S3FileSystem` to use OpenDAL with `s3://` URLs and the supported s3fs configuration options:
 
 ```python
 import fsspec
 from opendalfs import S3FileSystem
 
 fsspec.register_implementation("s3", S3FileSystem, clobber=True)
+```
 
-fs, path = fsspec.core.url_to_fs(
-    "s3://my-bucket/reports/2026.csv",
-    key="access-key",
-    secret="secret-key",
-    client_kwargs={"region_name": "us-east-1"},
-)
+The registration replaces the S3 implementation for subsequent fsspec lookups in the current process. Run it during application startup, before constructing an S3 filesystem. Installing or importing `opendalfs` does not change `s3://`. Use `opendal+s3://` if you do not want to change the process-wide registration.
+
+### Write and read a file
+
+The following example uses a local MinIO service at `http://127.0.0.1:9000` with an existing `test-bucket` bucket. The default credentials are for local development only. Set the `OPENDAL_S3_*` environment variables to use your own endpoint, credentials, and bucket.
+
+When working from this repository, `podman compose up -d --wait` starts the MinIO service. Create the bucket in the MinIO console at `http://localhost:9001` before running the example; the repository's documentation checks create their test bucket automatically.
+
+```python
+import os
+
+bucket = os.environ.get("OPENDAL_S3_BUCKET", "test-bucket")
+storage_options = {
+    "key": os.environ.get("OPENDAL_S3_ACCESS_KEY_ID", "minioadmin"),
+    "secret": os.environ.get("OPENDAL_S3_SECRET_ACCESS_KEY", "minioadmin"),
+    "client_kwargs": {
+        "endpoint_url": os.environ.get("OPENDAL_S3_ENDPOINT", "http://127.0.0.1:9000"),
+        "region_name": os.environ.get("OPENDAL_S3_REGION", "us-east-1"),
+    },
+}
+url = f"s3://{bucket}/docs/hello.txt"
+
+with fsspec.open(url, "wt", **storage_options) as stream:
+    stream.write("Hello from OpenDAL!")
+
+with fsspec.open(url, "rt", **storage_options) as stream:
+    assert stream.read() == "Hello from OpenDAL!"
 ```
 
-The registration call is process-wide and should run during application startup, before constructing an S3 filesystem.
-`S3FileSystem` translates common s3fs names such as `key`, `secret`, `token`, `anon`, and supported `client_kwargs`.
-Installing `opendalfs` alone never changes `s3://`.
+The same `storage_options` can be passed to downstream libraries; see the {doc}`../integrations/pandas` example. The complete list of supported s3fs aliases is in {doc}`../reference/configuration`.
+
+### Bucket scope and compatibility
 
 An OpenDAL S3 operator is scoped to one bucket, so each `S3FileSystem` instance is also scoped to one bucket.
-Independent fsspec calls can use different buckets.
-A single multi-path operation spanning buckets raises `ValueError` instead of sending a path to the wrong bucket.
+`url_to_fs` takes the bucket from the URL and returns a bucket-prefixed path:
+
+```python
+fs, path = fsspec.core.url_to_fs(url, **storage_options)
+assert path == f"{bucket}/docs/hello.txt"
+assert fs.cat_file(path) == b"Hello from OpenDAL!"
+
+try:
+    fs.cat_file(f"{bucket}-other/docs/hello.txt")
+except ValueError:
+    pass  # This filesystem cannot access another bucket.
+else:
+    raise AssertionError("A path in another bucket must be rejected")
+
+```
+
+Independent fsspec calls can use different buckets; create a separate filesystem for each bucket. When constructing `S3FileSystem` directly, pass `bucket=...` explicitly.
+
+The adapter does not implement every s3fs option or feature. Only the aliases listed in the configuration reference are supported as s3fs options; unsupported `client_kwargs` raise `TypeError`.
 
 ## Understand OpenDAL URLs
 
@@ -80,8 +138,25 @@ opendal+gcs://my-bucket/reports/2026.csv
 opendal+azblob://my-container/reports/2026.csv
 ```
 
+These URLs use OpenDAL option names, not s3fs aliases. To read the same MinIO object written above:
+
+```python
+with fsspec.open(
+    f"opendal+s3://{bucket}/docs/hello.txt",
+    "rt",
+    endpoint=storage_options["client_kwargs"]["endpoint_url"],
+    region=storage_options["client_kwargs"]["region_name"],
+    access_key_id=storage_options["key"],
+    secret_access_key=storage_options["secret"],
+) as stream:
+    assert stream.read() == "Hello from OpenDAL!"
+
+fs.rm(path)
+```
+
 Other OpenDAL services intentionally have no URL adapter.
 Construct `OpendalFileSystem` directly and pass the filesystem, mapping, or opened file to the consuming library.
+For application-defined URL protocols, use fsspec's `register_implementation()` with a filesystem class that implements the protocol's URL and path rules. Registration alone does not add those rules to `OpendalFileSystem`.
 
 ## Find service options