Fix documentation-related errors found by pydocstyle

Author: althonos

fs/base.py

@@ -598,7 +598,7 @@ def readbytes(self, path):
 
     def download(self, path, file, chunk_size=None, **options):
         # type: (Text, BinaryIO, Optional[int], **Any) -> None
-        """Copies a file from the filesystem to a file-like object.
+        """Copy a file from the filesystem to a file-like object.
 
         This may be more efficient that opening and copying files
         manually if the filesystem supplies an optimized method.
@@ -741,7 +741,7 @@ def getsyspath(self, path):
         # type: (Text) -> Text
         """Get the *system path* of a resource.
 
-        Parameters:
+        Arguments:
             path (str): A path on the filesystem.
 
         Returns:
@@ -777,10 +777,9 @@ def getsyspath(self, path):
 
     def getospath(self, path):
         # type: (Text) -> bytes
-        """Get a *system path* to a resource, encoded in the operating
-        system's prefered encoding.
+        """Get the *system path* to a resource, in the OS' prefered encoding.
 
-        Parameters:
+        Arguments:
             path (str): A path on the filesystem.
 
         Returns:
@@ -809,7 +808,7 @@ def gettype(self, path):
         # type: (Text) -> ResourceType
         """Get the type of a resource.
 
-        Parameters:
+        Arguments:
             path (str): A path on the filesystem.
 
         Returns:
@@ -847,7 +846,7 @@ def geturl(self, path, purpose="download"):
         # type: (Text, Text) -> Text
         """Get the URL to a given resource.
 
-        Parameters:
+        Arguments:
             path (str): A path on the filesystem
             purpose (str): A short string that indicates which URL
                 to retrieve for the given path (if there is more than
@@ -868,7 +867,7 @@ def hassyspath(self, path):
         # type: (Text) -> bool
         """Check if a path maps to a system path.
 
-        Parameters:
+        Arguments:
             path (str): A path on the filesystem.
 
         Returns:
@@ -886,7 +885,7 @@ def hasurl(self, path, purpose="download"):
         # type: (Text, Text) -> bool
         """Check if a path has a corresponding URL.
 
-        Parameters:
+        Arguments:
             path (str): A path on the filesystem.
             purpose (str): A purpose parameter, as given in
                 `~fs.base.FS.geturl`.
@@ -911,7 +910,7 @@ def isdir(self, path):
         # type: (Text) -> bool
         """Check if a path maps to an existing directory.
 
-        Parameters:
+        Arguments:
             path (str): A path on the filesystem.
 
         Returns:
@@ -930,7 +929,7 @@ def isempty(self, path):
         A directory is considered empty when it does not contain
         any file or any directory.
 
-        Parameters:
+        Arguments:
             path (str): A path to a directory on the filesystem.
 
         Returns:
@@ -947,7 +946,7 @@ def isfile(self, path):
         # type: (Text) -> bool
         """Check if a path maps to an existing file.
 
-        Parameters:
+        Arguments:
             path (str): A path on the filesystem.
 
         Returns:
@@ -963,7 +962,7 @@ def islink(self, path):
         # type: (Text) -> bool
         """Check if a path maps to a symlink.
 
-        Parameters:
+        Arguments:
             path (str): A path on the filesystem.
 
         Returns:
@@ -1009,7 +1008,7 @@ def movedir(self, src_path, dst_path, create=False):
         # type: (Text, Text, bool) -> None
         """Move directory ``src_path`` to ``dst_path``.
 
-        Parameters:
+        Arguments:
             src_path (str): Path of source directory on the filesystem.
             dst_path (str): Path to destination directory.
             create (bool): If `True`, then ``dst_path`` will be created
@@ -1443,8 +1442,7 @@ def touch(self, path):
 
     def validatepath(self, path):
         # type: (Text) -> Text
-        """Check if a path is valid, returning a normalized absolute
-        path.
+        """Validate a path, returning a normalized absolute path on sucess.
 
         Many filesystems have restrictions on the format of paths they
         support. This method will check that ``path`` is valid on the

fs/compress.py

@@ -46,9 +46,9 @@ def write_zip(
         compression (int): Compression to use (one of the constants
             defined in the `zipfile` module in the stdlib). Defaults
             to `zipfile.ZIP_DEFLATED`.
-        encoding (str):
-             The encoding to use for filenames. The default is ``"utf-8"``,
-             use ``"CP437"`` if compatibility with WinZip is desired.
+        encoding (str): The encoding to use for filenames. The default
+            is ``"utf-8"``, use ``"CP437"`` if compatibility with WinZip
+            is desired.
         walker (~fs.walk.Walker, optional): A `Walker` instance, or `None`
             to use default walker. You can use this to specify which files
             you want to compress.
@@ -116,6 +116,7 @@ def write_tar(
     """Write the contents of a filesystem to a tar file.
 
     Arguments:
+        src_fs (~fs.base.FS): The source filesystem to compress.
         file (str or io.IOBase): Destination file, may be a file
             name or an open file object.
         compression (str, optional): Compression to use, or `None`

fs/copy.py

@@ -150,7 +150,7 @@ def copy_file_internal(
     dst_path,  # type: Text
 ):
     # type: (...) -> None
-    """Low level copy, that doesn't call manage_fs or lock.
+    """Copy a file at low level, without calling `manage_fs` or locking.
 
     If the destination exists, and is a file, it will be first truncated.
 
