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

[LukasGold]

Closes #68.

Stacked on #148, which makes InMemoryController constructible. Merge that first, this base retargets to main automatically.

Changes

• FileController.uri: the location of the file in the URI scheme of its storage backend. Concrete, returns None by default.
• LocalFileController.uri: file://, via Path.absolute().as_uri(), see https://en.wikipedia.org/wiki/File_URI_scheme.
• RemoteFileController.uri: the stored url. S3FileController and WikiFileController inherit it, so they report s3://... and https://.../wiki/File:... without an override.
• InMemoryController.uri: None.
• tests/test_file_controller_uri.py: 7 offline tests.

Rationale

A caller holding a FileController had no way to ask where the file actually is. Each subclass kept that in a different shape: a Path, a url, or nothing at all.

WikiFileController already builds the page url in its url property (src/osw/controller/file/wiki.py:167), and S3FileController parses self.url for its bucket and key, so putting uri on RemoteFileController covers both from what they already carry.

uri is a read interface: derived on every access, never stored, so it cannot go stale. Each controller keeps the handle its backend actually needs and answers uri in its own scheme. The wider harmonization of path / url / uri, and a from_uri() write-side counterpart, are proposed in #68 (comment) and are out of scope here.

Notes

• The property is deliberately not abstract. pydantic v1's ModelMetaclass extends ABCMeta, so @abstractmethod is enforced at instantiation and an abstract uri would break every file controller outside this package that predates it. A concrete None default keeps this a feat, not a breaking change.
• InMemoryController returns None rather than raising. A stream is a legitimate file source, it just has no address.

Verification

Offline suite passes (66 passed, 1 skipped). The wiki and S3 controllers need a live backend, so their uri is covered through RemoteFileController and, for the wiki page url, by calling the property directly on a stand-in.

[github-actions]

Release preview

No version bump from the current commits (stays at v2.0.2). Use conventional commit types (feat, fix, ...) to trigger a release.

Changelog preview (truncated)

_{Preview via python-semantic-release and conventional commits.}

[LukasGold]

Changed uri from an abstract property to a concrete one returning None (ad43d07).

Reason: pydantic v1's ModelMetaclass extends ABCMeta, so @abstractmethod on an osw model is enforced at instantiation. Verified against main, where a file controller defining only get and put constructs fine. With the abstract version of this PR the same class raises:

TypeError: Can't instantiate abstract class Downstream without an implementation
for abstract method 'uri'

That is a breaking change for any file controller outside this package, and it was not marked as one, so it would have shipped as a minor release. tests/test_file_controller_uri.py::test_a_controller_that_predates_uri_still_works pins the behaviour.

None is also the honest default: before this PR no controller had a uri at all, so a subclass that does not override it is in exactly the state it was in before, and InMemoryController shows None is a real answer rather than a placeholder.

Follow-up on harmonizing path / url / uri across the controllers, plus a from_uri() counterpart: #68 (comment).

[LukasGold]

Reasonable changes that provide a uniform access point

[LukasGold]

Closing and reopening to make the Integration workflow attach to this PR. It never ran here because the branch was originally stacked on fix/in-memory-file-upload, and retargeting to main did not register the pull_request trigger.