Fixes of some errors/warnings reported by PyDev and inline documentation

fs/base.py

@@ -8,6 +8,8 @@ Instances of FS represent a filesystem containing files and directories
 that can be queried and manipulated.  To implement a new kind of filesystem,
 start by sublcassing the base FS class.
 
+For more information regarding implementing a working PyFilesystem interface, see :ref:`implementers`.
+
 """
 
 __all__ = ['DummyLock',
@@ -58,7 +60,7 @@ class DummyLock(object):
 
 
 def silence_fserrors(f, *args, **kwargs):
-    """Perform a function call and return None if FSError is thrown
+    """Perform a function call and return ``None`` if an :class:`fs.errors.FSError` is thrown
 
     :param f: Function to call
     :param args: Parameters to f
@@ -79,7 +81,7 @@ class NoDefaultMeta(object):
 class NullFile(object):
     """A NullFile is a file object that has no functionality.
 
-    Null files are returned by the 'safeopen' method in FS objects when the
+    Null files are returned by the :meth:`fs.base.FS.safeopen` method in FS objects when the
     file doesn't exist. This can simplify code by negating the need to check
     if a file exists, or handling exceptions.
 
@@ -172,9 +174,9 @@ class FS(object):
             ignore this value.
 
         :param enabled: If True the implementation is permitted to aggressively cache directory
-            structure / file information. Caching such information speeds up most operations,
+            structure / file information. Caching such information can speed up many operations,
             particularly for network based filesystems. The downside of caching is that
-            changes made to directories or files outside of this interface may not be picked up.
+            changes made to directories or files outside of this interface may not be picked up immediately.
 
         """
         pass
@@ -232,20 +234,17 @@ class FS(object):
          * *atomic.makedir* True if making a directory is an atomic operation
          * *atomic.rename* True if rename is an atomic operation, (and not implemented as a copy followed by a delete)
          * *atomic.setcontents* True if the implementation supports setting the contents of a file as an atomic operation (without opening a file)        
-         
-        The following are less common:
-        
          * *free_space* The free space (in bytes) available on the file system   
          * *total_space* The total space (in bytes) available on the file system   
         
-        FS implementations may expose non-generic meta data through a self-named namespace. e.g. 'somefs.some_meta'
+        FS implementations may expose non-generic meta data through a self-named namespace. e.g. ``somefs.some_meta``
         
         Since no meta value is guaranteed to exist, it is advisable to always supply a
-        default value to `getmeta`.   
+        default value to ``getmeta``.   
         
         :param meta_name: The name of the meta value to retrieve
         :param default: An option default to return, if the meta value isn't present
-        :raises NoMetaError: If specified meta value is not present, and there is no default        
+        :raises `fs.errors.NoMetaError`: If specified meta value is not present, and there is no default        
         
         """         
         if meta_name not in self._meta:
@@ -278,7 +277,7 @@ class FS(object):
         :param allow_none: if True, this method will return None when there is no system path,
             rather than raising NoSysPathError
         :type allow_none: bool
-        :raises NoSysPathError: if the path does not map on to a system path, and allow_none is set to False (default)
+        :raises `fs.errors.NoSysPathError`: if the path does not map on to a system path, and allow_none is set to False (default)
         :rtype: unicode
         
         """
@@ -300,14 +299,14 @@ class FS(object):
         """Returns a url that corresponds to the given path, if one exists.
         
         If the path does not have an equivalent URL form (and allow_none is False)
-        then a NoPathURLError exception is thrown. Otherwise the URL will be
+        then a :class:`~fs.errors.NoPathURLError` exception is thrown. Otherwise the URL will be
         returns as an unicode string.
         
         :param path: a path within the filesystem
         :param allow_none: if true, this method can return None if there is no
             URL form of the given path
         :type allow_none: bool
-        :raises NoPathURLError: If no URL form exists, and allow_none is False (the default)
+        :raises `fs.errors.NoPathURLError`: If no URL form exists, and allow_none is False (the default)
         :rtype: unicode 
         
         """
@@ -341,7 +340,7 @@ class FS(object):
     def safeopen(self, path, mode="r", **kwargs):
         """Like :py:meth:`~fs.base.FS.open`, but returns a :py:class:`~fs.base.NullFile` if the file could not be opened.
 
