pybind/rados: use type annotation for rtype docstring

some docstrings in rados.pyx put the type of return value like

:returns: str - value of the option or None

since we can also annotate the type of the return value using type
annotations, in this change, the rtype is annotated using type
annotations.

Signed-off-by: Kefu Chai <kchai@redhat.com>

diff --git a/src/pybind/rados/rados.pyx b/src/pybind/rados/rados.pyx
index 0c300ca4047782b36826b390533f742572145671..dc07e27aa2363836c204b19bb5c2184cb2dd4a31 100644 (file)
--- a/src/pybind/rados/rados.pyx
+++ b/src/pybind/rados/rados.pyx
@@ -273,7 +273,7 @@ cdef make_ex(ret: int, msg: str):
         return OSError(msg, errno=ret)
 
 
-def cstr(val, name, encoding="utf-8", opt=False):
+def cstr(val, name, encoding="utf-8", opt=False) -> Optional[bytes]:
     """
     Create a byte string from a Python string
 
@@ -281,7 +281,6 @@ def cstr(val, name, encoding="utf-8", opt=False):
     :param str name: Name of the string parameter, for exceptions
     :param str encoding: Encoding to use
     :param bool opt: If True, None is allowed
-    :rtype: bytes
     :raises: :class:`InvalidArgument`
     """
     if opt and val is None:
@@ -298,12 +297,11 @@ def cstr_list(list_str, name, encoding="utf-8"):
     return [cstr(s, name) for s in list_str]
 
 
-def decode_cstr(val, encoding="utf-8"):
+def decode_cstr(val, encoding="utf-8") -> Optional[str]:
     """
     Decode a byte string into a Python string.
 
     :param bytes val: byte string
-    :rtype: str or None
     """
     if val is None:
         return None
@@ -581,7 +579,7 @@ Rados object in state %s." % self.state)
 
         :param option: which option to read
 
-        :returns: str - value of the option or None
+        :returns: value of the option or None
         :raises: :class:`TypeError`
         """
         self.require_state("configuring", "connected")
@@ -689,8 +687,7 @@ Rados object in state %s." % self.state)
         This tells you total space, space used, space available, and number
         of objects. These are not updated immediately when data is written,
         they are eventually consistent.
-
-        :returns: dict - contains the following keys:
+        :returns: contains the following keys:
 
             - ``kb`` (int) - total space
 
@@ -722,7 +719,7 @@ Rados object in state %s." % self.state)
         :param pool_name: name of the pool to check
 
         :raises: :class:`TypeError`, :class:`Error`
-        :returns: bool - whether the pool exists, false otherwise.
+        :returns: whether the pool exists, false otherwise.
         """
         self.require_state("connected")
 
@@ -746,7 +743,7 @@ Rados object in state %s." % self.state)
         :param pool_name: name of the pool to look up
 
         :raises: :class:`TypeError`, :class:`Error`
-        :returns: int - pool ID, or None if it doesn't exist
+        :returns: pool ID, or None if it doesn't exist
         """
         self.require_state("connected")
         pool_name_raw = cstr(pool_name, 'pool_name')
@@ -762,14 +759,14 @@ Rados object in state %s." % self.state)
         else:
             raise make_ex(ret, "error looking up pool '%s'" % pool_name)
 
-    def pool_reverse_lookup(self, pool_id: int):
+    def pool_reverse_lookup(self, pool_id: int) -> Optional[str]:
         """
         Returns a pool's name based on its ID.
 
         :param pool_id: ID of the pool to look up
 
         :raises: :class:`TypeError`, :class:`Error`
-        :returns: string - pool name, or None if it doesn't exist
+        :returns: pool name, or None if it doesn't exist
         """
         self.require_state("connected")
         cdef:
@@ -883,7 +880,7 @@ Rados object in state %s." % self.state)
         List inconsistent placement groups in the given pool
 
         :param pool_id: ID of the pool in which PGs are listed
-        :returns: list - inconsistent placement groups
+        :returns: inconsistent placement groups
         """
         self.require_state("connected")
         cdef:
@@ -911,7 +908,7 @@ Rados object in state %s." % self.state)
         """
         Gets a list of pool names.
 
-        :returns: list - of pool names.
+        :returns: list of pool names.
         """
         self.require_state("connected")
         cdef:
@@ -937,7 +934,7 @@ Rados object in state %s." % self.state)
         Get the fsid of the cluster as a hexadecimal string.
 
         :raises: :class:`Error`
-        :returns: str - cluster fsid
+        :returns: cluster fsid
         """
         self.require_state("connected")
         cdef:
@@ -969,7 +966,7 @@ Rados object in state %s." % self.state)
         :param ioctx_name: name of the pool
 
         :raises: :class:`TypeError`, :class:`Error`
-        :returns: Ioctx - Rados Ioctx object
+        :returns: Rados Ioctx object
         """
         self.require_state("connected")
         ioctx_name_raw = cstr(ioctx_name, 'ioctx_name')
