[I] new feature: Better python docs [opendal]

["jayceslesar (via GitHub)" <gi...@apache.org>]

jayceslesar opened a new issue, #6471:
URL: https://github.com/apache/opendal/issues/6471

   ### 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:
   
   ```py
   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_binary(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.
   
   ### Additional Context
   
   _No response_
   
   ### Are you willing to contribute to the development of this feature?
   
   - [x] Yes, I am willing to contribute to the development of this feature.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@opendal.apache.org.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [I] new feature: Better python docs [opendal]

["erickguan (via GitHub)" <gi...@apache.org>]

erickguan commented on issue #6471:
URL: https://github.com/apache/opendal/issues/6471#issuecomment-3383546327

   Great initiative for more documentation.
   
   You might know cloudpathlib https://cloudpathlib.drivendata.org/stable/testing_mocked_cloudpathlib/
   
   This shall be closer to build more similar examples.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@opendal.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [I] new feature: Better python docs [opendal]

["erickguan (via GitHub)" <gi...@apache.org>]

erickguan closed issue #6471: new feature: Better python docs
URL: https://github.com/apache/opendal/issues/6471


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@opendal.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org