tests and opener changes

Author: willmcgugan

docs/source/extension.rst

@@ -4,23 +4,23 @@ Creating an extension
 =====================
 
 Once a filesystem has been implemented, it can be integrated with other
-projects and applications using PyFilesystem.
+applications and projects using PyFilesystem.
 
 
 Naming Convention
 -----------------
 
 For visibility in PyPi, we recommend that your package be prefixed with
-``fs-``, for example your package may be named `fs-awesome` or `fs-
-awesomefs`.
+``fs-``. For instance if you have implemented an ``AwesomeFS``
+PyFilesystem class, your packaged could be be named ``fs-awesome`` or
+``fs-awesomefs``.
 
 
 Opener
 ------
 
-In order for your filesystem to be opened through :doc:`openers` like
-the other builtin filesystems, you should define a
-:class:`~fs.opener.base.Opener` class for your filesystem.
+In order for your filesystem to be opened with an :ref:`FS URL <fs-urls>`
+you should define an :class:`~fs.opener.base.Opener` class.
 
 Here's an example taken from an Amazon S3 Filesystem::
 
@@ -51,26 +51,25 @@ Here's an example taken from an Amazon S3 Filesystem::
           )
           return s3fs
 
-My convention this would be declared in ``opener.py``.
+By convention this would be defined in ``opener.py``.
 
 
 To register the opener you will need to define an `entry point
 <http://setuptools.readthedocs.io/en/latest/setuptools.html?highlight=entry%20points#dynamic-discovery-of-services-and-plugins>`_
 in your setup.py. See below for an example.
 
 
-The ``setup.py`` file
----------------------
+The setup.py file
+-----------------
 
 Refer to the `setuptools documentation <https://setuptools.readthedocs.io/>`_
 to see how to write a ``setup.py`` file. There are only a few things that
 should be kept in mind when creating a Pyfilesystem2 extension. Make sure that:
 
-* ``fs`` is in the ``install_requires`` list, in order to always have
-  Pyfilesystem2 installed before your extension. You should reference
-  the version number with the ``~=`` operator which ensures that the
-  install will get any bugfix releases of PyFilesystem but not any
-  potentially breaking changes.
+* ``fs`` is in the ``install_requires`` list. You should reference the
+  version number with the ``~=`` operator which ensures that the install
+  will get any bugfix releases of PyFilesystem but not any potentially
+  breaking changes.
 * Ìf you created an opener, include it as an ``fs.opener`` entry point,
   using the name of the entry point as the protocol to be used.
 
@@ -100,27 +99,23 @@ Here is an minimal ``setup.py`` for our project:
 Good Practices
 --------------
 
-* Keep track of your achievements ! Add ``__version__``, ``__author__``,
-  ``__author_email__`` and ``__license__`` variables to your project
-  (either in ``fs/awesomefs.py`` or ``fs/awesomefs/__init__.py`` depending
-  on the chosen structure), containing:
-
-    ``__version__``
-      the version of the extension (use `Semantic Versioning
-      <http://semver.org/>`_ if possible !)
+Keep track of your achievements! Add the following values to your ``__init__.py``:
 
-    ``__author__``
-      your name(s)
+ * ``__version__`` The version of the extension (we recommend following
+   `Semantic Versioning <http://semver.org/>`_),
+ * ``__author__`` Your name(s).
+ * ``__author_email__`` Your email(s).
+ * ``__license__`` The module's license.
 
-    ``__author_email__``
-      your email(s)
+Let us Know
+-----------
 
-    ``__license__``
-      the license of the subpackage
+Contact us to add your filesystem to the `PyFilesystem Wiki <https://www.pyfilesystem.org/page/index-of-filesystems/>`_.
 
 
 Live Example
 ------------
 
 See `fs.sshfs <https://github.com/althonos/fs.sshfs>`_ for a functioning
-PyFilesystem2 extension implementing a Pyfilesystem2 filesystem over SSH.
+PyFilesystem2 extension implementing a Pyfilesystem2 filesystem over
+SSH.

docs/source/openers.rst

@@ -1,3 +1,5 @@
+.. _fs-urls:
+
 FS URLs
 =======
 

fs/_version.py

@@ -1 +1 @@
-__version__ = "2.0.6a2"
+__version__ = "2.0.6a3"

fs/base.py

@@ -846,8 +846,7 @@ def open(self,
             ``utf-8``)
         :param str errors: What to do with unicode decode errors (see
             `stdlib docs <https://docs.python.org/3/library/codecs.html#error-handlers>`_)
-        :param str newline: New line parameter (See `stdlib docs
-            <https://docs.python.org/3/library/functions.html#open>`_)
+        :param str newline: New line parameter (See stdlib docs).
         :param options: Additional keyword parameters to set
             implementation specific options (if required). See
             implementation docs for details.

fs/opener/__init__.py

@@ -12,8 +12,7 @@
 
 # Import objects into fs.opener namespace
 from .base import Opener
-from .errors import OpenerError, ParseError, Unsupported
-from .registry import registry, Registry
+from .registry import registry
 
 # Alias functions defined as Registry methods
 open_fs = registry.open_fs
