refactor: take the file controllers from opensemantic.core

- base, local, memory and remote now wrap the implementations that moved
  to core, which owns the file models
- LocalFileController keeps the path argument and filename-derived label
- WikiFileController rebases on core's RemoteFileController
- the session became optional and connects on first use from the
  credential registered for download_url or access_url
- the package imports its modules, so the controllers register and a file
  entity resolves to one without importing it by name

Author: simontaurus

src/osw/controller/file/__init__.py

@@ -0,0 +1,10 @@
+"""File controllers.
+
+Imported eagerly so the controllers register themselves: a caller that resolves
+a file entity through the controller registry then finds the wiki
+implementation without importing it by name.
+"""
+
+from osw.controller.file import base, local, memory, remote, wiki
+
+__all__ = ["base", "local", "memory", "remote", "wiki"]

src/osw/controller/file/base.py

@@ -1,66 +1,9 @@
-from abc import abstractmethod
-from typing import IO, Any, Dict
+"""File controller interface.
 
-from osw.core import model
+The implementation moved to ``opensemantic.core``, which owns the file models.
+This module keeps the import path working.
+"""
 
+from opensemantic.core.v1 import FileControllerMixin as FileController
 
-class FileController(model.File):
-    """Base class for file controllers"""
-
-    @abstractmethod
-    def get(self) -> IO:
-        """Reads or downloads a file from an IO object
-        Make sure to close the IO object after reading
-
-        Returns
-        -------
-            the IO object of the opened file
-        """
-
-    @abstractmethod
-    def put(self, file: IO, **kwargs: Dict[str, Any]):
-        """Writes or uploads a file from an IO object
-
-        Parameters
-        -------
-            file
-                the IO object to read from
-        """
-
-    def put_from(self, other: "FileController", **kwargs: Dict[str, Any]):
-        """Writes or uploads a file from another file controller
-        Automatically closes the other file controllers IO object after reading
-
-        Parameters
-        ----------
-        other
-            another file controller to read from
-        """
-        with other.get() as f:
-            self.put(f, **kwargs)
-
-    def get_to(self, other: "FileController"):
-        """Reads or downloads a file to another file controller
-        Automatically closes this file controllers IO object after reading
-
-        Parameters
-        ----------
-        other
-            another file controller to write to
-        """
-        with self.get() as f:
-            other.put(f)
-
-    @classmethod
-    def from_other(cls, other: "FileController", **kwargs: Any) -> "FileController":
-        """Create an instance based on another file controller
-        copying all common attributes
-
-        Parameters
-        ----------
-        other
-            another file controller to copy from
-        kwargs
-            additional attributes to be set
-        """
-        return other.cast(cls, **kwargs)
+__all__ = ["FileController"]

src/osw/controller/file/local.py

@@ -1,58 +1,53 @@
+"""Local file controller.
+
+The implementation moved to ``opensemantic.core``, which owns the file models.
+This subclass keeps the ``path`` argument and the filename-derived label of the
+controller it replaces.
+"""
+
 import os
-import shutil
-from io import TextIOBase
 from pathlib import Path
-from typing import IO, Any, Dict, List, Optional
+from typing import IO, Any, Dict
+
+from opensemantic.core.v1 import LocalFileController as _LocalFileController
 
-from osw.controller.file.base import FileController
 from osw.core import model
 
 
-class LocalFileController(FileController, model.LocalFile):
+class LocalFileController(_LocalFileController):
     """File controller for local files"""
 
-    label: Optional[List[model.Label]] = [model.Label(text="Unnamed file")]
-    """The label of the file, defaults to 'Unnamed file'"""
-    path: Path
-    """The path to the file"""
-
     class Config:
         arbitrary_types_allowed = True
 
-    @classmethod
-    def from_other(
-        cls, other: "FileController", path: Path, **kwargs
-    ) -> "LocalFileController":
-        return other.cast(cls, path=path, **kwargs)
-
     def __init__(self, **kwargs):
