feat(controller): add a uri property to every file controller

- file:// for LocalFileController, via Path.as_uri
- the stored url for RemoteFileController, so s3:// and https:// follow
- None for InMemoryController, a stream has no location
- fix InMemoryController, which could not be constructed at all

Author: LukasGold

src/osw/controller/file/base.py

@@ -1,12 +1,22 @@
 from abc import abstractmethod
-from typing import IO, Any, Dict
+from typing import IO, Any, Dict, Optional
 
 from osw.core import model
 
 
 class FileController(model.File):
     """Base class for file controllers"""
 
+    @property
+    @abstractmethod
+    def uri(self) -> Optional[str]:
+        """The location of the file, in the URI scheme of its storage backend
+
+        Returns
+        -------
+            the URI, or None if the file is not stored anywhere addressable
+        """
+
     @abstractmethod
     def get(self) -> IO:
         """Reads or downloads a file from an IO object

src/osw/controller/file/local.py

@@ -29,6 +29,12 @@ def __init__(self, **kwargs):
         super().__init__(**kwargs)
         self._set_metadata()
 
+    @property
+    def uri(self) -> str:
+        """The file URI of the path, see
+        https://en.wikipedia.org/wiki/File_URI_scheme"""
+        return Path(self.path).absolute().as_uri()
+
     def get(self) -> IO:
         self._set_metadata()
         return open(self.path, "rb")

src/osw/controller/file/memory.py

@@ -12,16 +12,25 @@ class InMemoryController(FileController, model.LocalFile):
     label: Optional[List[model.Label]] = [model.Label(text="Unnamed stream")]
     """the label of the stream, e.g., the name of the file the stream
     originates from. Defaults to 'Unnamed stream'."""
-    stream: IO
-    """the stream to the file"""
+    stream: Any
+    """the stream to the file, defaults to an empty StringIO. Not annotated as IO
+    because pydantic validates an arbitrary type by isinstance, and no stream is
+    an instance of typing.IO."""
 
     class Config:
         arbitrary_types_allowed = True
 
     def __init__(self, **kwargs):
-        self.stream = StringIO()
+        # the default has to go through the constructor: assigning it beforehand
+        # runs pydantic's __setattr__ on a model that is not initialized yet
+        kwargs.setdefault("stream", StringIO())
         super().__init__(**kwargs)
 
+    @property
+    def uri(self) -> None:
+        """None, a stream in memory has no location to address"""
+        return None
+
     def get(self) -> IO:
         return self.stream
 

src/osw/controller/file/remote.py

@@ -12,6 +12,12 @@
 # The data class must be the first base class, otherwise subclass controllers fall back
 #  to the data model of the controller superclass
 class RemoteFileController(model.RemoteFile, FileController):
+    @property
+    def uri(self) -> str:
+        """The url the file is stored at, e.g., 's3://' for S3FileController and
+        'https://' for WikiFileController"""
+        return self.url
+
     @abstractmethod
     def get(self) -> IO:
         pass

tests/test_file_controller_uri.py

@@ -0,0 +1,88 @@
+"""Offline tests for the uri property of the file controllers.
+
+Covers #68: every controller reports where its file lives, in the URI scheme of
+its own storage backend.
+"""
+
+from io import StringIO
+from pathlib import Path
+from types import SimpleNamespace
+from typing import IO, Any, Dict
+
+from osw.controller.file.local import LocalFileController
+from osw.controller.file.memory import InMemoryController
+from osw.controller.file.remote import RemoteFileController
+from osw.controller.file.wiki import WikiFileController
+from osw.core import model
+
+
+class OfflineRemoteFileController(RemoteFileController):
+    """A remote controller carrying nothing but a url, as model.S3File does"""
+
+    url: str
+
+    def get(self) -> IO:
+        pass
+
+    def put(self, file: IO, **kwargs: Dict[str, Any]):
+        pass
+
+
+def test_local_uri_is_a_file_url(tmp_path):
+    path = tmp_path / "test.txt"
+    path.write_text("content", encoding="utf-8")
+
+    uri = LocalFileController(path=path).uri
+
+    assert uri.startswith("file:///")
+    assert uri.endswith("/test.txt")
+
+
+def test_local_uri_is_absolute_for_a_relative_path(tmp_path, monkeypatch):
+    """as_uri() rejects a relative path, so the path has to be resolved first."""
+    monkeypatch.chdir(tmp_path)
+
+    uri = LocalFileController(path=Path("test.txt")).uri
+
+    assert uri == (Path.cwd() / "test.txt").as_uri()
+
+
+def test_local_uri_escapes_reserved_characters(tmp_path):
+    uri = LocalFileController(path=tmp_path / "a file.txt").uri
+
+    assert uri.endswith("/a%20file.txt")
+
+
+def test_in_memory_uri_is_none():
+    """A stream has no location, so there is nothing to point at."""
+    assert InMemoryController().uri is None
+
+
+def test_in_memory_keeps_the_stream_it_is_given():
+    stream = StringIO("content")
+
+    assert InMemoryController(stream=stream).get() is stream
+
+
+def test_remote_uri_is_the_url():
+    url = "s3://s3.example.org/bucket/OSW0000.txt"
+    controller = OfflineRemoteFileController(
+        url=url, label=[model.Label(text="OSW0000.txt")]
+    )
+
+    assert controller.uri == url
+
+
+def test_wiki_uri_is_the_file_page_url():
+    """WikiFileController builds url itself, so uri needs no override there."""
+    page = SimpleNamespace(
+        osw=SimpleNamespace(
+            mw_site=SimpleNamespace(scheme="https", host="wiki.example.org")
+        ),
+        title="OSW0000.txt",
+    )
+
+    url = WikiFileController.url.fget(page)
+
+    assert url == "https://wiki.example.org/wiki/File:OSW0000.txt"
+    assert RemoteFileController.uri.fget(SimpleNamespace(url=url)) == url