-        A NullFile is a dummy file which has all the methods of a file-like object,
+        A ``NullFile`` is a dummy file which has all the methods of a file-like object,
         but contains no data.
 
         :param path: a path to file that should be opened
@@ -415,7 +414,7 @@ class FS(object):
         :rtype: iterable of paths
 
         :raises `fs.errors.ResourceNotFoundError`: if the path is not found
-        :raises `fs.errror.ResourceInvalidError`: if the path exists, but is not a directory
+        :raises `fs.errors.ResourceInvalidError`: if the path exists, but is not a directory
 
         """
         raise UnsupportedError("list directory")
@@ -707,7 +706,7 @@ class FS(object):
                           error_callback=None):
         """Create a new file from a string or file-like object asynchronously
         
-        This method returns a `threading.Event` object. Call the `wait` method on the event object
+        This method returns a ``threading.Event`` object. Call the ``wait`` method on the event object
         to block until all data has been written, or simply ignore it.        
         
         :param path: a path of the file to create
@@ -770,7 +769,7 @@ class FS(object):
         """Creates an empty file if it doesn't exist
         
         :param path: path to the file to create
-        :param wipe: If True, the contents of the file will be erased 
+        :param wipe: if True, the contents of the file will be erased 
         
         """
         if not wipe and self.isfile(path):
@@ -788,12 +787,10 @@ class FS(object):
         """Opens a directory and returns a FS object representing its contents.
 
         :param path: path to directory to open
-        :rtype: An FS object
+        :rtype: an FS object
         
         """
                 
-        #if path in ('', '/'):
-        #    return self
         from fs.wrapfs.subfs import SubFS
         if not self.exists(path):
             raise ResourceNotFoundError(path)
@@ -816,8 +813,8 @@ class FS(object):
         :type dir_wildcard: a string containing a wildcard (e.g. `*.txt`) or a callable that takes the directory name and returns a boolean
         :param search: a string dentifying the method used to walk the directories. There are two such methods:
         
-             * "breadth" yields paths in the top directories first
-             * "depth" yields the deepest paths first
+             * ``"breadth"`` yields paths in the top directories first
+             * ``"depth"`` yields the deepest paths first
                           
         :param ignore_errors: ignore any errors reading the directory
 
@@ -1184,7 +1181,7 @@ class FS(object):
         :param path: A path on this filesystem
         :param read_only: If True, the mmap may not be modified
         :param copy: If False then changes wont be written back to the file
-        :raises NoMMapError: Only paths that have a syspath can be opened as a mmap 
+        :raises `fs.errors.NoMMapError`: Only paths that have a syspath can be opened as a mmap 
          
         """        
         syspath = self.getsyspath(path, allow_none=True)

fs/ftpfs.py

@@ -12,7 +12,6 @@ import fs
 from fs.base import *
 from fs.errors import *
 from fs.path import pathsplit, abspath, dirname, recursepath, normpath, pathjoin, isbase
-from fs.remote import RemoteFileBuffer
 
 from ftplib import FTP, error_perm, error_temp, error_proto, error_reply
 
@@ -22,9 +21,8 @@ except ImportError:
     _GLOBAL_DEFAULT_TIMEOUT = object()    
 
 import threading
-from time import sleep
 import datetime
-import re
+
 from socket import error as socket_error
 from fs.local_functools import wraps
 
@@ -34,7 +32,6 @@ except ImportError:
     from StringIO import StringIO
 
 import time
-import sys
 
 
 # -----------------------------------------------
@@ -919,7 +916,6 @@ class FTPFS(FS):
         if not paths:
             self.dircache.clear()
         else:            
-            remove_paths = []
             dircache = self.dircache
             paths = [normpath(abspath(path)) for path in paths]
             for cached_path in dircache.keys():                
@@ -1189,7 +1185,7 @@ class FTPFS(FS):
             raise ResourceInvalidError(path)
 
         if not force:
-            for checkpath in self.listdir(path):
+            for _checkpath in self.listdir(path):
                 raise DirectoryNotEmptyError(path)
         try:
             if force:

fs/httpfs.py

@@ -8,7 +8,6 @@ fs.httpfs
 from fs.base import FS
 from fs.path import normpath
 from fs.errors import ResourceNotFoundError, UnsupportedError
-from urlparse import urlparse
 from urllib2 import urlopen, URLError
 
 class HTTPFS(FS):
@@ -33,9 +32,9 @@ class HTTPFS(FS):
         try:
             f = urlopen(url)
         except URLError, e:
-            raise ResourceNotFoundError(path)
+            raise ResourceNotFoundError(path, details=e)
         except OSError, e:
-            raise ResourceNotFoundError(path)
+            raise ResourceNotFoundError(path, details=e)
         
         return f
     

fs/remote.py

@@ -22,15 +22,12 @@ FS subclasses interfacing with a remote filesystem.  These include:
 
 from __future__ import with_statement
 
-import sys
-import os
 import time
-import copy
 import stat as statinfo
 from errno import EINVAL
 
 import fs.utils
-from fs.base import FS, threading
+from fs.base import threading
 from fs.wrapfs import WrapFS, wrap_fs_methods
 from fs.wrapfs.lazyfs import LazyFS
 from fs.path import *
@@ -621,10 +618,10 @@ class CacheFSMixin(WrapFS):
         return info
 
     def listdir(self,path="",*args,**kwds):
-        return list(nm for (nm,info) in self.listdirinfo(path,*args,**kwds))
+        return list(nm for (nm, _info) in self.listdirinfo(path,*args,**kwds))
 
     def ilistdir(self,path="",*args,**kwds):
-        for (nm,info) in self.ilistdirinfo(path,*args,**kwds):
+        for (nm, _info) in self.ilistdirinfo(path,*args,**kwds):
             yield nm
 
     def listdirinfo(self,path="",*args,**kwds):

fs/s3fs.py

@@ -9,10 +9,7 @@ interface for objects stored in Amazon Simple Storage Service (S3).
 
 """
 
