Add describe regions (#335)

Author: zhuxiaolong37

oss2/api.py

@@ -296,6 +296,7 @@ class Service(_Base):
     """
 
     QOS_INFO = 'qosInfo'
+    REGIONS = 'regions'
 
     def __init__(self, auth, endpoint,
                  session=None,
@@ -347,6 +348,19 @@ def get_user_qos_info(self):
         logger.debug("get use qos, req_id: {0}, status_code: {1}".format(resp.request_id, resp.status))
         return self._parse_result(resp, xml_utils.parse_get_qos_info, GetUserQosInfoResult)
 
+    def describe_regions(self, regions=''):
+        """查询所有支持地域或者指定地域对应的Endpoint信息，包括外网Endpoint、内网Endpoint和传输加速Endpoint。
+
+        :param str regions : 地域。
+        :return: :class:`DescribeRegionsResult <oss2.models.DescribeRegionsResult>`
+        """
+        logger.debug("Start to describe regions")
+
+        resp = self._do('GET', '', '', params={Service.REGIONS: regions})
+        logger.debug("Describe regions done, req_id: {0}, status_code: {1}".format(resp.request_id, resp.status))
+
+        return self._parse_result(resp, xml_utils.parse_describe_regions, DescribeRegionsResult)
+
 class Bucket(_Base):
     """用于Bucket和Object操作的类，诸如创建、删除Bucket，上传、下载Object等。
 

oss2/models.py

@@ -2650,9 +2650,35 @@ def __init__(self, name=None, content=None, create_time=None, last_modify_time=N
 class ListBucketStyleResult(RequestResult):
     """查询图片样式信息列表的容器。
 
-    :param str styles: 图片样式内容的容器。元素类型为:class:`ListBucketStyleResult <oss2.models.ListBucketStyleResult>`。
+    :param str styles: 图片样式内容的容器。元素类型为:class:`BucketStyleInfo <oss2.models.BucketStyleInfo>`。
     """
 
     def __init__(self, resp):
         super(ListBucketStyleResult, self).__init__(resp)
-        self.styles = []
+        self.styles = []
+
+
+class RegionInfo(RequestResult):
+    """地域信息。
+
+    :param region: 地域ID。
+    :param internet_endpoint: 地域对应的外网Endpoint。
+    :param internal_endpoint: 地域对应的内网Endpoint。
+    :param accelerate_endpoint: 地域对应的传输加速Endpoint。取值固定为oss-accelerate.aliyuncs.com。
+    """
+    def __init__(self, region=None, internet_endpoint=None, internal_endpoint=None, accelerate_endpoint=None):
+        self.region = region
+        self.internet_endpoint = internet_endpoint
+        self.internal_endpoint = internal_endpoint
+        self.accelerate_endpoint = accelerate_endpoint
+
+
+class DescribeRegionsResult(RequestResult):
+    """地域信息列表。
+
+    :param list regions: 地域信息列表。元素类型为:class:`RegionInfo <oss2.models.RegionInfo>`。
+    """
+
+    def __init__(self, resp):
+        super(DescribeRegionsResult, self).__init__(resp)
+        self.regions = []

oss2/xml_utils.py

@@ -73,7 +73,8 @@
                      LifecycleFilter,
                      FilterNot,
                      FilterNotTag,
-                     BucketStyleInfo)
+                     BucketStyleInfo,
+                     RegionInfo)
 
 from .select_params import (SelectJsonTypes, SelectParameters)
 
@@ -2009,4 +2010,15 @@ def parse_list_bucket_style(result, body):
         tmp.create_time = _find_tag_with_default(style, 'CreateTime', None)
         tmp.last_modify_time = _find_tag_with_default(style, 'LastModifyTime', None)
 
-        result.styles.append(tmp)
+        result.styles.append(tmp)
+
+def parse_describe_regions(result, body):
+    root = ElementTree.fromstring(body)
+    for region in root.findall('RegionInfo'):
+        tmp = RegionInfo()
+        tmp.region = _find_tag_with_default(region, 'Region', None)
+        tmp.internet_endpoint = _find_tag_with_default(region, 'InternetEndpoint', None)
+        tmp.internal_endpoint = _find_tag_with_default(region, 'InternalEndpoint', None)
+        tmp.accelerate_endpoint = _find_tag_with_default(region, 'AccelerateEndpoint', None)
+
+        result.regions.append(tmp)

tests/test_bucket_describe_regions.py

