Merge pull request #753 from TomAugspurger/feature/doc-url_to_fs

Added fsspec.core.url_to_fs to public API

Author: martindurant

docs/source/api.rst

@@ -40,6 +40,7 @@ Base Classes
    fsspec.core.OpenFiles
    fsspec.core.BaseCache
    fsspec.core.get_fs_token_paths
+   fsspec.core.url_to_fs
    fsspec.dircache.DirCache
    fsspec.registry.ReadOnlyRegistry
    fsspec.registry.register_implementation
@@ -72,6 +73,8 @@ Base Classes
 
 .. autofunction:: fsspec.core.get_fs_token_paths
 
+.. autofunction:: fsspec.core.url_to_fs
+
 .. autoclass:: fsspec.dircache.DirCache
    :members: __init__
 

fsspec/core.py

@@ -352,7 +352,25 @@ def _un_chain(path, kwargs):
 
 
 def url_to_fs(url, **kwargs):
-    """Turn fully-qualified and potentially chained URL into filesystem instance"""
+    """
+    Turn fully-qualified and potentially chained URL into filesystem instance
+
+    Parameters
+    ----------
+    url : str
+        The fsspec-compatible URL
+    **kwargs: dict
+        Extra options that make sense to a particular storage connection, e.g.
+        host, port, username, password, etc.
+
+    Returns
+    -------
+    filesystem : FileSystem
+        The new filesystem discovered from ``url`` and created with
+        ``**kwargs``.
+    urlpath : str
+        The file-systems-specific URL for ``url``.
+    """
     chain = _un_chain(url, kwargs)
     if len(chain) > 1:
         inkwargs = {}

fsspec/tests/test_api.py

@@ -323,3 +323,11 @@ def test_chained_fo():
     with of[0] as f:
         assert f.read() == b"test"
     assert "afile" in os.listdir(d3)
+
+
+def test_url_to_fs():
+    url = "memory://a.txt"
+    fs, url2 = fsspec.core.url_to_fs(url)
+
+    assert isinstance(fs, MemoryFileSystem)
+    assert url2 == "/a.txt"