New examples for each API

fix: #47
1. Add new example in comment for each API.

aiooss2/api.py

@@ -303,10 +303,8 @@ async def get_object(  # pylint: disable=too-many-arguments
         """download the contents of an object
 
         (use case) ::
-            >>> resp = await bucket.get_object("helloword")
-            >>> async with resp as result:
-            >>>     data = await result.read()
-            >>> print(data)
+            >>> async with await bucket.get_object("helloword") as result
+            >>>     print(await result.read())
             'hello world'
 
         Args:
@@ -348,6 +346,16 @@ async def delete_object(
     ) -> "RequestResult":
         """delete an object
 
+        (use case) ::
+            >>> async for obj in AioObjectIterator(bucket):
+            >>>    print(obj.key)
+            'object1'
+            'object2'
+            >>> await bucket.delete_object("object1")
+            >>> async for obj in AioObjectIterator(bucket):
+            >>>    print(obj.key)
+            'object2'
+
         Args:
             key (str): _description_
             headers (Optional[Dict], optional): HTTP headers to specify.
@@ -373,6 +381,12 @@ async def list_objects(  # pylint: disable=too-many-arguments
     ) -> "ListObjectsResult":
         """list objects in a bucket
 
+        (use case) ::
+            >>> async for obj in AioObjectIterator(bucket, prefix=object_path):
+            >>>    print(obj.key)
+            'object1'
+            'object2'
+
         Args:
             prefix (str, optional): only list objects start with this prefix.
             delimiter (str, optional): delimiter as a folder separator.
@@ -409,6 +423,11 @@ async def get_object_meta(
     ) -> "GetObjectMetaResult":
         """get meta data from object
 
+        (use case) ::
+            >>> result = await bucket.get_object_meta(object_name)
+            >>> print(result.content_length )
+            256
+
         Args:
             key (str): object key
             params (Optional[Union[dict, CaseInsensitiveDict]], optional):
@@ -437,6 +456,11 @@ async def object_exists(
         """Return True if key exists, False otherwise. raise Exception
         for other exceptions.
 
+        (use case) ::
+            >>> result = await bucket.object_exists('object1')
+            >>> print(result)
+            True
+
         Args:
             key (str): key of the object
             headers (Optional[Union[Dict, CaseInsensitiveDict]], optional):
@@ -456,6 +480,11 @@ async def object_exists(
     async def get_bucket_info(self) -> GetBucketInfoResult:
         """Get bucket infomation, `Create time`, `Endpoint`, `Owner`, `ACL`
 
+        (use case) ::
+            >>> resp = await aiobucket.get_bucket_info()
+            >>> print(resp.name)
+            'bucket_name'
+
         Returns:
             GetBucketInfoResult
         """
@@ -476,6 +505,15 @@ async def append_object(
     ) -> "AppendObjectResult":
         """Append value to an object
 
+        (use case) ::
+            >>> async with await bucket.get_object("object1") as result
+            >>>     print(await result.read())
+            'hello world'
+            >>> resp = await bucket.append_object('object1', 11, "!!!")
+            >>> async with await bucket.get_object("object1") as result
+            >>>     print(await result.read())
+            'hello world!!!'
+
         Args:
             key (str): key of the object
             position (int): position to append
@@ -520,6 +558,16 @@ async def put_object_from_file(
     ) -> "PutObjectResult":
         """Upload a local file to a oss key
 
+        (use case) ::
+            >>> with open("file") as f:
+            >>>     print(f.read())
+            "hellow world"
+            >>> result = await aiobucket.put_object_from_file("object1",
+                "file")
+            >>> async with await bucket.get_object("object1") as result
+            >>>     print(await result.read())
+            'hello world'
+
         Args:
             key (str): key of the oss
             filename (str): filename to upload
@@ -551,6 +599,12 @@ async def get_object_to_file(
     ) -> AioGetObjectResult:
         """Download contents of object to file.
 
+        (use case) ::
+            >>> result = await aiobucket.get_object_to_file("object1", "file")
+            >>> with open("file") as f:
+            >>>     print(f.read())
+            "hellow world"
+
         Args:
             key (str): object name to download.
             filename (str): filename to save the data downloaded.
@@ -605,6 +659,23 @@ async def batch_delete_objects(
     ) -> BatchDeleteObjectsResult:
         """Delete a batch of objects
 
+        (use case) ::
+            >>> async for obj in AioObjectIterator(bucket, prefix=object_path):
+            >>>    print(obj.key)
+            'object1'
+            'object2'
+            'object3'
+            'object4'
+            'object5'
+            'object6'
+            >>> await aiobucket.batch_delete_objects(["object1", "object2",
+                "object3"])
+            >>> async for obj in AioObjectIterator(bucket, prefix=object_path):
+            >>>    print(obj.key)
+            'object4'
+            'object5'
+            'object6'
+
         Args:
             key_list (List[str]): list of objects to delete.
             headers (Optional[Dict], optional): HTTP headers to specify.
@@ -644,6 +715,16 @@ async def copy_object(
     ) -> PutObjectResult:
         """copy object to another place
 
+        (use case) ::
+            >>> async for obj in AioObjectIterator(bucket, prefix=object_path):
+            >>>    print(obj.key)
+            'object1'
+            >>> await aiobucket.copy_object(bucket_name, "object1", "object2")
+            >>> async for obj in AioObjectIterator(bucket, prefix=object_path):
+            >>>    print(obj.key)
+            'object1'
+            'object2'
+
         Args:
             source_bucket_name (str): source object bucket
             source_key (str): source object key
@@ -719,6 +800,13 @@ async def list_buckets(
     ) -> ListBucketsResult:
         """List buckets with given prefix of an user
 
+        (use case) ::
+            >>> async for obj in AioBucketIterator(aioservice):
+            >>>     print(obj.name)
+            'bucket_name1'
+            'bucket_name2'
+            ...
+
         Args:
             prefix (str, optional): prefix to filter the buckets results.
             marker (str, optional): paginate separator.