doc: add more type info to functions

Author: lihsai0

qiniu/config.py

@@ -19,7 +19,7 @@
     'default_uc_host': UC_HOST,
     'default_query_region_host': QUERY_REGION_HOST,
     'default_query_region_backup_hosts': QUERY_REGION_BACKUP_HOSTS,
-    'default_backup_hosts_retry_times': 3,  # 仅控制旧 Region 查询 Hosts 的重试次数
+    'default_backup_hosts_retry_times': 3,  # 仅控制旧区域 LegacyRegion 查询 Hosts 的重试次数
     'connection_timeout': 30,  # 链接超时为时间为30s
     'connection_retries': 3,  # 链接重试次数为3次
     'connection_pool': 10,  # 链接池个数为10

qiniu/http/endpoint.py

@@ -19,6 +19,12 @@ def from_host(host):
             return Endpoint(host=host)
 
     def __init__(self, host, default_scheme='https'):
+        """
+        Parameters
+        ----------
+        host: str
+        default_scheme: str
+        """
         self.host = host
         self.default_scheme = default_scheme
 
@@ -38,10 +44,24 @@ def __eq__(self, other):
         return self.host == other.host and self.default_scheme == other.default_scheme
 
     def get_value(self, scheme=None):
+        """
+        Parameters
+        ----------
+        scheme: str
+
+        Returns
+        -------
+        str
+        """
         scheme = scheme if scheme is not None else self.default_scheme
         return ''.join([scheme, '://', self.host])
 
     def clone(self):