@@ -160,7 +160,7 @@ def copy_file_internal(
     Arguments:
         src_fs (FS): Source filesystem.
         src_path (str): Path to a file on the source filesystem.
-        dst_fs (FS: Destination filesystem.
+        dst_fs (FS): Destination filesystem.
         dst_path (str): Path to a file on the destination filesystem.
 
     """

fs/errors.py

@@ -57,7 +57,7 @@
 class MissingInfoNamespace(AttributeError):
     """An expected namespace is missing."""
 
-    def __init__(self, namespace):
+    def __init__(self, namespace):  # noqa: D107
         # type: (Text) -> None
         self.namespace = namespace
         msg = "namespace '{}' is required for this attribute"
@@ -73,7 +73,7 @@ class FSError(Exception):
 
     default_message = "Unspecified error"
 
-    def __init__(self, msg=None):
+    def __init__(self, msg=None):  # noqa: D107
         # type: (Optional[Text]) -> None
         self._msg = msg or self.default_message
         super(FSError, self).__init__()
@@ -101,7 +101,7 @@ class BulkCopyFailed(FSError):
 
     default_message = "One or more copy operations failed (see errors attribute)"
 
-    def __init__(self, errors):
+    def __init__(self, errors):  # noqa: D107
         self.errors = errors
         super(BulkCopyFailed, self).__init__()
 
@@ -111,7 +111,7 @@ class CreateFailed(FSError):
 
     default_message = "unable to create filesystem, {details}"
 
-    def __init__(self, msg=None, exc=None):
+    def __init__(self, msg=None, exc=None):  # noqa: D107
         # type: (Optional[Text], Optional[Exception]) -> None
         self._msg = msg or self.default_message
         self.details = "" if exc is None else text_type(exc)
@@ -139,7 +139,7 @@ class PathError(FSError):
 
     default_message = "path '{path}' is invalid"
 
-    def __init__(self, path, msg=None):
+    def __init__(self, path, msg=None):  # noqa: D107
         # type: (Text, Optional[Text]) -> None
         self.path = path
         super(PathError, self).__init__(msg=msg)
@@ -159,7 +159,7 @@ class NoURL(PathError):
 
     default_message = "path '{path}' has no '{purpose}' URL"
 
-    def __init__(self, path, purpose, msg=None):
+    def __init__(self, path, purpose, msg=None):  # noqa: D107
         # type: (Text, Text, Optional[Text]) -> None
         self.purpose = purpose
         super(NoURL, self).__init__(path, msg=msg)
@@ -190,7 +190,7 @@ def __init__(
         path=None,  # type: Optional[Text]
         exc=None,  # type: Optional[Exception]
         msg=None,  # type: Optional[Text]
-    ):
+    ):  # noqa: D107
         # type: (...) -> None
         self.path = path
         self.exc = exc
@@ -243,7 +243,7 @@ class ResourceError(FSError):
 
     default_message = "failed on path {path}"
 
-    def __init__(self, path, exc=None, msg=None):
+    def __init__(self, path, exc=None, msg=None):  # noqa: D107
         # type: (Text, Optional[Exception], Optional[Text]) -> None
         self.path = path
         self.exc = exc
@@ -326,7 +326,7 @@ class IllegalBackReference(ValueError):
 
     """
 
-    def __init__(self, path):
+    def __init__(self, path):  # noqa: D107
         # type: (Text) -> None
         self.path = path
         msg = ("path '{path}' contains back-references outside of filesystem").format(

fs/ftpfs.py

@@ -347,18 +347,6 @@ def seek(self, pos, whence=Seek.set):
 
 class FTPFS(FS):
     """A FTP (File Transport Protocol) Filesystem.
-
-    Arguments:
-        host (str): A FTP host, e.g. ``'ftp.mirror.nl'``.
-        user (str): A username (default is ``'anonymous'``).
-        passwd (str): Password for the server, or `None` for anon.
-        acct (str): FTP account.
-        timeout (int): Timeout for contacting server (in seconds,
-            defaults to 10).
-        port (int): FTP port number (default 21).
-        proxy (str, optional): An FTP proxy, or ``None`` (default)
-            for no proxy.
-
     """
 
     _meta = {
@@ -381,6 +369,20 @@ def __init__(
         proxy=None,  # type: Optional[Text]
     ):
         # type: (...) -> None
+        """Create a new `FTPFS` instance.
+
+        Arguments:
+            host (str): A FTP host, e.g. ``'ftp.mirror.nl'``.
+            user (str): A username (default is ``'anonymous'``).
+            passwd (str): Password for the server, or `None` for anon.
+            acct (str): FTP account.
+            timeout (int): Timeout for contacting server (in seconds,
+                defaults to 10).
+            port (int): FTP port number (default 21).
+            proxy (str, optional): An FTP proxy, or ``None`` (default)
+                for no proxy.
+
+        """
         super(FTPFS, self).__init__()
         self._host = host
         self._user = user
@@ -494,9 +496,9 @@ def _get_ftp(self):
         return self._ftp
 
     @property
-    def features(self):
+    def features(self):  # noqa: D401
         # type: () -> Dict[Text, Text]
-        """dict: features of the remote FTP server."""
+        """`dict`: Features of the remote FTP server."""
         self._get_ftp()
         return self._features