typing, docs, formatting (#246)

* typing, docs, formatting

* docs

* readme revamp, and pull request template

Author: willmcgugan

CONTRIBUTORS.md

@@ -0,0 +1,8 @@
+# Contributors (sorted alphabetically)
+
+Many thanks to the following developers for contributing to this project:
+
+- [Geoff Jukes](https://github.com/geoffjukes)
+- [Giampaolo](https://github.com/gpcimino)
+- [Martin Larralde](https://github.com/althonos)
+- [Will McGugan](https://github.com/willmcgugan)

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2016 Will McGugan
+Copyright (c) 2016-2019 Will McGugan
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,35 +1,31 @@
-PyFilesystem2
-=============
+# PyFilesystem2
 
 Python's Filesystem abstraction layer.
 
 [![PyPI version](https://badge.fury.io/py/fs.svg)](https://badge.fury.io/py/fs)
 [![PyPI](https://img.shields.io/pypi/pyversions/fs.svg)](https://pypi.org/project/fs/)
 [![Build Status](https://travis-ci.org/PyFilesystem/pyfilesystem2.svg?branch=master)](https://travis-ci.org/PyFilesystem/pyfilesystem2)
 [![Coverage Status](https://coveralls.io/repos/github/PyFilesystem/pyfilesystem2/badge.svg)](https://coveralls.io/github/PyFilesystem/pyfilesystem2)
-[![Codacy Badge](https://api.codacy.com/project/badge/Grade/30ad6445427349218425d93886ade9ee)](https://www.codacy.com/app/will-mcgugan/pyfilesystem2?utm_source=github.com&utm_medium=referral&utm_content=PyFilesystem/pyfilesystem2&utm_campaign=Badge_Grade)
+[![Codacy Badge](https://api.codacy.com/project/badge/Grade/30ad6445427349218425d93886ade9ee)](https://www.codacy.com/app/will-mcgugan/pyfilesystem2?utm_source=github.com&utm_medium=referral&utm_content=PyFilesystem/pyfilesystem2&utm_campaign=Badge_Grade)
 [![Code Health](https://landscape.io/github/PyFilesystem/pyfilesystem2/master/landscape.svg?style=flat)](https://landscape.io/github/PyFilesystem/pyfilesystem2/master)
 
-Documentation
--------------
+## Documentation
 
-* [Wiki](https://www.pyfilesystem.org)
-* [API Documentation](https://pyfilesystem2.readthedocs.io/en/latest/)
-* [GitHub Repository](https://github.com/PyFilesystem/pyfilesystem2)
-* [Blog](https://www.willmcgugan.com/tag/fs/)
+- [Wiki](https://www.pyfilesystem.org)
+- [API Documentation](https://pyfilesystem2.readthedocs.io/en/latest/)
+- [GitHub Repository](https://github.com/PyFilesystem/pyfilesystem2)
+- [Blog](https://www.willmcgugan.com/tag/fs/)
 
+## Introduction
 
-Introduction
-------------
-
-Think of PyFilesystem's ``FS`` objects as the next logical step to
-Python's ``file`` objects. In the same way that file objects abstract a
+Think of PyFilesystem's `FS` objects as the next logical step to
+Python's `file` objects. In the same way that file objects abstract a
 single file, FS objects abstract an entire filesystem.
 
 Let's look at a simple piece of code as an example. The following
 function uses the PyFilesystem API to count the number of non-blank
-lines of Python code in a directory. It works *recursively*, so it will
-find ``.py`` files in all sub-directories.
+lines of Python code in a directory. It works _recursively_, so it will
+find `.py` files in all sub-directories.
 
 ```python
 def count_python_loc(fs):
@@ -50,10 +46,10 @@ print(count_python_loc(projects_fs))
 ```
 
 The line `project_fs = open_fs('~/projects')` opens an FS object that
-maps to the ``projects`` directory in your home folder. That object is
+maps to the `projects` directory in your home folder. That object is
 used by `count_python_loc` when counting lines of code.
 
-To count the lines of Python code in a *zip file*, we can make the
+To count the lines of Python code in a _zip file_, we can make the
 following change:
 
 ```python
@@ -90,20 +86,27 @@ work with the OS filesystem. Any other filesystem would require an
 entirely different API, and you would likely have to re-implement the
 directory walking functionality of `os.walk`.
 
-Credits
--------
+## Credits
+
+The following developers have contributed code and their time to this projects:
+
+- [Will McGugan](https://github.com/willmcgugan)
+- [Martin Larralde](https://github.com/althonos)
+- [Giampaolo](https://github.com/gpcimino)
+- [Geoff Jukes](https://github.com/geoffjukes)
 
-* [Will McGugan](https://github.com/willmcgugan)
-* [Martin Larralde](https://github.com/althonos)
-* [Giampaolo](https://github.com/gpcimino) for `copy_if_newer` and ftp fixes.
-* [Geoff Jukes](https://github.com/geoffjukes) for ftp fixes.
+See CONTRIBUTORS.md for a full list of contributors.
 
 PyFilesystem2 owes a massive debt of gratitude to the following
 developers who contributed code and ideas to the original version.
 
-* Ryan Kelly
-* Andrew Scheller
-* Ben Timby
+- Ryan Kelly
+- Andrew Scheller
+- Ben Timby
 
 Apologies if I missed anyone, feel free to prompt me if your name is
 missing here.
+
+## Support
+
+If commercial support is required, please contact [Will McGugan](mailto:[email protected]).

fs/_bulk.py

@@ -100,7 +100,7 @@ def stop(self):
                 self.queue.put(None)
             for worker in self.workers:
                 worker.join()
-            # Free up references help by workers
+            # Free up references held by workers
             del self.workers[:]
             self.queue.join()
         self.running = False

fs/base.py

@@ -116,12 +116,8 @@ def walk(self):
     # ---------------------------------------------------------------- #
 
     @abc.abstractmethod
-    def getinfo(
-        self,
-        path,  # type: Text
-        namespaces=None,  # type: Optional[Collection[Text]]
-    ):
-        # type: (...) -> Info
+    def getinfo(self, path, namespaces=None):
+        # type: (Text, Optional[Collection[Text]]) -> Info
         """Get information about a resource on a filesystem.
 
         Arguments:
@@ -393,7 +389,7 @@ def copydir(self, src_path, dst_path, create=False):
             src_path (str): Path of source directory.
             dst_path (str): Path to destination directory.
             create (bool): If `True`, then ``dst_path`` will be created
-                if it doesn't exist alreadys (defaults to `False`).
+                if it doesn't exist already (defaults to `False`).
 
         Raises:
             fs.errors.ResourceNotFound: If the ``dst_path``
@@ -980,7 +976,7 @@ def lock(self):
 
     def movedir(self, src_path, dst_path, create=False):
         # type: (Text, Text, bool) -> None
-        """Move contents of directory ``src_path`` to ``dst_path``.
+        """Move directory ``src_path`` to ``dst_path``.
 
         Parameters:
             src_path (str): Path of source directory on the filesystem.

fs/osfs.py

@@ -27,15 +27,15 @@
     try:
         from scandir import scandir  # type: ignore
     except ImportError:  # pragma: no cover
-        scandir = None
+        scandir = None  # pragma: no cover
 
 try:
     from os import sendfile
 except ImportError:
     try:
         from sendfile import sendfile  # type: ignore
     except ImportError:
-        sendfile = None
+        sendfile = None  # pragma: no cover
 
 from . import errors
 from .errors import FileExists

fs/test.py

@@ -494,12 +494,14 @@ def test_getinfo(self):
 
         # Check that if the details namespace is present, times are
         # of valid types.
-        if 'details' in info.namespaces:
-            details = info.raw['details']
-            self.assertIsInstance(details.get('accessed'), (type(None), int, float))
-            self.assertIsInstance(details.get('modified'), (type(None), int, float))
-            self.assertIsInstance(details.get('created'), (type(None), int, float))
-            self.assertIsInstance(details.get('metadata_changed'), (type(None), int, float))
+        if "details" in info.namespaces:
+            details = info.raw["details"]
+            self.assertIsInstance(details.get("accessed"), (type(None), int, float))
+            self.assertIsInstance(details.get("modified"), (type(None), int, float))
+            self.assertIsInstance(details.get("created"), (type(None), int, float))
+            self.assertIsInstance(
+                details.get("metadata_changed"), (type(None), int, float)
+            )
 
     def test_exists(self):
         # Test exists method.
@@ -1739,6 +1741,7 @@ def test_movedir(self):
         self.fs.movedir("foo/bar", "foo2")
         self.assert_text("foo2/foofoo.txt", "Hello")
         self.assert_isdir("foo2/baz/egg")
+        self.assert_not_exists("foo/bar")
         self.assert_not_exists("foo/bar/foofoo.txt")
         self.assert_not_exists("foo/bar/baz/egg")
 
@@ -1814,7 +1817,5 @@ def test_case_sensitive(self):
         self.assert_isfile("fOO")
 
     def test_glob(self):
-        self.assertIsInstance(
-            self.fs.glob,
-            glob.BoundGlobber
-        )
+        self.assertIsInstance(self.fs.glob, glob.BoundGlobber)
+

fs/tools.py

@@ -69,7 +69,7 @@ def get_intermediate_dirs(fs, dir_path):
         list: A list of non-existing paths.
 
     Raises:
-        `fs.errors.DirectoryExpected`: If a path component
+        ~fs.errors.DirectoryExpected: If a path component
             references a file and not a directory.
 
     """

pull_request_template.md

@@ -0,0 +1,20 @@
+# PyFilesystem Pull Request
+
+Thank you for your pull request!
+
+## Type of changes
+
+- [ ] Bug fix
+- [ ] New Feature
+- [ ] Documentation / docstrings
+- [ ] Other
+
+## Checklist
+
+- [ ] I've run the latest [black](https://github.com/ambv/black) with default args on new code
+- [ ] I've updated CHANGELOG.md
+- [ ] I accept that @willmcgugan may be pedantic in the code review
+
+## Description
+
+Please describe your changes here. If this fixes a bug, please link to the issue, if possible.