Merge pull request #467 from PyFilesystem/update-docs

Update docs and add doctest loading mechanism

Author: althonos

CHANGELOG.md

@@ -15,6 +15,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
   [#449](https://github.com/PyFilesystem/pyfilesystem2/pull/449).
 - `PathError` now supports wrapping an exception using the `exc` argument.
   Closes [#453](https://github.com/PyFilesystem/pyfilesystem2/issues/453).
+- Better documentation of the `writable` parameter of `fs.open_fs`, and
+  hint about using `fs.wrap.read_only` when a read-only filesystem is
+  required. Closes [#441](https://github.com/PyFilesystem/pyfilesystem2/issues/441).
 
 ### Changed
 
@@ -28,7 +31,13 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - `FSTestCases` now builds the large data required for `upload` and `download` tests only
   once in order to reduce the total testing time.
 - `MemoryFS.move` and `MemoryFS.movedir` will now avoid copying data.
-   Closes [#452](https://github.com/PyFilesystem/pyfilesystem2/issues/452).
+  Closes [#452](https://github.com/PyFilesystem/pyfilesystem2/issues/452).
+- `FS.removetree("/")` behaviour has been standardized in all filesystems, and
+  is expected to clear the contents of the root folder without deleting it.
+  Closes [#471](https://github.com/PyFilesystem/pyfilesystem2/issues/471).
+- `FS.getbasic` is now deprecated, as it is redundant with `FS.getinfo`,
+  and `FS.getinfo` is now explicitly expected to return the *basic* info
+  namespace unconditionally. Closes [#469](https://github.com/PyFilesystem/pyfilesystem2/issues/469).
 
 ### Fixed
 
@@ -40,8 +49,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - `WrapCachedDir.isdir` and `WrapCachedDir.isfile` raising a `ResourceNotFound` error on non-existing path ([#470](https://github.com/PyFilesystem/pyfilesystem2/pull/470)).
 - `FTPFS` not listing certain entries with sticky/SUID/SGID permissions set by Linux server ([#473](https://github.com/PyFilesystem/pyfilesystem2/pull/473)).
   Closes [#451](https://github.com/PyFilesystem/pyfilesystem2/issues/451).
-- `scandir` iterator not being closed explicitly in `OSFS.scandir`, occasionally causing a `ResourceWarning` 
+- `scandir` iterator not being closed explicitly in `OSFS.scandir`, occasionally causing a `ResourceWarning`
   to be thrown. Closes [#311](https://github.com/PyFilesystem/pyfilesystem2/issues/311).
+- Incomplete type annotations for the `temp_fs` parameter of `WriteTarFS` and `WriteZipFS`.
+  Closes [#410](https://github.com/PyFilesystem/pyfilesystem2/issues/410).
 
 
 ## [2.4.12] - 2021-01-14

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/_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/_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