From d395bb223ae922b6a8880de3ae2e544972297399 Mon Sep 17 00:00:00 2001 From: karajan1001 Date: Sat, 20 Aug 2022 16:54:28 +0800 Subject: [PATCH] New examples for each API fix: #47 1. Add new example in comment for each API. --- aiooss2/api.py | 96 +++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 92 insertions(+), 4 deletions(-) diff --git a/aiooss2/api.py b/aiooss2/api.py index fdb890d..dbbdbaf 100644 --- a/aiooss2/api.py +++ b/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.