deprecate asdf.util.filepath_to_url

CHANGES.rst

@@ -7,6 +7,8 @@
 
 - Deprecate ``asdf.versioning.AsdfSpec`` [#1774]
 
+- Deprecate ``asdf.util.filepath_to_url`` use ``pathlib.Path.to_uri`` [#1735]
+
 
 3.2.0 (2024-04-05)
 ------------------

asdf/_tests/_block/test_external.py

@@ -11,7 +11,7 @@ def test_cache(tmp_path):
     asdf.AsdfFile({"data": arr}).write_to(efn)
 
     cache = external.ExternalBlockCache()
-    base_uri = asdf.util.filepath_to_url(f"{tmp_path}/")
+    base_uri = f"{tmp_path.as_uri()}/"
     data = cache.load(base_uri, "test.asdf")
     np.testing.assert_array_equal(data, arr)
     assert cache.load(base_uri, "test.asdf") is data

asdf/_tests/test_deprecated.py

@@ -129,3 +129,8 @@ def test_asdffile_version_map_deprecation():
 def test_format_tag_deprecation():
     with pytest.warns(AsdfDeprecationWarning, match="format_tag is deprecated"):
         asdf.testing.helpers.format_tag("stsci.edu", "asdf", "1.0.0", "fits/fits")
+
+
+def test_asdf_util_filepath_to_url_deprecation(tmp_path):
+    with pytest.warns(AsdfDeprecationWarning, match="asdf.util.filepath_to_url is deprecated"):
+        asdf.util.filepath_to_url(str(tmp_path))

asdf/_tests/test_generic_io.py

@@ -9,7 +9,7 @@
 import pytest
 
 import asdf
-from asdf import exceptions, generic_io, util
+from asdf import exceptions, generic_io
 from asdf.config import config_context
 
 from . import _helpers as helpers
@@ -91,19 +91,19 @@ def test_open(tmp_path, small_tree):
 
 
 def test_path(tree, tmp_path):
-    path = os.path.join(str(tmp_path), "test.asdf")
+    path = tmp_path / "test.asdf"
 
     def get_write_fd():
         f = generic_io.get_file(path, mode="w")
         assert isinstance(f, generic_io.RealFile)
-        assert f._uri == util.filepath_to_url(path)
+        assert f._uri == path.as_uri()
         return f
 
     def get_read_fd():
         # Must open with mode=rw in order to get memmapped data
         f = generic_io.get_file(path, mode="rw")
         assert isinstance(f, generic_io.RealFile)
-        assert f._uri == util.filepath_to_url(path)
+        assert f._uri == path.as_uri()
         # This is to check for a "feature" in Python 3.x that reading zero
         # bytes from a socket causes it to stop.  We have code in generic_io.py
         # to workaround it.
@@ -116,21 +116,21 @@ def get_read_fd():
 
 
 def test_open2(tree, tmp_path):
-    path = os.path.join(str(tmp_path), "test.asdf")
+    path = tmp_path / "test.asdf"
 
     def get_write_fd():
         # cannot use context manager here because it closes the file
         f = generic_io.get_file(open(path, "wb"), mode="w", close=True)
         assert isinstance(f, generic_io.RealFile)
-        assert f._uri == util.filepath_to_url(path)
+        assert f._uri == path.as_uri()
         return f
 
     def get_read_fd():
         # Must open with mode=rw in order to get memmapped data
         # cannot use context manager here because it closes the file
         f = generic_io.get_file(open(path, "r+b"), mode="rw", close=True)
         assert isinstance(f, generic_io.RealFile)
-        assert f._uri == util.filepath_to_url(path)
+        assert f._uri == path.as_uri()
         return f
 
     with _roundtrip(tree, get_write_fd, get_read_fd) as ff:
@@ -140,7 +140,7 @@ def get_read_fd():
 
 @pytest.mark.parametrize("mode", ["r", "w", "rw"])
 def test_open_not_binary_fail(tmp_path, mode):
-    path = os.path.join(str(tmp_path), "test.asdf")
+    path = tmp_path / "test.asdf"
 
     with open(path, "w") as fd:
         fd.write("\n\n\n")
@@ -157,20 +157,20 @@ def test_open_not_binary_fail(tmp_path, mode):
 
 
 def test_io_open(tree, tmp_path):
-    path = os.path.join(str(tmp_path), "test.asdf")
+    path = tmp_path / "test.asdf"
 
     def get_write_fd():
         # cannot use context manager here because it closes the file
         f = generic_io.get_file(open(path, "wb"), mode="w", close=True)
         assert isinstance(f, generic_io.RealFile)
-        assert f._uri == util.filepath_to_url(path)
+        assert f._uri == path.as_uri()
         return f
 
     def get_read_fd():
         # cannot use context manager here because it closes the file
         f = generic_io.get_file(open(path, "r+b"), mode="rw", close=True)
         assert isinstance(f, generic_io.RealFile)
-        assert f._uri == util.filepath_to_url(path)
+        assert f._uri == path.as_uri()
         return f
 
     with _roundtrip(tree, get_write_fd, get_read_fd) as ff:

asdf/_tests/test_reference.py

@@ -6,7 +6,7 @@
 from numpy.testing import assert_array_equal
 
 import asdf
-from asdf import reference, util
+from asdf import reference
 from asdf.exceptions import AsdfDeprecationWarning
 from asdf.tags.core import ndarray
 
@@ -79,7 +79,7 @@ def do_asserts(ff):
 
         assert_array_equal(ff.tree["internal"], exttree["cool_stuff"]["a"])
 
-    with asdf.AsdfFile({}, uri=util.filepath_to_url(os.path.join(str(tmp_path), "main.asdf"))) as ff:
+    with asdf.AsdfFile({}, uri=(tmp_path / "main.asdf").as_uri()) as ff:
         # avoid passing tree to AsdfFile to avoid the deprecation warning, this can be updated
         # when automatic find_references on AsdfFile.__init__ is removed
         ff.tree = tree
@@ -143,7 +143,7 @@ def test_external_reference_invalid(tmp_path):
 
     # avoid passing tree to AsdfFile to avoid the deprecation warning, this can be updated
     # when automatic find_references on AsdfFile.__init__ is removed
-    ff = asdf.AsdfFile({}, uri=util.filepath_to_url(os.path.join(str(tmp_path), "main.asdf")))
+    ff = asdf.AsdfFile({}, uri=(tmp_path / "main.asdf").as_uri())
     ff.tree = tree
     ff.find_references()
     with pytest.raises(IOError, match=r"No such file or directory: .*"):
@@ -160,7 +160,7 @@ def test_external_reference_invalid_fragment(tmp_path):
 
     # avoid passing tree to AsdfFile to avoid the deprecation warning, this can be updated
     # when automatic find_references on AsdfFile.__init__ is removed
-    with asdf.AsdfFile({}, uri=util.filepath_to_url(os.path.join(str(tmp_path), "main.asdf"))) as ff:
+    with asdf.AsdfFile({}, uri=(tmp_path / "main.asdf").as_uri()) as ff:
         ff.tree = tree
         ff.find_references()
         with pytest.raises(ValueError, match=r"Unresolvable reference: .*"):
@@ -170,7 +170,7 @@ def test_external_reference_invalid_fragment(tmp_path):
 
     # avoid passing tree to AsdfFile to avoid the deprecation warning, this can be updated
     # when automatic find_references on AsdfFile.__init__ is removed
-    with asdf.AsdfFile({}, uri=util.filepath_to_url(os.path.join(str(tmp_path), "main.asdf"))) as ff:
+    with asdf.AsdfFile({}, uri=(tmp_path / "main.asdf").as_uri()) as ff:
         ff.tree = tree
         ff.find_references()
         with pytest.raises(ValueError, match=r"Unresolvable reference: .*"):
@@ -204,7 +204,7 @@ def test_make_reference(tmp_path):
 
 
 def test_internal_reference(tmp_path):
-    testfile = os.path.join(str(tmp_path), "test.asdf")
+    testfile = tmp_path / "test.asdf"
 
     tree = {"foo": 2, "bar": {"$ref": "#"}}
 
@@ -216,7 +216,7 @@ def test_internal_reference(tmp_path):
     assert ff.tree["bar"]["foo"] == 2
 
     tree = {"foo": 2}
-    ff = asdf.AsdfFile(tree, uri=util.filepath_to_url(os.path.abspath(testfile)))
+    ff = asdf.AsdfFile(tree, uri=testfile.as_uri())
     ff.tree["bar"] = ff.make_reference([])
     buff = io.BytesIO()
     ff.write_to(buff)

asdf/generic_io.py

@@ -754,7 +754,7 @@ def __init__(self, fd, mode, close=False, uri=None):
         super().__init__(fd, mode, close=close, uri=uri)
 
         if uri is None and hasattr(fd, "name") and isinstance(fd.name, str):
-            self._uri = util.filepath_to_url(os.path.abspath(fd.name))
+            self._uri = pathlib.Path(fd.name).expanduser().absolute().as_uri()
 
     def write_array(self, arr):
         if isinstance(arr, np.memmap) and getattr(arr, "fd", None) is self:

asdf/util.py

@@ -155,6 +155,8 @@ def filepath_to_url(path):
     """
     For a given local file path, return a file:// url.
     """
+    msg = "asdf.util.filepath_to_url is deprecated. Please use pathlib.Path.as_uri"
+    warnings.warn(msg, exceptions.AsdfDeprecationWarning)
     return _patched_urllib_parse.urljoin("file:", pathname2url(path))
 
 

docs/asdf/deprecations.rst

@@ -33,6 +33,8 @@ be issued on a failed validation during the following methods:
 
 Providing ``kwargs`` to ``AsdfFile.resolve_references`` does nothing and is deprecated.
 
+``asdf.util.filepath_to_url`` is deprecated. Please use ``pathlib.Path.to_uri``.
+
 Version 3.0
 ===========
 

pytest_asdf/plugin.py

@@ -210,15 +210,15 @@ def from_parent(
         return result
 
     def runtest(self):
-        from asdf import AsdfFile, _block, generic_io, util
+        from asdf import AsdfFile, _block, generic_io
         from asdf.testing import helpers
 
         # Make sure that the examples in the schema files (and thus the
         # ASDF standard document) are valid.
         buff = helpers.yaml_to_asdf("example: " + self.example.example.strip(), version=self.example.version)
 
         ff = AsdfFile(
-            uri=util.filepath_to_url(os.path.abspath(self.filename)),
+            uri=pathlib.Path(self.filename).expanduser().absolute().as_uri(),
             ignore_unrecognized_tag=self.ignore_unrecognized_tag,
             ignore_version_mismatch=self.ignore_version_mismatch,
         )
@@ -227,7 +227,7 @@ def runtest(self):
         ff2 = AsdfFile({"data": np.empty((1024 * 1024 * 8), dtype=np.uint8)})
 
         ff._external_asdf_by_uri[
-            util.filepath_to_url(os.path.abspath(os.path.join(os.path.dirname(self.filename), "external.asdf")))
+            (pathlib.Path(self.filename).expanduser().absolute().parent / "external.asdf").as_uri()
         ] = ff2
 
         wb = _block.writer.WriteBlock(np.zeros(1024 * 1024 * 8, dtype=np.uint8))