@@ -24,11 +23,7 @@
 # __all__ with aliases and classes
 __all__ = [
     "registry",
-    "Registry",
     "Opener",
-    "OpenerError",
-    "ParseError",
-    "Unsupported",
     'open_fs',
     'open',
     'manage_fs',

fs/opener/errors.py

@@ -3,7 +3,8 @@
 fs.opener.errors
 ================
 
-Errors raised when attempting to open a filesystem
+Errors raised when attempting to open a filesystem.
+
 """
 
 class ParseError(ValueError):
@@ -13,9 +14,11 @@ class ParseError(ValueError):
 class OpenerError(Exception):
     """Base class for opener related errors."""
 
-class Unsupported(OpenerError):
-    """May be raised by opener if the opener fails to open a FS."""
+
+class UnsupportedProtocol(OpenerError):
+    """May be raised if no opener could be found for a given
+    protocol."""
 
 
-class EntryPointError(OpenerError, RuntimeError):
+class EntryPointError(OpenerError):
     """Raised by the registry when an entry point cannot be loaded."""

fs/opener/registry.py

@@ -5,6 +5,7 @@
 
 Defines the Registry, which maps protocols and FS URLs to their
 respective Opener.
+
 """
 
 from __future__ import absolute_import
@@ -18,7 +19,7 @@
 import pkg_resources
 
 from .base import Opener
-from .errors import ParseError, Unsupported, EntryPointError
+from .errors import ParseError, UnsupportedProtocol, EntryPointError
 
 
 class Registry(object):
@@ -56,12 +57,11 @@ class Registry(object):
     @classmethod
     def parse(cls, fs_url):
         """
-        Parse a Filesystem URL and return a :class:`ParseResult`, or raise
-        :class:`ParseError` (subclass of ValueError) if the FS URL is
-        not value.
+        Parse a Filesystem URL and return a :class:`ParseResult`, or
+        raise :class:`ParseError` (subclass of ValueError) if the FS URL
+        is not value.
 
-        :param fs_url: A filesystem URL
-        :type fs_url: str
+        :param str fs_url: A filesystem URL
         :rtype: :class:`ParseResult`
 
         """
@@ -85,13 +85,6 @@ def parse(cls, fs_url):
             path
         )
 
-    @property
-    def protocols(self):
-        return [
-            entry_point.name
-            for entry_point in pkg_resources.iter_entry_points('fs.opener')
-        ]
-
     def __init__(self, default_opener='osfs'):
         """
         Create a registry object.
@@ -102,27 +95,34 @@ def __init__(self, default_opener='osfs'):
 
         """
         self.default_opener = default_opener
+        self.protocols = [
+            entry_point.name
+            for entry_point in
+            pkg_resources.iter_entry_points('fs.opener')
+        ]
 
     def __repr__(self):
         return "<fs-registry {!r}>".format(self.protocols)
 
     def get_opener(self, protocol):
-        """Get the opener class associated to a given protocol.
+        """
+        Get the opener class associated to a given protocol.
 
-        :param str protocol: A filesystem URL protocol
-        :rtype: ``Opener``
-        :raises `~fs.opener.errors.Unsupported`: If no opener could be found
-        :raises EntryPointLoadingError: If the returned entry point is
-            not an ``Opener`` subclass or could not be loaded
+        :param str protocol: A filesystem protocol.
+        :rtype: ``Opener``.
+        :raises `~fs.opener.errors.UnsupportedProtocol`: If no opener could be found.
+        :raises `EntryPointLoadingError`: If the returned entry
+            point is not an ``Opener`` subclass or could not be loaded
             successfully.
+
         """
         entry_point = next(
             pkg_resources.iter_entry_points('fs.opener', protocol),
             None
         )
 
         if entry_point is None:
-            raise Unsupported(
+            raise UnsupportedProtocol(
                 "protocol '{}' is not supported".format(protocol)
             )
 

tests/test_opener.py

@@ -9,14 +9,18 @@
 
 from fs import opener
 from fs.osfs import OSFS
-from fs.opener import errors
+from fs.opener import registry, errors
 from fs.memoryfs import MemoryFS
 
 
 class TestParse(unittest.TestCase):
 
+    def test_registry_repr(self):
+        str(registry)
+        repr(registry)
+
     def test_parse_not_url(self):
-        with self.assertRaises(opener.ParseError):
+        with self.assertRaises(errors.ParseError):
             parsed = opener.parse('foo/bar')
 
     def test_parse_simple(self):
@@ -66,15 +70,21 @@ def test_parse_path(self):
 class TestRegistry(unittest.TestCase):
 
     def test_registry_protocols(self):
-        # Check regitry.protocols list the names of all available entry points
-        entry_map = pkg_resources.get_entry_map('fs', 'fs.opener')
+        # Check registry.protocols list the names of all available entry points
+
+        protocols = [
+            entry_point.name
+            for entry_point in
+            pkg_resources.iter_entry_points('fs.opener')
+        ]
+
         self.assertEqual(
-            sorted(entry_map.keys()),
+            sorted(protocols),
             sorted(opener.registry.protocols)
         )
 
     def test_unknown_protocol(self):
-        with self.assertRaises(opener.Unsupported):
+        with self.assertRaises(errors.UnsupportedProtocol):
             opener.open_fs('unknown://')
 
     def test_entry_point_load_error(self):
@@ -119,7 +129,6 @@ def test_entry_point_create_error(self):
                 'could not instantiate opener; some creation error', str(ctx.exception))
 
 
-
 class TestManageFS(unittest.TestCase):
 
     def test_manage_fs_url(self):
@@ -139,9 +148,9 @@ def test_manage_fs_error(self):
                 1/0
         except ZeroDivisionError:
             pass
-
         self.assertTrue(mem_fs.isclosed())
 
+
 class TestOpeners(unittest.TestCase):
 
     def test_repr(self):