Fix docstrings of various fs submodules to pass the doctests

Author: althonos

fs/_repr.py

@@ -27,7 +27,7 @@ def make_repr(class_name, *args, **kwargs):
         >>> MyClass('Will')
         MyClass('foo', name='Will')
         >>> MyClass(None)
-        MyClass()
+        MyClass('foo')
 
     """
     arguments = [repr(arg) for arg in args]

fs/base.py

@@ -619,7 +619,7 @@ def download(self, path, file, chunk_size=None, **options):
 
         Example:
             >>> with open('starwars.mov', 'wb') as write_file:
-            ...     my_fs.download('/movies/starwars.mov', write_file)
+            ...     my_fs.download('/Videos/starwars.mov', write_file)
 
         """
         with self._lock:
@@ -986,6 +986,7 @@ def lock(self):
         Example:
             >>> with my_fs.lock():  # May block
             ...    # code here has exclusive access to the filesystem
+            ...    pass
 
         It is a good idea to put a lock around any operations that you
         would like to be *atomic*. For instance if you are copying
@@ -1561,9 +1562,9 @@ def match(self, patterns, name):
         names).
 
         Example:
-            >>> home_fs.match(['*.py'], '__init__.py')
+            >>> my_fs.match(['*.py'], '__init__.py')
             True
-            >>> home_fs.match(['*.jpg', '*.png'], 'foo.gif')
+            >>> my_fs.match(['*.jpg', '*.png'], 'foo.gif')
             False
 
         Note:

fs/filesize.py

@@ -61,7 +61,7 @@ def traditional(size):
         `str`: A string containing an abbreviated file size and units.
 
     Example:
-        >>> filesize.traditional(30000)
+        >>> fs.filesize.traditional(30000)
         '29.3 KB'
 
     """
@@ -87,7 +87,7 @@ def binary(size):
         `str`: A string containing a abbreviated file size and units.
 
     Example:
-        >>> filesize.binary(30000)
+        >>> fs.filesize.binary(30000)
         '29.3 KiB'
 
     """
@@ -112,7 +112,7 @@ def decimal(size):
         `str`: A string containing a abbreviated file size and units.
 
     Example:
-        >>> filesize.decimal(30000)
+        >>> fs.filesize.decimal(30000)
         '30.0 kB'
 
     """

fs/glob.py

@@ -172,9 +172,8 @@ def count(self):
         """Count files / directories / data in matched paths.
 
         Example:
-            >>> import fs
-            >>> fs.open_fs('~/projects').glob('**/*.py').count()
-            Counts(files=18519, directories=0, data=206690458)
+            >>> my_fs.glob('**/*.py').count()
+            Counts(files=2, directories=0, data=55)
 
         Returns:
             `~Counts`: A named tuple containing results.
@@ -199,9 +198,8 @@ def count_lines(self):
             `~LineCounts`: A named tuple containing line counts.
 
         Example:
-            >>> import fs
-            >>> fs.open_fs('~/projects').glob('**/*.py').count_lines()
-            LineCounts(lines=5767102, non_blank=4915110)
+            >>> my_fs.glob('**/*.py').count_lines()
+            LineCounts(lines=4, non_blank=3)
 
         """
         lines = 0
@@ -222,9 +220,8 @@ def remove(self):
             int: Number of file and directories removed.
 
         Example:
-            >>> import fs
-            >>> fs.open_fs('~/projects/my_project').glob('**/*.pyc').remove()
-            29
+            >>> my_fs.glob('**/*.pyc').remove()
+            2
 
         """
         removes = 0

fs/info.py

@@ -106,8 +106,9 @@ def get(self, namespace, key, default=None):  # noqa: F811
                 is not found.
 
         Example:
-            >>> info.get('access', 'permissions')
-            ['u_r', 'u_w', '_wx']
+            >>> info = my_fs.getinfo("foo.py", namespaces=["details"])
+            >>> info.get('details', 'type')
+            2
 
         """
         try:
@@ -189,12 +190,10 @@ def suffix(self):
         In case there is no suffix, an empty string is returned.
 
         Example:
-            >>> info
-            <info 'foo.py'>
+            >>> info = my_fs.getinfo("foo.py")
             >>> info.suffix
             '.py'
-            >>> info2
-            <info 'bar'>
+            >>> info2 = my_fs.getinfo("bar")
             >>> info2.suffix
             ''
 
@@ -211,8 +210,7 @@ def suffixes(self):
         """`List`: a list of any suffixes in the name.
 
         Example:
-            >>> info
-            <info 'foo.tar.gz'>
+            >>> info = my_fs.getinfo("foo.tar.gz")
             >>> info.suffixes
             ['.tar', '.gz']
 
@@ -228,8 +226,7 @@ def stem(self):
         """`str`: the name minus any suffixes.
 
         Example:
-            >>> info
-            <info 'foo.tar.gz'>
+            >>> info = my_fs.getinfo("foo.tar.gz")
             >>> info.stem
             'foo'
 

fs/opener/registry.py

@@ -260,10 +260,13 @@ def manage_fs(
         required logic for that.
 
         Example:
-            >>> def print_ls(list_fs):
-            ...     '''List a directory.'''
-            ...     with manage_fs(list_fs) as fs:
-            ...         print(' '.join(fs.listdir()))
+            The `~Registry.manage_fs` method can be used to define a small
+            utility function::
+
+                >>> def print_ls(list_fs):
+                ...     '''List a directory.'''
+                ...     with manage_fs(list_fs) as fs:
+                ...         print(' '.join(fs.listdir()))
 
             This function may be used in two ways. You may either pass
             a ``str``, as follows::

fs/path.py

@@ -14,6 +14,8 @@
 import re
 import typing
 
+import six
+
 from .errors import IllegalBackReference
 
 if typing.TYPE_CHECKING:
@@ -64,9 +66,9 @@ def normpath(path):
         >>> normpath("/foo//bar/frob/../baz")
         '/foo/bar/baz'
         >>> normpath("foo/../../bar")
-        Traceback (most recent call last)
+        Traceback (most recent call last):
             ...
-        IllegalBackReference: path 'foo/../../bar' contains back-references outside of filesystem"
+        fs.errors.IllegalBackReference: path 'foo/../../bar' contains back-references outside of filesystem
 
     """  # noqa: E501
     if path in "/":
