Add typing comments (#154)

* Add typing comments to `fs.base` and `fs.tools`

* Fix syntax for Python < 3.6

* Make sure `if False` typing branches are not covered

* Add typing comments to `fs.appfs`, `fs.compress` and `fs.opener.registry`

* Add typing comments to `fs.path`, `fs.wrap` and `fs.wrapfs`

* Add typing comments to `fs.filesize`

* Add typing comments to `fs.permissions`

* Add typing comments to `fs.copy`

* Fix renamed variable not renamed in `fs.path.relativefrom`

* Add typing comments to `fs.mode`

* Add `typing` to library dependencies

* Start adding typing annotations to `fs.memoryfs`

* Add `mypy_cache` to git ignore list

* Add a typecheck target to Makefile

* Add type alias `RawInfo` to `fs.info` module

* Enforce `_AppFS.app_dir` type as `Text`

* Make `FS.setinfo` expect a `_RawInfo`

* Add missing type annotations to `fs.memoryfs`

* Make `_ConvertOSErrors` a context manager subclass

* Add typing comments to `fs.ftpfs`

* Use `typing.TYPE_CHECKING` to hide imports at runtime

* Add typing comments to `fs.mirror`

* Add typing comments to `fs.mountfs` and fix Mode subclass

* Remove `typing.ContextManager` subclassing for PyPy compatibility

* Add typing comments to `fs.move`

* Add typing annotations to `fs.multifs`

* Amend `MultiFS` API to improve type checking

* Make Python 3.5 depend on `typing~=3.6`

* Add missing type comments to `fs.path` and `fs.permissions`

* Add typing annotations to `fs.zipfs` and `fs.tarfs`

* Fix wrong `make_repr` signature in `fs._repr`

* Add typing annotations to `fs.tree` and `fs.tempfs`

* Make `FS.getmeta` return a mapping instead of a dict

* Fix wrong `unwrap_error` signature in `fs.error_tools`

* Add type comments to `fs.wrapfs`

* Ignore coverage of `typing` imports

* Make `WrapFS` and `SubFS` generic classes

* Make `MountFS.makedir` return only `SubFS[FS]`

* Fix `makedir`, `makedirs` and `opendir` signatures where applicable

* Add missing typing comments to `fs.osfs`

* Fix undeclared bound class in `fs.base`

* Fix invalid `__eq__` method of `Info` objects

* Fix method shadowing in `fs.appfs`

* Fix `FTPFS.create` not returning anything

* Fix occurences of `optional` within the documentation

* Fix `WrapReadOnly.makedirs` using mode instead of Permissions

* Add type comments to `fs.errors`

* Make `LRUCache` a generic mapping class

* Fix missing signatures and type-related bugs

* Fix bugs introduced by typing code changes

* Fix missing typing annotations in `fs.opener`

* Fix functions missing type annotations

* Add `mypy` configuration to `setup.cfg`

* Have `fs.copy` use `typing.TYPE_CHECKING` import guard

* Allow `on_copy` callbacks to return objects in `fs.copy`

* Import `typing` classes locally in `fs.ftpfs`

* Add annotations to `fs.iotools`

* Improve type signature of `makedir` and `opendir`

* Make `getsize` return always int

* Make `Info.size` property return int

* Fix @althonos role in README

Signed-off-by: Martin Larralde <[email protected]>

* Patch `typing.TYPE_CHECKING` missing in Python 3.5.1

* Fix `mypy` complaints about `_OpendirFactory`

Author: Martin Larralde

.gitignore

@@ -90,7 +90,8 @@ ENV/
 # Rope project settings
 .ropeproject
 
-
-#PyCharm
-
+# PyCharm
 .idea/
+
+# MyPy cache
+.mypy_cache

Makefile

@@ -24,3 +24,7 @@ testall:
 docs:
 	cd docs && make html
 	python -c "import os, webbrowser; webbrowser.open('file://' + os.path.abspath('./docs/build/html/index.html'))"
+
+.PHONY: typecheck
+typecheck:
+	mypy -p fs --config setup.cfg

README.rst

@@ -89,7 +89,7 @@ Credits
 -------
 
 -  `Will McGugan <https://github.com/willmcgugan>`__
--  `Martin Larralde <https://github.com/althonos>`__ for TarFS
+-  `Martin Larralde <https://github.com/althonos>`__
 -  `Giampaolo <https://github.com/gpcimino>`__ for ``copy_if_newer`` and
    ftp fixes.
 

fs/_repr.py

@@ -3,7 +3,14 @@
 
 from __future__ import unicode_literals
 
+import typing
+
+if False:  # typing.TYPE_CHECKING
+    from typing import Text, Tuple
+
+
 def make_repr(class_name, *args, **kwargs):
+    # type: (Text, *object, **Tuple[object, object]) -> Text
     """Generate a repr string.
 
     Positional arguments should be the positional arguments used to

fs/appfs.py

@@ -9,10 +9,16 @@
 
 # see http://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx
 
+import typing
+
 from .osfs import OSFS
 from ._repr import make_repr
 from appdirs import AppDirs
 
+if False:  # typing.TYPE_CHECKING
+    from typing import Optional, Text
+
+
 __all__ = ['UserDataFS',
            'UserConfigFS',
            'SiteDataFS',
@@ -25,37 +31,45 @@ class _AppFS(OSFS):
     """Abstract base class for an app FS.
     """
 
-    app_dir = None
+    # FIXME(@althonos): replace by ClassVar[Text] once
+    # https://github.com/python/mypy/pull/4718 is accepted
+    # (subclass override will raise errors until then)
+    app_dir = None  # type: Text
 
     def __init__(self,
-                 appname,
-                 author=None,
-                 version=None,
-                 roaming=False,
-                 create=True):
+                 appname,          # type: Text
+                 author=None,      # type: Optional[Text]
+                 version=None,     # type: Optional[Text]
+                 roaming=False,    # type: bool
+                 create=True       # type: bool
+                 ):
+        # type: (...) -> None
         self.app_dirs = AppDirs(appname, author, version, roaming)
-        self.create = create
+        self._create = create
         super(_AppFS, self).__init__(
             getattr(self.app_dirs, self.app_dir),
             create=create
         )
 
     def __repr__(self):
+        # type: () -> Text
         return make_repr(
             self.__class__.__name__,
             self.app_dirs.appname,
             author=(self.app_dirs.appauthor, None),
             version=(self.app_dirs.version, None),
             roaming=(self.app_dirs.roaming, False),
-            create=(self.create, True)
+            create=(self._create, True)
         )
 
     def __str__(self):
+        # type: () -> Text
         return "<{} '{}'>".format(
             self.__class__.__name__.lower(),
             self.app_dirs.appname
         )
 
+
 class UserDataFS(_AppFS):
     """A filesystem for per-user application data.