Port more docstrings to Google style.

dulwich/contrib/release_robot.py

@@ -59,8 +59,10 @@ PATTERN = r'[ a-zA-Z_\-]*([\d\.]+[\-\w\.]*)'
 def get_recent_tags(projdir=PROJDIR):
     """Get list of tags in order from newest to oldest and their datetimes.
 
-    :param projdir: path to ``.git``
+    Args:
-    :returns: list of tags sorted by commit time from newest to oldest
+      projdir: path to ``.git``
+    Returns:
+      list of tags sorted by commit time from newest to oldest
 
     Each tag in the list contains the tag name, commit time, commit id, author
     and any tag meta. If a tag isn't annotated, then its tag meta is ``None``.
@@ -115,10 +117,12 @@ def get_current_version(projdir=PROJDIR, pattern=PATTERN, logger=None):
     version. *EG*: "Release-0.2.1-rc.1" will be come "0.2.1-rc.1". If no match
     is found, then the most recent tag is return without modification.
 
-    :param projdir: path to ``.git``
+    Args:
-    :param pattern: regular expression pattern with group that matches version
+      projdir: path to ``.git``
-    :param logger: a Python logging instance to capture exception
+      pattern: regular expression pattern with group that matches version
-    :returns: tag matching first group in regular expression pattern
+      logger: a Python logging instance to capture exception
+    Returns:
+      tag matching first group in regular expression pattern
     """
     tags = get_recent_tags(projdir)
     try:

dulwich/contrib/swift.py

@@ -167,8 +167,9 @@ class PackInfoMissingObjectFinder(GreenThreadsMissingObjectFinder):
 def load_conf(path=None, file=None):
     """Load configuration in global var CONF
 
-    :param path: The path to the configuration file
+    Args:
-    :param file: If provided read instead the file like object
+      path: The path to the configuration file
+      file: If provided read instead the file like object
     """
     conf = ConfigParser()
     if file:
@@ -195,9 +196,10 @@ def load_conf(path=None, file=None):
 def swift_load_pack_index(scon, filename):
     """Read a pack index file from Swift
 
-    :param scon: a `SwiftConnector` instance
+    Args:
-    :param filename: Path to the index file objectise
+      scon: a `SwiftConnector` instance
-    :return: a `PackIndexer` instance
+      filename: Path to the index file objectise
+    Returns: a `PackIndexer` instance
     """
     with scon.get_object(filename) as f:
         return load_pack_index_file(filename, f)
@@ -248,8 +250,9 @@ class SwiftConnector(object):
     def __init__(self, root, conf):
         """ Initialize a SwiftConnector
 
-        :param root: The swift container that will act as Git bare repository
+        Args:
-        :param conf: A ConfigParser Object
+          root: The swift container that will act as Git bare repository
+          conf: A ConfigParser Object
         """
         self.conf = conf
         self.auth_ver = self.conf.get("swift", "auth_ver")
@@ -394,9 +397,10 @@ class SwiftConnector(object):
     def get_object_stat(self, name):
         """Retrieve object stat
 
-        :param name: The object name
+        Args:
-        :return: A dict that describe the object
+          name: The object name
-                 or None if object does not exist
+        Returns:
+          A dict that describe the object or None if object does not exist
         """
         path = self.base_path + '/' + name
         ret = self.httpclient.request('HEAD', path)
@@ -413,9 +417,11 @@ class SwiftConnector(object):
     def put_object(self, name, content):
         """Put an object
 
-        :param name: The object name
+        Args:
-        :param content: A file object
+          name: The object name
-        :raise: `SwiftException` if unable to create
+          content: A file object
+        Raises:
+          SwiftException: if unable to create
         """
         content.seek(0)
         data = content.read()
@@ -442,11 +448,12 @@ class SwiftConnector(object):
     def get_object(self, name, range=None):
         """Retrieve an object
 
-        :param name: The object name
+        Args:
-        :param range: A string range like "0-10" to
+          name: The object name
-                      retrieve specified bytes in object content
+          range: A string range like "0-10" to
-        :return: A file like instance
+                 retrieve specified bytes in object content
-                 or bytestring if range is specified
+        Returns:
+          A file like instance or bytestring if range is specified
         """
         headers = {}
         if range:
@@ -467,8 +474,10 @@ class SwiftConnector(object):
     def del_object(self, name):
         """Delete an object
 
-        :param name: The object name
+        Args:
-        :raise: `SwiftException` if unable to delete
+          name: The object name
+        Raises:
+          SwiftException: if unable to delete
         """
         path = self.base_path + '/' + name
         ret = self.httpclient.request('DELETE', path)
@@ -502,9 +511,10 @@ class SwiftPackReader(object):
     def __init__(self, scon, filename, pack_length):
         """Initialize a SwiftPackReader
 
-        :param scon: a `SwiftConnector` instance
+        Args:
-        :param filename: the pack filename
+          scon: a `SwiftConnector` instance
-        :param pack_length: The size of the pack object
+          filename: the pack filename
+          pack_length: The size of the pack object
         """
         self.scon = scon
         self.filename = filename