@@ -86,6 +88,7 @@ def normpath(path):
             else:
                 components.append(component)
     except IndexError:
+        # FIXME (@althonos): should be raised from the IndexError
         raise IllegalBackReference(path)
     return prefix + "/".join(components)
 

fs/permissions.py

@@ -58,7 +58,7 @@ class Permissions(object):
         >>> p.mode
         500
         >>> oct(p.mode)
-        '0764'
+        '0o764'
 
     """
 

fs/walk.py

@@ -146,24 +146,25 @@ def bind(cls, fs):
         Returns:
             ~fs.walk.BoundWalker: a bound walker.
 
-        Example:
-            >>> from fs import open_fs
-            >>> from fs.walk import Walker
-            >>> home_fs = open_fs('~/')
-            >>> walker = Walker.bind(home_fs)
-            >>> for path in walker.files(filter=['*.py']):
-            ...     print(path)
-
-        Unless you have written a customized walker class, you will be
-        unlikely to need to call this explicitly, as filesystem objects
-        already have a ``walk`` attribute which is a bound walker
-        object.
+        Examples:
 
-        Example:
-            >>> from fs import open_fs
-            >>> home_fs = open_fs('~/')
-            >>> for path in home_fs.walk.files(filter=['*.py']):
-            ...     print(path)
+            Use this method to explicitly bind a filesystem instance::
+
+                >>> walker = Walker.bind(my_fs)
+                >>> for path in walker.files(filter=['*.py']):
+                ...     print(path)
+                /foo.py
+                /bar.py
+
+            Unless you have written a customized walker class, you will
+            be unlikely to need to call this explicitly, as filesystem
+            objects already have a ``walk`` attribute which is a bound
+            walker object::
+
+                >>> for path in my_fs.walk.files(filter=['*.py']):
+                ...     print(path)
+                /foo.py
+                /bar.py
 
         """
         return BoundWalker(fs)
@@ -316,14 +317,16 @@ def walk(
         `~fs.info.Info` objects for directories and files in ``<path>``.
 
         Example:
-            >>> home_fs = open_fs('~/')
             >>> walker = Walker(filter=['*.py'])
-            >>> namespaces = ['details']
-            >>> for path, dirs, files in walker.walk(home_fs, namespaces)
+            >>> for path, dirs, files in walker.walk(my_fs, namespaces=["details"]):
             ...    print("[{}]".format(path))
             ...    print("{} directories".format(len(dirs)))
             ...    total = sum(info.size for info in files)
-            ...    print("{} bytes {}".format(total))
+            ...    print("{} bytes".format(total))
+            [/]
+            2 directories
+            55 bytes
+            ...
 
         """
         _path = abspath(normpath(path))
@@ -495,10 +498,9 @@ class BoundWalker(typing.Generic[_F]):
     `BoundWalker` object.
 
     Example:
-        >>> import fs
-        >>> home_fs = fs.open_fs('~/')
-        >>> home_fs.walk
-        BoundWalker(OSFS('/Users/will', encoding='utf-8'))
+        >>> tmp_fs = fs.tempfs.TempFS()
+        >>> tmp_fs.walk
+        BoundWalker(TempFS())
 
     A `BoundWalker` is callable. Calling it is an alias for the
     `~fs.walk.BoundWalker.walk` method.
@@ -575,13 +577,16 @@ def walk(
             `~fs.info.Info` objects for directories and files in ``<path>``.
 
         Example:
-            >>> home_fs = open_fs('~/')
             >>> walker = Walker(filter=['*.py'])
-            >>> for path, dirs, files in walker.walk(home_fs, namespaces=['details']):
+            >>> for path, dirs, files in walker.walk(my_fs, namespaces=['details']):
             ...     print("[{}]".format(path))
             ...     print("{} directories".format(len(dirs)))
             ...     total = sum(info.size for info in files)
-            ...     print("{} bytes {}".format(total))
+            ...     print("{} bytes".format(total))
+            [/]
+            2 directories
+            55 bytes
+            ...
 
         This method invokes `Walker.walk` with bound `FS` object.
 

fs/wrap.py

@@ -2,14 +2,12 @@
 
 Here's an example that opens a filesystem then makes it *read only*::
 
-    >>> from fs import open_fs
-    >>> from fs.wrap import read_only
-    >>> projects_fs = open_fs('~/projects')
-    >>> read_only_projects_fs = read_only(projects_fs)
-    >>> read_only_projects_fs.remove('__init__.py')
+    >>> home_fs = fs.open_fs('~')
+    >>> read_only_home_fs = fs.wrap.read_only(home_fs)
+    >>> read_only_home_fs.removedir('Desktop')
     Traceback (most recent call last):
       ...
-    fs.errors.ResourceReadOnly: resource '__init__.py' is read only
+    fs.errors.ResourceReadOnly: resource 'Desktop' is read only
 
 """