+        path = kwargs.pop("path", None)
+        if path is not None and not kwargs.get("local_path"):
+            kwargs["local_path"] = str(path)
         super().__init__(**kwargs)
-        self._set_metadata()
+        if self.local_path:
+            self._set_metadata()
+
+    @classmethod
+    def from_other(cls, other, path=None, **kwargs) -> "LocalFileController":
+        if path is not None:
+            kwargs["local_path"] = str(path)
+        return other.cast(cls, **kwargs)
 
     def get(self) -> IO:
         self._set_metadata()
-        return open(self.path, "rb")
+        return super().get()
 
     def put(self, file: IO, **kwargs: Dict[str, Any]):
         self._set_metadata()
-        mode = "wb"
-        if isinstance(file, TextIOBase):
-            mode = "w"
-        with open(self.path, mode) as f:
-            # f.write(file.read())  # In-memory - limited by available RAM
-            shutil.copyfileobj(file, f)  # Chunked copy
-
-    def delete(self):
-        if os.path.exists(self.path):
-            os.remove(self.path)
+        super().put(file, **kwargs)
 
     def _set_metadata(self):
-        file = LocalFileController.extract_metadata(self.path)
-        self.label = file.label
+        self.label = LocalFileController.extract_metadata(self.path).label
 
     @classmethod
     def extract_metadata(cls, path: Path) -> model.LocalFile:
-        file = model.LocalFile(label=[model.Label(text=path.name)])
+        file = model.LocalFile(label=[model.Label(text=Path(path).name)])
         if os.path.exists(path):
             pass
             # stats = os.stat(path)

src/osw/controller/file/memory.py

@@ -1,28 +1,9 @@
-import shutil
-from io import BytesIO
-from typing import IO, Any, Dict, List, Optional
+"""In-memory file controller.
 
-from pydantic.v1 import Field
+The implementation moved to ``opensemantic.core``, which owns the file models.
+This module keeps the import path working.
+"""
 
-from osw.controller.file.base import FileController
-from osw.core import model
+from opensemantic.core.v1 import InMemoryController
 
-
-class InMemoryController(FileController, model.LocalFile):
-    """File controller for in-memory streams"""
-
-    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: Any = Field(default_factory=BytesIO)
-    """the stream to the file, any file-like object. Defaults to an empty
-    binary buffer. Byte-oriented, to match the get/put counterparts."""
-
-    class Config:
-        arbitrary_types_allowed = True
-
-    def get(self) -> IO:
-        return self.stream
-
-    def put(self, file: IO, **kwargs: Dict[str, Any]):
-        shutil.copyfileobj(file, self.stream)
+__all__ = ["InMemoryController"]

src/osw/controller/file/remote.py

@@ -1,31 +1,9 @@
-from abc import abstractmethod
-from typing import IO, Any, Dict
+"""Remote file controller.
 
-from osw.controller.file.base import FileController
-from osw.core import model
+The implementation moved to ``opensemantic.core``, which owns the file models.
+This module keeps the import path working.
+"""
 
-# TODO: add additional remove file with
-#  https://docs.prefect.io/2.11.4/concepts/filesystems/
+from opensemantic.core.v1 import RemoteFileController
 
-
-# Note: the order of the base classes is important
-# 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):
-    @abstractmethod
-    def get(self) -> IO:
-        pass
-
-    @abstractmethod
-    def put(self, file: IO, **kwargs: Dict[str, Any]):
-        pass
-
-    # @classmethod
-    # def from_local(self, local: "local.LocalFileController") -> "RemoteFileController":
-    #    rf = local.cast(self)
-    #    rf.put(local.get())
-    #    return rf
-
-    # def from_local(self, local: "local.LocalFileController") -> None:
-    #    with local.get() as f:
-    #        self.put(f)
+__all__ = ["RemoteFileController"]

