Rewrite docstrings of some private helpers in doctest format so they are tested

Author: althonos

fs/_ftp_parse.py

@@ -56,9 +56,7 @@
 
 
 def get_decoders():
-    """
-    Returns all available FTP LIST line decoders with their matching regexes.
-    """
+    """Return all available FTP LIST line decoders with their matching regexes."""
     decoders = [
         (RE_LINUX, decode_linux),
         (RE_WINDOWSNT, decode_windowsnt),
@@ -149,13 +147,34 @@ def _decode_windowsnt_time(mtime):
 
 
 def decode_windowsnt(line, match):
-    """
-    Decodes a Windows NT FTP LIST line like one of these:
+    """Decode a Windows NT FTP LIST line.
+
+    Examples:
+        Decode a directory line::
+
+            >>> line = "11-02-18  02:12PM       <DIR>          images"
+            >>> match = RE_WINDOWSNT.match(line)
+            >>> pprint(decode_windowsnt(line, match))
+            {'basic': {'is_dir': True, 'name': 'images'},
+             'details': {'modified': 1518358320.0, 'type': 1},
+             'ftp': {'ls': '11-02-18  02:12PM       <DIR>          images'}}
+
+        Decode a file line::
+
+            >>> line = "11-02-18  03:33PM                 9276 logo.gif"
+            >>> match = RE_WINDOWSNT.match(line)
+            >>> pprint(decode_windowsnt(line, match))
+            {'basic': {'is_dir': False, 'name': 'logo.gif'},
+             'details': {'modified': 1518363180.0, 'size': 9276, 'type': 2},
+             'ftp': {'ls': '11-02-18  03:33PM                 9276 logo.gif'}}
+
+        Alternatively, the time might also be present in 24-hour format::
 
-    `11-02-18  02:12PM       <DIR>          images`
-    `11-02-18  03:33PM                 9276 logo.gif`
+            >>> line = "11-02-18  15:33                   9276 logo.gif"
+            >>> match = RE_WINDOWSNT.match(line)
+            >>> decode_windowsnt(line, match)["details"]["modified"]
+            1518363180.0
 
-    Alternatively, the time (02:12PM) might also be present in 24-hour format (14:12).
     """
     is_dir = match.group("size") == "<DIR>"
 

fs/_url_tools.py

@@ -11,13 +11,15 @@
 
 def url_quote(path_snippet):
     # type: (Text) -> Text
-    """
-    On Windows, it will separate drive letter and quote windows
-    path alone. No magic on Unix-alie path, just pythonic
-    `pathname2url`
+    """Quote a URL without quoting the Windows drive letter, if any.
+
+    On Windows, it will separate drive letter and quote Windows
+    path alone. No magic on Unix-like path, just pythonic
+    `~urllib.request.pathname2url`.
 
     Arguments:
-       path_snippet: a file path, relative or absolute.
+       path_snippet (str): a file path, relative or absolute.
+
     """
     if _WINDOWS_PLATFORM and _has_drive_letter(path_snippet):
         drive_letter, path = path_snippet.split(":", 1)
@@ -34,17 +36,19 @@ def url_quote(path_snippet):
 
 def _has_drive_letter(path_snippet):
     # type: (Text) -> bool
-    """
-    The following path will get True
-    D:/Data
-    C:\\My Dcouments\\ test
+    """Check whether a path contains a drive letter.
 
-    And will get False
+    Arguments:
+       path_snippet (str): a file path, relative or absolute.
 
-    /tmp/abc:test
+    Example:
+        >>> _has_drive_letter("D:/Data")
+        True
+        >>> _has_drive_letter(r"C:\\System32\\ test")
+        True
+        >>> _has_drive_letter("/tmp/abc:test")
+        False
 
-    Arguments:
-       path_snippet: a file path, relative or absolute.
     """
     windows_drive_pattern = ".:[/\\\\].*$"
     return re.match(windows_drive_pattern, path_snippet) is not None

fs/base.py

@@ -709,7 +709,7 @@ def getmeta(self, namespace="standard"):
                             network.
         read_only           `True` if this filesystem is read only.
         supports_rename     `True` if this filesystem supports an
-                            `os.rename` operation (or equivalent).
+                            `os.rename` operation.
         =================== ============================================
 
         Most builtin filesystems will provide all these keys, and third-

fs/opener/registry.py

@@ -217,7 +217,7 @@ def open_fs(
             filesystem *needs* to be writable, which is relevant for
             some archive filesystems. Passing ``writeable=False`` will
             **not** make the return filesystem read-only. For this,
-            consider using `fs.wrap.WrapReadOnly` to wrap the returned
+            consider using `fs.wrap.read_only` to wrap the returned
             instance.
 
         """

tests/test_doctest.py

@@ -8,7 +8,9 @@
 import types
 import warnings
 import tempfile
+import time
 import unittest
+from pprint import pprint
 
 try:
     from unittest import mock
@@ -142,6 +144,8 @@ def tearDown(self):
                 OSFS=lambda path: MemoryFS(),
                 # NB (@althonos): This is for compatibility in `fs.registry`
                 print_list=lambda path: None,
+                pprint=pprint,
+                time=time,
             )
 
             # load the doctests into the unittest test suite