@@ -525,8 +535,10 @@ class SwiftPackReader(object):
     def read(self, length):
         """Read a specified amount of Bytes form the pack object
 
-        :param length: amount of bytes to read
+        Args:
-        :return: bytestring
+          length: amount of bytes to read
+        Returns:
+          a bytestring
         """
         end = self.offset+length
         if self.base_offset + end > self.pack_length:
@@ -544,7 +556,8 @@ class SwiftPackReader(object):
     def seek(self, offset):
         """Seek to a specified offset
 
-        :param offset: the offset to seek to
+        Args:
+          offset: the offset to seek to
         """
         self.base_offset = offset
         self._read()
@@ -568,8 +581,9 @@ class SwiftPackData(PackData):
     def __init__(self, scon, filename):
         """ Initialize a SwiftPackReader
 
-        :param scon: a `SwiftConnector` instance
+        Args:
-        :param filename: the pack filename
+          scon: a `SwiftConnector` instance
+          filename: the pack filename
         """
         self.scon = scon
         self._filename = filename
@@ -639,7 +653,8 @@ class SwiftObjectStore(PackBasedObjectStore):
     def __init__(self, scon):
         """Open a Swift object store.
 
-        :param scon: A `SwiftConnector` instance
+        Args:
+          scon: A `SwiftConnector` instance
         """
         super(SwiftObjectStore, self).__init__()
         self.scon = scon
@@ -901,8 +916,9 @@ class SwiftRepo(BaseRepo):
         `SwiftInfoRefsContainer`. The root attribute is the Swift
         container that contain the Git bare repository.
 
-        :param root: The container which contains the bare repo
+        Args:
-        :param conf: A ConfigParser object
+          root: The container which contains the bare repo
+          conf: A ConfigParser object
         """
         self.root = root.lstrip('/')
         self.conf = conf
@@ -929,8 +945,9 @@ class SwiftRepo(BaseRepo):
     def _put_named_file(self, filename, contents):
         """Put an object in a Swift container
 
-        :param filename: the path to the object to put on Swift
+        Args:
-        :param contents: the content as bytestring
+          filename: the path to the object to put on Swift
+          contents: the content as bytestring
         """
         with BytesIO() as f:
             f.write(contents)
@@ -940,9 +957,11 @@ class SwiftRepo(BaseRepo):
     def init_bare(cls, scon, conf):
         """Create a new bare repository.
 
-        :param scon: a `SwiftConnector` instance
+        Args:
-        :param conf: a ConfigParser object
+          scon: a `SwiftConnector` instance
-        :return: a `SwiftRepo` instance
+          conf: a ConfigParser object
+        Returns:
+          a `SwiftRepo` instance
         """
         scon.create_root()
         for obj in [posixpath.join(OBJECTDIR, PACKDIR),

dulwich/ignore.py

@@ -197,8 +197,10 @@ class IgnoreFilter(object):
     def find_matching(self, path):
         """Yield all matching patterns for path.
 
-        :param path: Path to match
+        Args:
-        :return: Iterator over  iterators
+          path: Path to match
+        Returns:
+          Iterator over  iterators
         """
         if not isinstance(path, bytes):
             path = path.encode(sys.getfilesystemencoding())
@@ -242,9 +244,11 @@ class IgnoreFilterStack(object):
     def is_ignored(self, path):
         """Check whether a path is explicitly included or excluded in ignores.
 
-        :param path: Path to check
+        Args:
-        :return: None if the file is not mentioned, True if it is included,
+          path: Path to check
-            False if it is explicitly excluded.
+        Returns:
+          None if the file is not mentioned, True if it is included,
+          False if it is explicitly excluded.
         """
         status = None
         for filter in self._filters:
@@ -257,8 +261,10 @@ class IgnoreFilterStack(object):
 def default_user_ignore_filter_path(config):
     """Return default user ignore filter path.
 
-    :param config: A Config object
+    Args:
-    :return: Path to a global ignore file
+      config: A Config object
+    Returns:
+      Path to a global ignore file
     """
     try:
         return config.get((b'core', ), b'excludesFile')
@@ -305,8 +311,10 @@ class IgnoreFilterManager(object):
 
         Stops after the first ignore file with matches.
 
-        :param path: Path to check
+        Args:
-        :return: Iterator over Pattern instances
+          path: Path to check
+        Returns:
+          Iterator over Pattern instances
         """
         if os.path.isabs(path):
             raise ValueError('%s is an absolute path' % path)