src/osw/controller/file/wiki.py

@@ -2,9 +2,12 @@
 import logging
 import os
 from typing import IO, Any, Dict, List, Optional
+from urllib.parse import urlparse
 
 import mwclient.errors
+from oold.backend.auth import get_credential as _get_registered_credential
 
+from osw.auth import CredentialManager
 from osw.controller.file.base import FileController
 from osw.controller.file.remote import RemoteFileController
 from osw.core import OSW, model
@@ -79,13 +82,42 @@ def store_params_for_upload(
     return {**se_params, "overwrite": "replace remote"}
 
 
+_sessions: Dict[str, OSW] = {}
+"""Sessions by host, so several files of one wiki share a connection."""
+
+
+def session_for(url: str) -> OSW:
+    """An OSW session for the host of ``url``, from the registered credential.
+
+    The file entity may be stored somewhere other than its bytes, so the
+    lookup key is the URL the content lives at, not the entity's own IRI.
+    """
+    host = urlparse(url).netloc or url
+    session = _sessions.get(host)
+    if session is not None:
+        return session
+    try:
+        credential = _get_registered_credential(url)
+    except ValueError as error:
+        raise ValueError(
+            f"No credential registered for {host}. Pass osw= explicitly or "
+            "register one with oold.backend.auth.set_credential."
+        ) from error
+    cred_mngr = CredentialManager()
+    cred_mngr.add_credential(credential)
+    session = OSW(site=WtSite(WtSite.WtSiteConfig(iri=host, cred_mngr=cred_mngr)))
+    _sessions[host] = session
+    return session
+
+
 class WikiFileController(model.WikiFile, RemoteFileController):
     """File controller for wiki files"""
 
     label: Optional[List[model.Label]] = [model.Label(text="Unnamed file")]
     """the label of the file, defaults to 'Unnamed file'"""
-    osw: OSW
-    """the OSW instance to connect with"""
+    osw: Optional[OSW] = None
+    """the OSW instance to connect with. Left unset, it is created on first
+    use from the credential registered for download_url / access_url."""
     namespace: Optional[str] = "File"
     """the namespace of the file, defaults to 'File'"""
     title: Optional[str] = None
@@ -98,7 +130,10 @@ class Config:
 
     @classmethod
     def from_other(
-        cls, other: FileController, osw: OSW, **kwargs: Dict[str, Any]
+        cls,
+        other: FileController,
+        osw: Optional[OSW] = None,
+        **kwargs: Dict[str, Any],
     ) -> "WikiFileController":
         return super().from_other(other, osw=osw, **kwargs)
 
@@ -177,6 +212,7 @@ def get_to(self, other: "FileController"):
             other.put(response.raw)
 
     def put(self, file: IO, **kwargs: Dict[str, Any]):
+        self._ensure_session()
         # extract file meta information
         if hasattr(file, "name") and file.name is not None:
             name = os.path.basename(file.name)
@@ -235,6 +271,7 @@ def put_from(self, other: FileController, **kwargs: Dict[str, Any]):
         super().put_from(other, **kwargs)
 
     def delete(self):
+        self._ensure_session()
         file_page_name = f"{self.namespace}:{self.title}"
         file_page = self.osw.site.get_page(
             WtSite.GetPageParam(titles=[file_page_name])
@@ -244,12 +281,20 @@ def delete(self):
 
     @property
     def url(self):
+        self._ensure_session()
         return (
             f"{self.osw.mw_site.scheme}://{self.osw.mw_site.host}"
             f"/wiki/File:{self.title}"
         )
 
+    def _ensure_session(self) -> OSW:
+        """The session, connecting on first use when none was passed in."""
+        if self.osw is None:
+            self.osw = session_for(self._url())
+        return self.osw
+
     def _init(self, name=None, suffix=None):
+        self._ensure_session()
         # set the name attribute to the actual file name, e.g., "image.png"
         if self.name is None:
             self.name = name