-import os
-import time
 import datetime
-import hashlib
 import tempfile
 from fnmatch import fnmatch
 import stat as statinfo

fs/sftpfs.py

@@ -481,7 +481,7 @@ class SFTPFS(FS):
             self.client.rename(nsrc,ndst)
         except IOError, e:
             if getattr(e,"errno",None) == 2:
-                raise ResourceNotFoundError(path)
+                raise ResourceNotFoundError(src)
             if not self.isdir(dirname(dst)):
                 raise ParentDirectoryMissingError(dst)
             raise
@@ -496,7 +496,7 @@ class SFTPFS(FS):
             self.client.rename(nsrc,ndst)
         except IOError, e:
             if getattr(e,"errno",None) == 2:
-                raise ResourceNotFoundError(path)
+                raise ResourceNotFoundError(src)
             if self.exists(dst):
                 raise DestinationExistsError(dst)
             if not self.isdir(dirname(dst)):

fs/utils.py

@@ -14,7 +14,6 @@ __all__ = ['copyfile',
            'find_duplicates',
            'print_fs']
 
-import shutil
 import os
 import sys
 import stat

fs/watch.py

@@ -318,7 +318,7 @@ class WatchableFS(WatchableFSMixin,WrapFS):
         if not existed:
             self.notify_watchers(CREATED,path)
         self.notify_watchers(ACCESSED,path)
-        return retq
+        return ret
 
     def makedir(self,path,recursive=False,allow_recreate=False):
         existed = self.wrapped_fs.isdir(path)
@@ -441,7 +441,7 @@ class WatchableFS(WatchableFSMixin,WrapFS):
         self.notify_watchers(MODIFIED,path,False)
 
     def delxattr(self,path,name):
-        super(WatchableFS,self).delxattr(path,name,value)
+        super(WatchableFS,self).delxattr(path,name)
         self.notify_watchers(MODIFIED,path,False)
 
 

fs/zipfs.py

@@ -151,7 +151,7 @@ class ZipFS(FS):
             if path:
                 self._path_fs.makedir(path, recursive=True, allow_recreate=True)
         else:
-            dirpath, filename = pathsplit(path)
+            dirpath, _filename = pathsplit(path)
             if dirpath:
                 self._path_fs.makedir(dirpath, recursive=True, allow_recreate=True)
             f = self._path_fs.open(path, 'w')
@@ -191,7 +191,7 @@ class ZipFS(FS):
                 raise OperationFailedError("open file",
                                            path=path,
                                            msg="2 Zip file must be opened for writing ('w') or appending ('a')")
-            dirname, filename = pathsplit(path)
+            dirname, _filename = pathsplit(path)
             if dirname:
                 self.temp_fs.makedir(dirname, recursive=True, allow_recreate=True)