@@ -333,9 +341,11 @@ class IgnoreFilterManager(object):
     def is_ignored(self, path):
         """Check whether a path is explicitly included or excluded in ignores.
 
-        :param path: Path to check
+        Args:
-        :return: None if the file is not mentioned, True if it is included,
+          path: Path to check
-            False if it is explicitly excluded.
+        Returns:
+          None if the file is not mentioned, True if it is included,
+          False if it is explicitly excluded.
         """
         matches = list(self.find_matching(path))
         if matches:
@@ -346,8 +356,10 @@ class IgnoreFilterManager(object):
     def from_repo(cls, repo):
         """Create a IgnoreFilterManager from a repository.
 
-        :param repo: Repository object
+        Args:
-        :return: A `IgnoreFilterManager` object
+          repo: Repository object
+        Returns:
+          A `IgnoreFilterManager` object
         """
         global_filters = []
         for p in [

dulwich/index.py

@@ -56,8 +56,10 @@ FLAG_EXTENDED = 0x4000
 def pathsplit(path):
     """Split a /-delimited path into a directory part and a basename.
 
-    :param path: The path to split.
+    Args:
-    :return: Tuple with directory name and basename
+      path: The path to split.
+    Returns:
+      Tuple with directory name and basename
     """
     try:
         (dirname, basename) = path.rsplit(b"/", 1)
@@ -77,8 +79,10 @@ def pathjoin(*args):
 def read_cache_time(f):
     """Read a cache time.
 
-    :param f: File-like object to read from
+    Args:
-    :return: Tuple with seconds and nanoseconds
+      f: File-like object to read from
+    Returns:
+      Tuple with seconds and nanoseconds
     """
     return struct.unpack(">LL", f.read(8))
 
@@ -86,8 +90,9 @@ def read_cache_time(f):
 def write_cache_time(f, t):
     """Write a cache time.
 
-    :param f: File-like object to write to
+    Args:
-    :param t: Time to write (as int, float or tuple with secs and nsecs)
+      f: File-like object to write to
+      t: Time to write (as int, float or tuple with secs and nsecs)
     """
     if isinstance(t, int):
         t = (t, 0)
@@ -102,8 +107,10 @@ def write_cache_time(f, t):
 def read_cache_entry(f):
     """Read an entry from a cache file.
 
-    :param f: File-like object to read from
+    Args:
-    :return: tuple with: device, inode, mode, uid, gid, size, sha, flags
+      f: File-like object to read from
+    Returns:
+      tuple with: device, inode, mode, uid, gid, size, sha, flags
     """
     beginoffset = f.tell()
     ctime = read_cache_time(f)
@@ -121,8 +128,9 @@ def read_cache_entry(f):
 def write_cache_entry(f, entry):
     """Write an index entry to a file.
 
-    :param f: File object
+    Args:
-    :param entry: Entry to write, tuple with:
+      f: File object
+      entry: Entry to write, tuple with:
         (name, ctime, mtime, dev, ino, mode, uid, gid, size, sha, flags)
     """
     beginoffset = f.tell()
@@ -152,7 +160,8 @@ def read_index(f):
 def read_index_dict(f):
     """Read an index file and return it as a dictionary.
 
-    :param f: File object to read from
+    Args:
+      f: File object to read from
     """
     ret = {}
     for x in read_index(f):

dulwich/porcelain.py

@@ -1191,16 +1191,18 @@ def fetch(repo, remote_location, remote_name=b'origin', outstream=sys.stdout,
           prune=False, prune_tags=False, **kwargs):
     """Fetch objects from a remote server.
 
-    :param repo: Path to the repository
+    Args:
-    :param remote_location: String identifying a remote server
+      repo: Path to the repository
-    :param remote_name: Name for remote server
+      remote_location: String identifying a remote server
-    :param outstream: Output stream (defaults to stdout)
+      remote_name: Name for remote server
-    :param errstream: Error stream (defaults to stderr)
+      outstream: Output stream (defaults to stdout)
-    :param message: Reflog message (defaults to b"fetch: from <remote_name>")
+      errstream: Error stream (defaults to stderr)
-    :param depth: Depth to fetch at
+      message: Reflog message (defaults to b"fetch: from <remote_name>")
-    :param prune: Prune remote removed refs
+      depth: Depth to fetch at
-    :param prune_tags: Prune reomte removed tags
+      prune: Prune remote removed refs
-    :return: Dictionary with refs on the remote
+      prune_tags: Prune reomte removed tags
+    Returns:
+      Dictionary with refs on the remote
     """
     if message is None:
         message = b'fetch: from ' + remote_location.encode("utf-8")
@@ -1229,9 +1231,11 @@ def fetch(repo, remote_location, remote_name=b'origin', outstream=sys.stdout,
 def ls_remote(remote, config=None, **kwargs):
     """List the refs in a remote.
 
-    :param remote: Remote repository location
+    Args:
-    :param config: Configuration to use
+      remote: Remote repository location
-    :return: Dictionary with remote refs
+      config: Configuration to use
+    Returns:
+      Dictionary with remote refs
     """
     if config is None:
         config = StackedConfig.default()