Add property uri to every file controller #68

Activity

1. LukasGold commented on Sep 2, 2026

   

   LukasGold

   on Sep 2, 2026

   Contributor

   More actions

   path / url / uri across the file controllers

   #158 adds uri but leaves path and url in place, so all three now name a location. Proposal for how they should relate, for discussion before anything is changed.

   uri is the read interface

   • Every controller answers uri in the scheme of its own backend: file:// for https://github.com/OpenSemanticLab/osw-python/blob/main/src/osw/controller/file/local.py, s3:// for S3FileController, https://<domain>/wiki/File:... for WikiFileController, None for InMemoryController.
   • uri is derived on every access and never stored, so it cannot go stale when the underlying handle changes.
   • Callers that only want to know where a file lives, log it, compare two controllers, or hand a location to something else use uri and nothing else.

   path and url stay, as backend-native handles

   They are not redundant with uri, they are the input uri is derived from, and each is the type its backend actually works with:

   • LocalFileController.path is a pathlib.Path and is used as a path, not as a string: src/osw/express.py:335, :367, :368. It is also part of the public return of osw_download_file(...), which callers use to open the downloaded file.
   • model.S3File.url is a field of the wiki schema at Category:OSWc43f749badcb4490a785505de1fc7d20, fetched at runtime by https://github.com/OpenSemanticLab/osw-python/blob/main/examples/file_upload_download.py#L22-L24. Renaming it is a schema change plus a jsondata migration on every existing S3File page, not a Python-only rename.
   • WikiFileController.url is already a derived property (https://github.com/OpenSemanticLab/osw-python/blob/main/src/osw/controller/file/wiki.py#L167), so there it is uri under another name.

   So the collapse happens at the interface, not in the storage: one name to read a location, the native handle kept where the backend needs it. Removing path and url outright would be a breaking change for a gain that uri already delivers.

   Missing piece: the write side

   uri has no counterpart for going the other way. A from_uri() classmethod on FileController that dispatches on the scheme would close that:

   FileController.from_uri("file:///tmp/a.txt")                    # -> LocalFileController
   FileController.from_uri("s3://bucket/key")                      # -> S3FileController
   FileController.from_uri("https://wiki.example.org/wiki/File:X") # -> WikiFileController

   with FileController.from_uri(c.uri) round-tripping for every controller that has a uri. That is what makes uri an actual interchange format rather than a display string, and it gives from_other / put_from a way to start from a location instead of an already-built controller.

   Loose ends

   • model.RemoteFile does not declare url, so RemoteFileController.uri returning self.url relies on a contract the subclasses happen to keep rather than one the base class states. Declaring url on RemoteFile would fix that, again as a schema change.
   • The wiki controllers need credentials to build a uri, so from_uri for https:// cannot be a pure constructor. It needs an osw or cred_mngr argument, unlike the local and S3 cases.