+        """
+        Returns
+        -------
+        Endpoint
+        """
         return Endpoint(
             host=self.host,
             default_scheme=self.default_scheme

qiniu/http/endpoints_retry_policy.py

@@ -3,10 +3,25 @@
 
 class EndpointsRetryPolicy(RetryPolicy):
     def __init__(self, endpoints_provider=None, skip_init_context=False):
+        """
+        Parameters
+        ----------
+        endpoints_provider: Iterable[Endpoint]
+        skip_init_context: bool
+        """
         self.endpoints_provider = endpoints_provider if endpoints_provider else []
         self.skip_init_context = skip_init_context
 
     def init_context(self, context):
+        """
+        Parameters
+        ----------
+        context: dict
+
+        Returns
+        -------
+        None
+        """
         if self.skip_init_context:
             return
         context['alternative_endpoints'] = list(self.endpoints_provider)
@@ -15,9 +30,27 @@ def init_context(self, context):
         context['endpoint'] = context['alternative_endpoints'].pop(0)
 
     def should_retry(self, attempt):
+        """
+        Parameters
+        ----------
+        attempt: qiniu.retry.Attempt
+
+        Returns
+        -------
+        bool
+        """
         return len(attempt.context['alternative_endpoints']) > 0
 
     def prepare_retry(self, attempt):
+        """
+        Parameters
+        ----------
+        attempt: qiniu.retry.Attempt
+
+        Returns
+        -------
+        None
+        """
         if not attempt.context['alternative_endpoints']:
             raise Exception('There isn\'t available endpoint for next try')
         attempt.context['endpoint'] = attempt.context['alternative_endpoints'].pop(0)

qiniu/http/region.py

@@ -166,12 +166,22 @@ def __init__(
 
     @property
     def is_live(self):
+        """
+        Returns
+        -------
+        bool
+        """
         if self.ttl < 0:
             return True
         live_time = datetime.now() - self.create_time
         return live_time < timedelta(seconds=self.ttl)
 
     def clone(self):
+        """
+        Returns
+        -------
+        Region
+        """
         return Region(
             region_id=self.region_id,
             s3_region_id=self.s3_region_id,

qiniu/http/regions_provider.py

@@ -77,6 +77,15 @@ def __init__(
         preferred_scheme='http',
         max_retry_times_per_endpoint=1,
     ):
+        """
+        Parameters
+        ----------
+        access_key: str
+        bucket_name: str
+        endpoints_provider: Iterable[Endpoint]
+        preferred_scheme: str
+        max_retry_times_per_endpoint: int
+        """
         self.access_key = access_key
         self.bucket_name = bucket_name
         self.endpoints_provider = endpoints_provider
@@ -142,6 +151,11 @@ def __exit__(self, exc_type, exc_val, exc_tb):
 
     @property
     def lock_file_path(self):
+        """
+        Returns
+        -------
+        str
+        """
         return self._origin_file + '.lock'
 
 
@@ -290,6 +304,16 @@ def _get_service_name(k):
 
 
 def _parse_persisted_regions(persisted_data):
+    """
+    Parameters
+    ----------
+    persisted_data: str
+
+    Returns
+    -------
+    cache_key: str
+    regions: list[Region]
+    """
     parsed_data = json.loads(persisted_data)
     regions = [
         _get_region_from_persisted(d)
@@ -299,6 +323,16 @@ def _parse_persisted_regions(persisted_data):
 
 
 def _walk_persist_cache_file(persist_path, ignore_parse_error=False):
+    """
+    Parameters
+    ----------
+    persist_path: str
+    ignore_parse_error: bool
+
+    Returns
+    -------
+    Iterable[(str, list[Region])]
+    """
     if not os.access(persist_path, os.R_OK):
         return
 
@@ -397,6 +431,11 @@ def __iter__(self):
             yield r
 
     def set_regions(self, regions):
+        """
+        Parameters
+        ----------
+        regions: list[Region]
+        """
         self._cache_scope.memo_cache[self.cache_key] = regions
 
         if not self._cache_scope.persist_path:
@@ -557,6 +596,11 @@ def __flush_file_cache_to_memo(self):
 
     @property
     def __should_shrink(self):
+        """
+        Returns
+        -------
+        bool
+        """
         return self._cache_scope.last_shrink_at + self._cache_scope.shrink_interval >= datetime.datetime.now()
 
     def __shrink_cache(self):

qiniu/retry/attempt.py

@@ -1,5 +1,10 @@
 class Attempt:
     def __init__(self, custom_context=None):
+        """
+        Parameters
+        ----------
+        custom_context: dict or None
+        """
         self.context = custom_context if custom_context is not None else {}
         self.exception = None
         self.result = None

qiniu/services/storage/bucket.py

@@ -567,6 +567,15 @@ def change_bucket_permission(self, bucket_name, private):
         )
 
     def _get_regions_provider(self, bucket_name):
+        """
+        Parameters
+        ----------
+        bucket_name: str
+
+        Returns
+        -------
+        Iterable[Region]
+        """
         if self.regions:
             return self.regions
 
@@ -600,6 +609,17 @@ def _get_regions_provider(self, bucket_name):
         )
 
     def __uc_do_with_retrier(self, url_resource, data=None):
+        """
+        Parameters
+        ----------
+        url_resource: url
+        data: dict or None
+
+        Returns
+        -------
+        ret: dict or None
+        resp: ResponseInfo
+        """
         regions = self.regions
 
         # ignore self.zone by no uc in it
@@ -635,6 +655,20 @@ def __uc_do_with_retrier(self, url_resource, data=None):
         return attempt.result
 
     def __server_do_with_retrier(self, bucket_name, service_names, url_resource, data=None, method='POST'):
+        """
+        Parameters
+        ----------
+        bucket_name: str
+        service_names: List[ServiceName]
+        url_resource: str
+        data: dict or None
+        method: str
+
+        Returns
+        -------
+        ret: dict or None
+        resp: ResponseInfo
+        """
         if not service_names:
             raise ValueError('service_names is empty')
 
@@ -680,14 +714,49 @@ def _build_op(*args):
 
 
 def build_batch_copy(source_bucket, key_pairs, target_bucket, force='false'):
+    """
+    Parameters
+    ----------
+    source_bucket: str
+    key_pairs: dict
+    target_bucket: str
+    force: str
+
+    Returns
+    -------
+    list[str]
+    """
     return _two_key_batch('copy', source_bucket, key_pairs, target_bucket, force)
 
 
 def build_batch_rename(bucket, key_pairs, force='false'):
+    """
+    Parameters
+    ----------
+    bucket: str
+    key_pairs: dict
+    force: str
+
+    Returns
+    -------
+    list[str]
+    """
     return build_batch_move(bucket, key_pairs, bucket, force)
 
 
 def build_batch_move(source_bucket, key_pairs, target_bucket, force='false'):
+    """
+    Parameters
+    ----------
+    source_bucket: str
+    key_pairs: dict
+    target_bucket: str
+    force: str
+
+    Returns
+    -------
+    list[str]
+    """
     return _two_key_batch('move', source_bucket, key_pairs, target_bucket, force)
 
 
@@ -726,10 +795,30 @@ def build_batch_restore_ar(bucket, keys):
 
 
 def build_batch_delete(bucket, keys):
+    """
+    Parameters
+    ----------
+    bucket: str
+    keys: list[str]
+
+    Returns
+    -------
+    list[str]
+    """
     return _one_key_batch('delete', bucket, keys)
 
 
 def build_batch_stat(bucket, keys):
+    """
+    Parameters
+    ----------
+    bucket: str
+    keys: list[str]
+
+    Returns
+    -------
+    list[str]
+    """
     return _one_key_batch('stat', bucket, keys)