Code review: 316120043: Update docstrings to new style #76

config/dpkg/changelog

@@ -1,5 +1,5 @@
-dfvfs (20161113-1) unstable; urgency=low
+dfvfs (20170116-1) unstable; urgency=low
 
   * Auto-generated
 
- -- Log2Timeline <[email protected]>  Sun, 13 Nov 2016 08:31:17 +0100
+ -- Log2Timeline <[email protected]>  Mon, 16 Jan 2017 19:26:57 +0100

dfvfs/__init__.py

@@ -6,4 +6,4 @@
 storage media types and file formats.
 """
 
-__version__ = '20161113'
+__version__ = '20170116'

dfvfs/compression/bzip2_decompressor.py

@@ -26,7 +26,7 @@ def Decompress(self, compressed_data):
       compressed_data (bytes): compressed data.
 
     Returns:
-      tuple(bytes,bytes): uncompressed data and remaining compressed data.
+      tuple(bytes, bytes): uncompressed data and remaining compressed data.
 
     Raises:
       BackEndError: if the BZIP2 compressed stream cannot be decompressed.

dfvfs/compression/decompressor.py

@@ -15,5 +15,5 @@ def Decompress(self, compressed_data):
       compressed_data (bytes): compressed data.
 
     Returns:
-      tuple(bytes,bytes): uncompressed data and remaining compressed data.
+      tuple(bytes, bytes): uncompressed data and remaining compressed data.
     """

dfvfs/compression/xz_decompressor.py

@@ -35,7 +35,7 @@ def Decompress(self, compressed_data):
       compressed_data (bytes): compressed data.
 
     Returns:
-      tuple(bytes,bytes): uncompressed data and remaining compressed data.
+      tuple(bytes, bytes): uncompressed data and remaining compressed data.
 
     Raises:
       BackEndError: if the XZ compressed stream cannot be decompressed.

dfvfs/compression/zlib_decompressor.py

@@ -32,7 +32,7 @@ def Decompress(self, compressed_data):
       compressed_data (bytes): compressed data.
 
     Returns:
-      tuple(bytes,bytes): uncompressed data and remaining compressed data.
+      tuple(bytes, bytes): uncompressed data and remaining compressed data.
 
     Raises:
       BackEndError: if the zlib compressed stream cannot be decompressed.

dfvfs/encoding/base16_decoder.py

@@ -22,7 +22,7 @@ def Decode(self, encoded_data):
       encoded_data (byte): encoded data.
 
     Returns:
-      tuple(bytes,bytes): decoded data and remaining encoded data.
+      tuple(bytes, bytes): decoded data and remaining encoded data.
 
     Raises:
       BackEndError: if the base16 stream cannot be decoded.

dfvfs/encoding/base32_decoder.py

@@ -22,7 +22,7 @@ def Decode(self, encoded_data):
       encoded_data (byte): encoded data.
 
     Returns:
-      tuple(bytes,bytes): decoded data and remaining encoded data.
+      tuple(bytes, bytes): decoded data and remaining encoded data.
 
     Raises:
       BackEndError: if the base32 stream cannot be decoded.

dfvfs/encoding/base64_decoder.py

@@ -22,7 +22,7 @@ def Decode(self, encoded_data):
       encoded_data (byte): encoded data.
 
     Returns:
-      tuple(bytes,bytes): decoded data and remaining encoded data.
+      tuple(bytes, bytes): decoded data and remaining encoded data.
 
     Raises:
       BackEndError: if the base64 stream cannot be decoded.

dfvfs/encoding/decoder.py

@@ -15,5 +15,5 @@ def Decode(self, encoded_data):
       encoded_data (byte): encoded data.
 
     Returns:
-      tuple(bytes,bytes): decoded data and remaining encoded data.
+      tuple(bytes, bytes): decoded data and remaining encoded data.
     """

dfvfs/file_io/bde_file_io.py

@@ -23,7 +23,7 @@ def _OpenFileObject(self, path_spec):
       path_spec (PathSpec): path specification.
 
     Returns:
-      A file-like object.
+      pyvde.volume: BDE volume file-like object.
 
     Raises:
       PathSpecError: if the path specification is incorrect.

dfvfs/file_io/compressed_stream_io.py

@@ -23,9 +23,9 @@ def __init__(
     file-like object.
 
     Args:
-      resolver_context: the resolver context (instance of resolver.Context).
-      compression_method: optional method used to the compress the data.
-      file_object: optional parent file-like object.
+      resolver_context (Context): resolver context.
+      compression_method (Optional[str]): method used to the compress the data.
+      file_object (Optional[file]): parent file-like object.
 
     Raises:
       ValueError: if file_object provided but compression_method is not.
@@ -68,12 +68,20 @@ def _Close(self):
     self._decompressor = None
 
   def _GetDecompressor(self):
-    """Retrieves the decompressor."""
+    """Retrieves the decompressor.
+
+    Returns:
+      Decompressor: decompressor.
+    """
     return compression_manager.CompressionManager.GetDecompressor(
         self._compression_method)
 
   def _GetUncompressedStreamSize(self):
-    """Retrieves the uncompressed stream size."""
+    """Retrieves the uncompressed stream size.
+
+    Returns:
+      int: uncompressed stream size.
+    """
     self._file_object.seek(0, os.SEEK_SET)
 
     self._decompressor = self._GetDecompressor()
@@ -97,8 +105,8 @@ def _Open(self, path_spec=None, mode='rb'):
     """Opens the file-like object.
 
     Args:
-      path_spec: optional path specification (instance of PathSpec).
-      mode: optional file access mode. The default is 'rb' read-only binary.
+      path_spec (Optional[PathSpec]): path specification.
+      mode (Optional[str]): file access mode.
 
     Raises:
       AccessError: if the access to open the file was denied.
@@ -127,7 +135,7 @@ def _AlignUncompressedDataOffset(self, uncompressed_data_offset):
     """Aligns the compressed file with the uncompressed data offset.
 
     Args:
-      uncompressed_data_offset: the uncompressed data offset.
+      uncompressed_data_offset (int): uncompressed data offset.
     """
     self._file_object.seek(0, os.SEEK_SET)
 
@@ -154,10 +162,10 @@ def _ReadCompressedData(self, read_size):
     """Reads compressed data from the file-like object.
 
     Args:
-      read_size: the number of bytes of compressed data to read.
+      read_size (int): number of bytes of compressed data to read.
 
     Returns:
-      The number of bytes of compressed data read.
+      int: number of bytes of compressed data read.
     """
     compressed_data = self._file_object.read(read_size)
 
@@ -182,11 +190,11 @@ def read(self, size=None):
     all of the remaining data if no size was specified.
 
     Args:
-      size: Optional integer value containing the number of bytes to read.
-            Default is all remaining data (None).
+      size (Optional[int]): number of bytes to read, where None is all
+          remaining data.
 
     Returns:
-      A byte string containing the data read.
+      bytes: data read.
 
     Raises:
       IOError: if the read failed.
@@ -255,12 +263,12 @@ def read(self, size=None):
     return uncompressed_data
 
   def seek(self, offset, whence=os.SEEK_SET):
-    """Seeks an offset within the file-like object.
+    """Seeks to an offset within the file-like object.
 
     Args:
-      offset: the offset to seek.
-      whence: optional value that indicates whether offset is an absolute
-              or relative position within the file.
+      offset (int): offset to seek to.
+      whence (Optional(int)): value that indicates whether offset is an absolute
+          or relative position within the file.
 
     Raises:
       IOError: if the seek failed.
@@ -287,7 +295,10 @@ def seek(self, offset, whence=os.SEEK_SET):
       self._realign_offset = True
 
   def get_offset(self):
-    """Returns the current offset into the file-like object.
+    """Retrieves the current offset into the file-like object.
+
+    Returns:
+      int: current offset in the uncompressed stream.
 
     Raises:
       IOError: if the file-like object has not been opened.
@@ -298,7 +309,10 @@ def get_offset(self):
     return self._current_offset
 
   def get_size(self):
-    """Returns the size of the file-like object.
+    """Retrieves the size of the file-like object.
+
+    Returns:
+      int: size of the uncompressed stream.
 
     Raises:
       IOError: if the file-like object has not been opened.

dfvfs/file_io/cpio_file_io.py

@@ -14,7 +14,7 @@ def __init__(self, resolver_context):
     """Initializes the file-like object.
 
     Args:
-      resolver_context: the resolver context (instance of resolver.Context).
+      resolver_context (Context): resolver context.
     """
     super(CPIOFile, self).__init__(resolver_context)
     self._cpio_archive_file = None
@@ -35,8 +35,8 @@ def _Open(self, path_spec=None, mode='rb'):
     """Opens the file-like object defined by path specification.
 
     Args:
-      path_spec: optional the path specification (instance of PathSpec).
-      mode: optional file access mode. The default is 'rb' read-only binary.
+      path_spec (Optional[PathSpec]): path specification.
+      mode (Optional[str]): file access mode.
 
     Raises:
       AccessError: if the access to open the file was denied.
@@ -71,11 +71,11 @@ def read(self, size=None):
     all of the remaining data if no size was specified.
 
     Args:
-      size: optional integer value containing the number of bytes to read.
-            Default is all remaining data (None).
+      size (Optional[int]): number of bytes to read, where None is all
+          remaining data.
 
     Returns:
-      A byte string containing the data read.
+      bytes: data read.
 
     Raises:
       IOError: if the read failed.
@@ -103,12 +103,12 @@ def read(self, size=None):
     return data
 
   def seek(self, offset, whence=os.SEEK_SET):
-    """Seeks an offset within the file-like object.
+    """Seeks to an offset within the file-like object.
 
     Args:
-      offset: the offset to seek.
-      whence: optional value that indicates whether offset is an absolute
-              or relative position within the file. Default is SEEK_SET.
+      offset (int): offset to seek to.
+      whence (Optional(int)): value that indicates whether offset is an absolute
+          or relative position within the file.
 
     Raises:
       IOError: if the seek failed.
@@ -129,7 +129,10 @@ def seek(self, offset, whence=os.SEEK_SET):
     self._current_offset = offset
 
   def get_offset(self):
-    """Returns the current offset into the file-like object.
+    """Retrieves the current offset into the file-like object.
+
+    Returns:
+      int: current offset in the CPIO archived file.
 
     Raises:
       IOError: if the file-like object has not been opened.
@@ -140,7 +143,10 @@ def get_offset(self):
     return self._current_offset
 
   def get_size(self):
-    """Returns the size of the file-like object.
+    """Retrieves the size of the file-like object.
+
+    Returns:
+      int: size of the CPIO archived file.
 
     Raises:
       IOError: if the file-like object has not been opened.