@@ -0,0 +1,34 @@
+from .common import *
+
+class TestDescribeRegions(OssTestCase):
+    def test_describe_regions_normal(self):
+
+        service = oss2.Service(oss2.Auth(OSS_ID, OSS_SECRET), OSS_ENDPOINT)
+        result = service.describe_regions()
+        self.assertEqual(200, result.status)
+
+        exist_region = False
+        for r in result.regions:
+            if 'oss-cn-chengdu' == r.region:
+                exist_region = True
+        self.assertTrue(exist_region)
+
+        exist_region = False
+        result = service.describe_regions('oss-cn-chengdu')
+        self.assertEqual(200, result.status)
+        for r in result.regions:
+            if 'oss-cn-chengdu' == r.region:
+                exist_region = True
+
+        self.assertTrue(exist_region)
+
+    def test_describe_regions_exception(self):
+        try:
+            service = oss2.Service(oss2.Auth(OSS_ID, OSS_SECRET), OSS_ENDPOINT)
+            service.describe_regions('aaa')
+        except oss2.exceptions.ServerError as e:
+            self.assertEqual(e.code, 'NoSuchRegion')
+
+
+if __name__ == '__main__':
+    unittest.main()

unittests/test_bucket.py

@@ -2399,7 +2399,50 @@ def test_get_black_referer2(self, do_request):
         self.assertEqual(result.allow_empty_referer, True)
         self.assertSortedListEqual(result.referers, ['http://hello.com', 'mibrowser:home', '阿里巴巴'])
 
+    @patch('oss2.Session.do_request')
+    def test_describe_regions(self, do_request):
+        request_text = '''GET /?regions HTTP/1.1
+Date: Fri , 30 Apr 2021 13:08:38 GMT
+Content-Length：443
+Host: oss-cn-hangzhou.aliyuncs.com
+Authorization: OSS qn6qrrqxo2oawuk53otf****:PYbzsdWAIWAlMW8luk****'''
+
+        response_text = '''HTTP/1.1 200 OK
+x-oss-request-id: 566B6BD927A4046E9C725578
+Date: Fri , 30 Apr 2021 13:08:38 GMT
 
+<?xml version="1.0" encoding="UTF-8"?>
+<RegionInfoList>
+  <RegionInfo>
+     <Region>oss-cn-hangzhou</Region>
+     <InternetEndpoint>oss-cn-hangzhou.aliyuncs.com</InternetEndpoint>
+     <InternalEndpoint>oss-cn-hangzhou-internal.aliyuncs.com</InternalEndpoint>
+     <AccelerateEndpoint>oss-accelerate.aliyuncs.com</AccelerateEndpoint>  
+  </RegionInfo>
+  <RegionInfo>
+     <Region>oss-cn-shanghai</Region>
+     <InternetEndpoint>oss-cn-shanghai.aliyuncs.com</InternetEndpoint>
+     <InternalEndpoint>oss-cn-shanghai-internal.aliyuncs.com</InternalEndpoint>
+     <AccelerateEndpoint>oss-accelerate.aliyuncs.com</AccelerateEndpoint>  
+  </RegionInfo>
+</RegionInfoList>
+'''
+
+        req_info = mock_response(do_request, response_text)
 
+        result = service().describe_regions()
+
+        self.assertRequest(req_info, request_text)
+        self.assertEqual(result.request_id, '566B6BD927A4046E9C725578')
+        self.assertEqual(result.status, 200)
+        self.assertEqual(result.regions[0].region, 'oss-cn-hangzhou')
+        self.assertEqual(result.regions[0].internet_endpoint, 'oss-cn-hangzhou.aliyuncs.com')
+        self.assertEqual(result.regions[0].internal_endpoint, 'oss-cn-hangzhou-internal.aliyuncs.com')
+        self.assertEqual(result.regions[0].accelerate_endpoint, 'oss-accelerate.aliyuncs.com')
+        self.assertEqual(result.regions[1].region, 'oss-cn-shanghai')
+        self.assertEqual(result.regions[1].internet_endpoint, 'oss-cn-shanghai.aliyuncs.com')
+        self.assertEqual(result.regions[1].internal_endpoint, 'oss-cn-shanghai-internal.aliyuncs.com')
+        self.assertEqual(result.regions[1].accelerate_endpoint, 'oss-accelerate.aliyuncs.com')
+        
 if __name__ == '__main__':
     unittest.main()