@@ -994,7 +991,7 @@ Rados object in state %s." % self.state)
         :param pool_id: ID of the pool
 
         :raises: :class:`TypeError`, :class:`Error`
-        :returns: Ioctx - Rados Ioctx object
+        :returns: Rados Ioctx object
         """
         self.require_state("connected")
         cdef:
@@ -1517,15 +1514,15 @@ ioctx '%s'" % self.ioctx.name)
             num_snaps = num_snaps * 2
         self.cur_snap = 0
 
-    def __iter__(self):
+    def __iter__(self) -> 'SnapIterator':
         return self
 
-    def __next__(self):
+    def __next__(self) -> 'Snap':
         """
         Get the next Snapshot
 
         :raises: :class:`Error`, StopIteration
-        :returns: Snap - next snapshot
+        :returns: next snapshot
         """
         if self.cur_snap >= self.max_snap:
             raise StopIteration
@@ -1577,7 +1574,7 @@ cdef class Snap(object):
         Find when a snapshot in the current pool occurred
 
         :raises: :class:`Error`
-        :returns: datetime - the data and time the snapshot was created
+        :returns: the data and time the snapshot was created
         """
         cdef time_t snap_time
 
@@ -1673,7 +1670,7 @@ cdef class Completion(object):
         The return value is set when the operation is complete or safe,
         whichever comes first.
 
-        :returns: int - return value of the operation
+        :returns: return value of the operation
         """
         with nogil:
             ret = rados_aio_get_return_value(self.rados_comp)
@@ -2868,7 +2865,7 @@ returned %d, but should return zero on success." % (self.name, ret))
 
         :raises: :class:`TypeError`
         :raises: :class:`Error`
-        :returns: str - data read from object
+        :returns: data read from object
         """
         self.require_ioctx_open()
         key_raw = cstr(key, 'key')
@@ -2952,7 +2949,7 @@ returned %d, but should return zero on success." % (self.name, ret))
         """
         Get pool usage statistics
 
-        :returns: dict - contains the following keys:
+        :returns: dict contains the following keys:
 
             - ``num_bytes`` (int) - size of pool in bytes
 
@@ -3008,7 +3005,7 @@ returned %d, but should return zero on success." % (self.name, ret))
 
         :raises: :class:`TypeError`
         :raises: :class:`Error`
-        :returns: bool - True on success
+        :returns: True on success
         """
         self.require_ioctx_open()
         key_raw = cstr(key, 'key')
@@ -3021,7 +3018,7 @@ returned %d, but should return zero on success." % (self.name, ret))
             raise make_ex(ret, "Failed to remove '%s'" % key)
         return True
 
-    def trunc(self, key: str, size: int):
+    def trunc(self, key: str, size: int) -> int:
         """
         Resize an object
 
@@ -3033,7 +3030,7 @@ returned %d, but should return zero on success." % (self.name, ret))
 
         :raises: :class:`TypeError`
         :raises: :class:`Error`
-        :returns: int - 0 on success, otherwise raises error
+        :returns: 0 on success, otherwise raises error
         """
 
         self.require_ioctx_open()
@@ -3105,7 +3102,7 @@ returned %d, but should return zero on success." % (self.name, ret))
 
         :raises: :class:`TypeError`
         :raises: :class:`Error`
-        :returns: str - value of the xattr
+        :returns: value of the xattr
         """
         self.require_ioctx_open()
 
@@ -3155,7 +3152,7 @@ returned %d, but should return zero on success." % (self.name, ret))
 
         :raises: :class:`TypeError`
         :raises: :class:`Error`
-        :returns: bool - True on success, otherwise raise an error
+        :returns: True on success, otherwise raise an error
         """
         self.require_ioctx_open()
 
@@ -3183,7 +3180,7 @@ returned %d, but should return zero on success." % (self.name, ret))
 
         :raises: :class:`TypeError`
         :raises: :class:`Error`
-        :returns: bool - True on success, otherwise raise an error
+        :returns: True on success, otherwise raise an error
         """
         self.require_ioctx_open()
 
@@ -3210,7 +3207,7 @@ returned %d, but should return zero on success." % (self.name, ret))
 
         :raises: :class:`TypeError`
         :raises: :class:`Error`
-        :returns: bool - True on success, otherwise raise an error
+        :returns: True on success, otherwise raise an error
         """
         self.require_ioctx_open()
 
@@ -3333,7 +3330,7 @@ returned %d, but should return zero on success." % (self.name, ret))
         """
         Get pool name
 
-        :returns: str - pool name
+        :returns: pool name
         """
         cdef:
             int name_len = 10