new feature: Better python docs

[jayceslesar]

Feature Description

I was playing around with OpenDAL and have written a few file system abstractions before and was thinking the python docs could be a little bit better in hopes of making it easier for users to use the python bindings. For example maybe a little suite showing users how they could achieve parity with Pathlib!

The following is a rough and incomplete impementation of a Pathlib like interface using an operator under the hood:

from urllib.parse import urlparse
from opendal import Operator, File
from pathlib import Path


class OpenDALPath:
    def __init__(self, path: str, **options) -> None:

        self.parsed = urlparse(path)
        scheme = self.parsed.scheme
        netloc = self.parsed.netloc
        self.path = Path(self.parsed.path)

        root = str(self.path.parent)

        if scheme in ("fs", ""):
            operator = Operator("fs", root=root, **options)

        elif scheme in ("s3", "gcs"):
            operator = Operator(scheme, root=root, bucket=netloc)
        else:
            raise ValueError(f"Unsupported scheme: {scheme}")

        self.operator = operator

    def open(self, mode: str, **options) -> File:
        return self.operator.open(mode, **options)

    def read_text(self, **options) -> str:
        ...

    def read_bytes(self, **options) -> str:
        ...

    def write_text(self, data: str, **options) -> None:
        self.operator.write(self.path.name, data, content_type="text/plain", **options)

    def write_bytes(self, data: bytes, **options) -> None:
       self.operator.write(self.path.name, data, **options)

Problem and Solution

The solution does not look like the code above, but I think some better docs showing uses of reading and writing text and binary data would go a long way, additionally showing the usage of the operator with and without a context manager. Ideally, there is a way to autogenerate this documentation so that all bindings can better benefit, but that seems out of reach.

Additional Context

No response

Are you willing to contribute to the development of this feature?

• Yes, I am willing to contribute to the development of this feature.