thds.mops 3.6.20250219172032__py3-none-any.whl

thds/mops/pure/core/script_support.py

@@ -0,0 +1,25 @@
+"""Support for transferring execution of a function
+when the function is defined inside the __main__ module.
+
+Only works if you 'transfer execution' to the same process.
+"""
+import typing as ty
+
+_LOCAL_MAIN_FUNCTIONS: ty.Dict[str, ty.Callable] = dict()
+
+
+def add_main_module_function(function_name: str, function: ty.Callable) -> None:
+    """This only works if you end up running remotely in the same process."""
+    _LOCAL_MAIN_FUNCTIONS[function_name] = function
+
+
+def get_main_module_function(fname: str) -> ty.Callable:
+    """This only works if you end up running 'remotely' in the same process."""
+    try:
+        return _LOCAL_MAIN_FUNCTIONS[fname]
+    except KeyError:
+        raise ValueError(
+            f"Serialized function {fname} that was in the __main__ module"
+            " and attempted to transfer control to a different process."
+            " Please move your function to a module that is not __main__."
+        ) from KeyError

thds/mops/pure/core/serialize_big_objs.py

@@ -0,0 +1,73 @@
+"""Bring your own serialization."""
+
+import typing as ty
+from weakref import WeakValueDictionary
+
+from thds.core.log import getLogger
+
+from ..._utils.once import Once
+from .types import Deserializer, Serializer, T
+
+V = ty.TypeVar("V")
+
+logger = getLogger(__name__)
+
+
+class NeedsToBeWeakReferenceable(TypeError):
+    pass
+
+
+class ByIdRegistry(ty.Generic[T, V]):
+    """When you want to use something as the key for a runtime-only
+    dictionary, but the thing doesn't support being hashed.
+    """
+
+    def __init__(self) -> None:
+        self._objects: ty.Dict[int, T] = WeakValueDictionary()  # type: ignore
+        self._values: ty.Dict[int, V] = dict()
+
+    def __setitem__(self, obj: T, value: V) -> None:
+        try:
+            self._objects[id(obj)] = obj
+            self._values[id(obj)] = value
+        except TypeError as te:
+            raise NeedsToBeWeakReferenceable(f"{obj} needs to be weak-referenceable") from te
+
+    def __contains__(self, obj: T) -> bool:
+        return id(obj) in self._objects and self._objects[id(obj)] is obj
+
+    def __getitem__(self, obj: T) -> V:
+        if obj not in self:
+            raise KeyError(str(obj))
+        return self._values[id(obj)]
+
+
+class ByIdSerializer:
+    """Proxies id()-based memoizing serialization for large in-memory objects.
+
+    For use with something like CallablePickler, which will allow this
+    object to recognize registered objects and provide their
+    serialization.
+
+    Thread-safe at the time of (deferred) serialization, but all calls
+    to `register` should be done prior to beginning concurrent serialization.
+
+    The Deserializer returned by the Serializer should ideally not
+    occupy much memory, as it will be cached.
+    """
+
+    def __init__(self, registry: ByIdRegistry[ty.Any, Serializer]) -> None:
+        self._registry = registry
+        self._desers: ty.Dict[int, Deserializer] = dict()
+        self._once = Once()
+
+    def __call__(self, obj: ty.Any) -> ty.Union[None, Deserializer]:
+        if obj in self._registry:
+
+            def serialize_and_cache() -> None:
+                logger.info(f"Serializing object {type(obj)} {id(obj)}")
+                self._desers[id(obj)] = self._registry[obj](obj)
+
+            self._once.run_once(id(obj), serialize_and_cache)
+            return self._desers[id(obj)]
+        return None

thds/mops/pure/core/serialize_paths.py

@@ -0,0 +1,149 @@
+import hashlib
+import typing as ty
+from functools import partial
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+
+from thds import humenc
+from thds.core.hash_cache import hash_file
+from thds.core.log import getLogger
+
+from ..._utils import once
+from . import deferred_work
+
+Downloader = ty.Callable[[], Path]
+logger = getLogger(__name__)
+_1_MB = 2**20
+
+
+def human_sha256b64_file_at_paths(path: Path) -> str:
+    """Return a human-readable hash of the file at the given path."""
+    assert path.exists(), path
+    return humenc.encode(hash_file(path, hashlib.sha256()))
+
+
+class _ProcessLockingPathContentAddresser:
+    """Hashes the data at a path, but only once per unique resolved
+    Path seen, because hashing a large file is expensive and such
+    Paths are often shared across many invocations.
+
+    In general, you will want only one instance of this per
+    application/process, to take advantage of the caching behavior.
+
+    This does imply that each use of a Path is, as documented in the
+    README, a reference to an immutable, write-at-most-once file, at
+    least during the lifetime of the process hosting this
+    object. Passing the same Path multiple times with different
+    contents, and expecting it to get hashed and uploaded each time,
+    will not work.
+    """
+
+    def __init__(self, once: once.Once):
+        self.once = once
+        self.paths_to_keys: ty.Dict[str, str] = dict()
+
+    def __call__(self, path: Path) -> str:
+        """Return a remote key (sha256 hash in human-base64) for a path."""
+        resolved = str(path.resolve())
+        # we now put all paths at the hash of their own contents which
+        # allows us to avoid uploading duplicated data even from two
+        # different file paths that happen to share the same contents.
+        #
+        # This _also_ allows us to be more confident that memoization
+        # bugs arising from reuse of Paths pointing to different
+        # underlying file contents across separate process lifetimes
+        # cannot happen - a given Path will be represented inside the
+        # pickle by something that represents the (immutable) file
+        # contents itself, rather than by a mutable reference (the
+        # path).
+
+        def _hash_and_remember_path() -> None:
+            self.paths_to_keys[resolved] = human_sha256b64_file_at_paths(path)
+
+        self.once.run_once(resolved, _hash_and_remember_path)
+        return self.paths_to_keys[resolved]
+
+
+class PathStream(ty.Protocol):
+    def local_to_remote(self, __path: Path, __key: str) -> None:
+        ...  # pragma: no cover
+
+    def get_downloader(self, __key: str) -> Downloader:
+        ...  # pragma: no cover
+
+
+class NotAFileError(ValueError):
+    """We err on the side of caution in Mops 2.0 by never allowing
+    Paths that are not actual files to be serialized on either side.
+
+    This error is not intended to be caught; it is intended to inform
+    the developer that they have made a coding mistake by passing an
+    incorrect Path to a function that is supposed to be transferring
+    execution via a Runner.
+
+    In the future we might add support for directories if it is desired.
+    """
+
+
+def _serialize_file_path_as_upload(
+    once: once.Once, path_keyer: _ProcessLockingPathContentAddresser, stream: PathStream, local_src: Path
+) -> ty.Optional[Downloader]:
+    if not local_src.exists():
+        raise NotAFileError(f"You asked mops to upload the path {local_src}, but it does not exist.")
+    if not local_src.is_file():
+        raise NotAFileError(f"You asked mops to upload the Path {local_src}, but it is not a file.")
+
+    remote_root = path_keyer(local_src)
+    # I am creating a root 'directory' so that we can put debug info
+    # side-by-side with the actual bytes, without interfering in any
+    # way with the determinism of the hashed bytes themselves.
+    remote_key = remote_root + "/_bytes"
+
+    def upload() -> None:
+        size = local_src.stat().st_size
+        formatted_size = f"{size / _1_MB:,.2f} MB"
+        log = logger.info if size > 10 * _1_MB else logger.debug
+        log(
+            f"Uploading Path {local_src} of size {formatted_size} to {remote_key} - "
+            "its contents will get 'unpickled' on the other side"
+            " as a Path pointing to a local, read-only file."
+        )
+        stream.local_to_remote(local_src, remote_key)
+        with NamedTemporaryFile("w") as tmp:
+            tmp.write(str(local_src))
+            tmp.flush()
+            stream.local_to_remote(  # purely debug info
+                Path(tmp.name),
+                f"{remote_root}/pathname-_{str(local_src).replace('/', '_')}",
+            )
+
+    logger.debug("Adding deferred upload of %s", remote_key)
+    deferred_work.add(
+        __name__,
+        remote_key,
+        partial(once.run_once, remote_key, upload),
+    )
+    return stream.get_downloader(remote_key)
+
+
+class CoordinatingPathSerializer:
+    """Allow local file Paths to be serialized as streaming objects and then
+    deserialized remotely by downloading them from a stream and then
+    returning a Path object pointing to the downloaded file.
+    """
+
+    def __init__(self, stream: PathStream, once: once.Once):
+        self.stream = stream
+        self.once = once
+        self.path_addresser = _ProcessLockingPathContentAddresser(once)
+
+    def __call__(self, maybe_path: ty.Any) -> ty.Optional[ty.Callable[[], Path]]:
+        """Returns a persistent ID compatible with CallableUnpickler for any real file Path.
+
+        The Persistent ID will actually be a thunk that is self-unpickling.
+        """
+        if isinstance(maybe_path, Path):
+            return _serialize_file_path_as_upload(
+                self.once, self.path_addresser, self.stream, maybe_path
+            )
+        return None

thds/mops/pure/core/source.py

@@ -0,0 +1,291 @@
+"""Bidirectional, context-sensitive translation: Source <--> (Hashref | URI).
+
+Hashrefs - passing data blobs of many kinds into remote functions by their Hash where
+possible, then using a separate lookup file per hash to tell us where the actual data is
+stored.
+
+- local file source containing a Hash - can be optimized with hashref
+- remote file source containing a Hash - can be optimized with hashref
+- remote file source only having URI - cannot be optimized - passed as a raw URI.
+
+Decoupling hashref creation from potential upload is important because it lets us avoid
+upload in cases where the Shim turns out to be a local machine shim.
+
+We create hashrefs for Sources on the local machine in a shared location. Since this
+data is immutable and content-addressed, there should be no serious concurrency objections
+to this approach.
+
+Then, if we cross a boundary into a Shim that will start execution on a different
+machine, we serialize the local Path to content-addressed storage in the current active
+storage root, and we then create a hashref in the active storage root (again, these
+should be effectively immutable on the shared store even if they will mostly likely get
+rewritten multiple times).
+
+On the remote side, we will first check the local hashref location. It may very well not
+exist at all.  If it does, we should attempt to follow it, but the referent may not
+exist (for whatever reason) and in all cases we are able to fall back to looking for a
+remote hashref and following its reference.
+
+We are keeping the core business logic completely separate from pickling.  All
+serialization methods will have to choose how to represent the information returned by
+this module, but it should be able to call back into this module with that same state to
+have a Source object returned to it while it performs low-level deserialization.
+"""
+
+import io
+import typing as ty
+from functools import partial
+from pathlib import Path
+
+from thds import humenc
+from thds.core import hashing, log, source
+from thds.core.files import is_file_uri, to_uri
+from thds.core.source import Source
+from thds.core.types import StrOrPath
+
+from . import deferred_work
+from .content_addressed import wordybin_content_addressed
+from .output_naming import invocation_output_uri
+from .uris import active_storage_root, lookup_blob_store
+
+_REMOTE_HASHREF_PREFIX = "mops2-hashrefs"
+_LOCAL_HASHREF_DIR = ".mops2-local-hashrefs"
+logger = log.getLogger(__name__)
+
+
+def _hash_to_str(hash: hashing.Hash) -> str:
+    # i see no reason to not remain opinionated and "debug-friendly" with the user-visible
+    # encoding of our hashes when they are being stored on a blob store/FS of some kind.
+    return f"{hash.algo}-{humenc.encode(hash.bytes)}"
+
+
+def _hashref_uri(hash: hashing.Hash, type: ty.Literal["local", "remote"]) -> str:
+    # the .txt extensions are just for user-friendliness during debugging
+    if type == "remote":
+        base_uri = active_storage_root()
+        return lookup_blob_store(base_uri).join(
+            base_uri, _REMOTE_HASHREF_PREFIX, _hash_to_str(hash) + ".txt"
+        )
+    local_hashref = Path.home() / _LOCAL_HASHREF_DIR / f"{_hash_to_str(hash)}.txt"
+    return to_uri(local_hashref)
+
+
+def _read_hashref(hashref_uri: str) -> str:
+    """Return URI represented by this hashref. Performs IO."""
+    uri_bytes = io.BytesIO()
+    lookup_blob_store(hashref_uri).readbytesinto(hashref_uri, uri_bytes)
+    uri = uri_bytes.getvalue().decode()
+    assert uri, f"Hashref from {hashref_uri} is empty"
+    return uri
+
+
+def _write_hashref(hashref_uri: str, uri: str) -> None:
+    """Write URI to this hashref. Performs IO."""
+    assert uri, f"Should never encode hashref ({hashref_uri}) pointing to empty URI"
+    lookup_blob_store(hashref_uri).putbytes(hashref_uri, uri.encode(), type_hint="text/plain")
+
+
+def source_from_hashref(hash: hashing.Hash) -> Source:
+    """Re-create a Source from a Hash by looking up one of two Hashrefs and finding a
+    valid Source for the data."""
+    local_file_hashref_uri = _hashref_uri(hash, "local")
+    remote_hashref_uri = _hashref_uri(hash, "remote")
+
+    def remote_uri(allow_blob_not_found: bool = True) -> str:
+        try:
+            return _read_hashref(remote_hashref_uri)
+        except Exception as e:
+            if not allow_blob_not_found or not lookup_blob_store(
+                remote_hashref_uri,
+            ).is_blob_not_found(e):
+                # 'remote' blob not found is sometimes fine, but anything else is weird
+                # and we should raise.
+                raise
+            return ""
+
+    try:
+        # we might be on the same machine where this was originally invoked.
+        # therefore, there may be a local path we can use directly.
+        # Then, there's no need to bother grabbing the remote_uri
+        # - but for debugging's sake, it's quite nice to actually
+        # have the full remote URI as well even if we're ultimately going to use the local copy.
+        return source.from_file(_read_hashref(local_file_hashref_uri), hash=hash, uri=remote_uri())
+    except FileNotFoundError:
+        # we are not on the same machine as the local ref. assume we need the remote URI.
+        pass
+    except Exception as e:
+        if not lookup_blob_store(local_file_hashref_uri).is_blob_not_found(e):
+            # 'local' blob not found is fine, but anything else is weird and we should raise.
+            raise
+
+    # no local file, so we assume there must be a remote URI.
+    return source.from_uri(remote_uri(False), hash=hash)
+
+
+def _upload_and_create_remote_hashref(local_path: Path, remote_uri: str, hash: hashing.Hash) -> None:
+    # exists only to provide a local (non-serializable) closure around local_path and remote_uri.
+    lookup_blob_store(remote_uri).putfile(local_path, remote_uri)
+    # make sure we never overwrite a hashref until it's actually going to be valid.
+    _write_hashref(_hashref_uri(hash, "remote"), remote_uri)
+
+
+def _auto_remote_uri(hash: hashing.Hash) -> str:
+    """Pick a remote URI for a file/source that has the given hash.
+
+    The underlying implementation is shared with the content-addressing that is used
+    throughout mops.
+    """
+    return wordybin_content_addressed(hash).bytes_uri
+
+
+def prepare_source_argument(source_: Source) -> ty.Union[str, hashing.Hash]:
+    """For use on the orchestrator side, during serialization of the invocation.
+
+    You either end up with a Hashref created under the current HASHREF_ROOT, or you end up
+    with just a URI, which is not amenable to hashref optimization.
+    """
+    if not source_.hash:
+        # we cannot optimize this one for memoization - just return the URI.
+        return source_.uri
+
+    local_path = source_.cached_path
+    if local_path and local_path.exists():
+        # register creation of local hashref...
+        deferred_work.add(
+            __name__ + "-localhashref",
+            source_.hash,
+            partial(_write_hashref, _hashref_uri(source_.hash, "local"), str(local_path)),
+        )
+        # then also register pending upload - if the URI is a local file, we need to determine a
+        # remote URI for this thing automagically; otherwise, use whatever was already
+        # specified by the Source itself.
+        remote_uri = source_.uri if not is_file_uri(source_.uri) else _auto_remote_uri(source_.hash)
+        deferred_work.add(
+            __name__ + "-remotehashref",
+            source_.hash,
+            partial(_upload_and_create_remote_hashref, local_path, remote_uri, source_.hash),
+        )
+    else:
+        # prepare to (later, if necessary) create a remote hashref, because this Source
+        # represents a non-local resource.
+        deferred_work.add(
+            __name__,
+            source_.hash,
+            partial(_write_hashref, _hashref_uri(source_.hash, "remote"), source_.uri),
+        )
+
+    return source_.hash
+
+
+def perform_source_uploads() -> None:  # has been replaced by a general work-deferring mechanism.
+    deferred_work.perform_all()
+
+
+# RETURNING FROM REMOTE
+#
+# when returning a Source from a remote, we cannot avoid the upload.  this is because the
+# uploaded data is part of the memoized result, and memoization by definition is available
+# to all callers, even those on other machines/environments.
+#
+# A good example of where this is necessary is memoizing Person API test data in CI.  the
+# code runs locally, but the goal is to create an output file that can be reused next time
+# it runs (locally or in CI). And for that to be possible, the output _must_ be uploaded.
+#
+# This does not mean that the Source itself must be uploaded immediately upon creation;
+# just that mops must detect Sources in the return value and must force an upload on them.
+# In essence, this creates a bifurcated code path for Sources during serialization; if
+# we're "on the way out", we avoid uploading until it is clear that the data will be used
+# in a remote environment. Whereas "on the way back", we must always upload, and nothing
+# can or should be deferred; upload should happen at the time of serialization.
+#
+# Nevertheless, a local caller should still be able to short-circuit the _download_ by
+# using a locally-created File, if on the same machine where the local file was created.
+
+
+class SourceResult(ty.NamedTuple):
+    """Contains the fully-specified local URI and remote URI, plus (probably) a Hash.
+
+    Everything is defined right here. No need for any kind of dynamic lookup, and
+    optimization buys us nothing, since memoization only operates on arguments.
+    """
+
+    remote_uri: str
+    hash: ty.Optional[hashing.Hash]
+    file_uri: str
+
+
+def prepare_source_result(source_: Source) -> SourceResult:
+    """Call from within the remote side of an invocation, while serializing the function return value.
+
+    Forces the Source to be present at a remote URI which will be available once
+    returned to the orchestrator.
+
+    The full output URI is auto-generated if one is not already provided, because we're
+    guaranteed to be in a remote context, which provides an invocation output root URI
+    where we can safely place any named output.
+    """
+    if not is_file_uri(source_.uri):
+        if source_.cached_path and Path(source_.cached_path).exists():
+            # it exists locally - an upload may be necessary.
+            file_uri = to_uri(source_.cached_path)
+            lookup_blob_store(source_.uri).putfile(source_.cached_path, source_.uri)
+            logger.info("Uploading Source to %s", source_.uri)
+        else:
+            file_uri = ""
+            logger.debug("Creating a SourceResult for a URI that is presumed to already be uploaded.")
+        return SourceResult(source_.uri, source_.hash, file_uri)
+
+    # by definition, if this is a file URI, it now needs to be uploaded, because we could
+    # be transferring back to an orchestrator on a different machine, but also because a
+    # future caller on a different machine could try to use this memoized result.
+    local_path = source.path_from_uri(source_.uri)
+    assert local_path.exists(), f"{local_path} does not exist"
+    logger.debug("Automatically selecting a remote URI for a Source being returned.")
+    remote_uri = invocation_output_uri(name=local_path.name)
+    # the line above is a bit of opinionated magic. it uses the 'end' of the filename
+    # to automagically assign a meaningful name to the output remote URI.
+    #
+    # If users do not like this automatically assigned remote URI name, they can construct
+    # the Source themselves and provide a remote URI (as well as, optionally, a
+    # local_path), and we will use their remote URI.
+    lookup_blob_store(remote_uri).putfile(local_path, remote_uri)
+    # upload must _always_ happen on remotely-returned Sources, as detailed above.
+    # There is no advantage to waiting to upload past this point.
+    return SourceResult(remote_uri, source_.hash, source_.uri)
+
+
+def source_from_source_result(remote_uri: str, hash: ty.Optional[hashing.Hash], file_uri: str) -> Source:
+    """Call when deserializing a remote function return value on the orchestrator side, to
+    replace all SourceResults with the intended Source object.
+    """
+    if not file_uri:
+        return source.from_uri(remote_uri, hash=hash)
+
+    local_path = source.path_from_uri(file_uri)
+    if local_path.exists():
+        try:
+            # since there's a remote URI, it's possible a specific consumer might want to
+            # get access to that directly, even though the default data access would still
+            # be to use the local file.
+            return source.from_file(local_path, hash=hash, uri=remote_uri)
+        except Exception as e:
+            logger.warning(
+                f"Unable to reuse destination local path {local_path} when constructing Source {remote_uri}: {e}"
+            )
+    return source.from_uri(remote_uri, hash=hash)
+
+
+def create_source_at_uri(filename: StrOrPath, destination_uri: str) -> Source:
+    """Public API for creating a Source with a manually-specified remote URI
+    within a remote function invocation. Not generally recommended.
+
+    Use this if you want to provide specific URI destination for a file that exists
+    locally, rather than using the automagic naming behavior provided by creating a Source
+    with `from_file`, which is standard.
+
+    _Only_ use this if you are willing to immediately upload your data.
+
+    """
+    source_ = source.from_file(filename, uri=destination_uri)
+    lookup_blob_store(destination_uri).putfile(Path(filename), destination_uri)
+    return source_

thds/mops/pure/core/types.py

@@ -0,0 +1,142 @@
+"""Core abstractions for the remote runner system."""
+
+import typing as ty
+from pathlib import Path
+
+from typing_extensions import Protocol
+
+from thds.core import config
+
+T = ty.TypeVar("T")
+F = ty.TypeVar("F", bound=ty.Callable)
+
+Deserializer = ty.Callable[[], T]
+Serializer = ty.Callable[[T], Deserializer]
+SerializerHandler = ty.Callable[[T], ty.Union[None, Deserializer]]
+# returns None if the object should be serialized normally.
+# Otherwise returns a Deserializing Callable that will itself return the deserialized object when called.
+
+
+class Runner(Protocol):
+    """A Runner copies a function, its arguments, and discoverable
+    context to a location that can be picked up from a future remote
+    process, executes that process remotely, and later pulls the
+    result of that remote process back to the local caller process.
+
+    It is essentially the same abstraction as
+    `concurrent.futures.Executor.submit`, or
+    `multiprocessing.Pool.apply`.
+
+    `use_runner` uses this abstraction to provide a way of wrapping a
+    function and calling it elsewhere.
+    """
+
+    def __call__(
+        self,
+        __f: ty.Callable[..., T],
+        __args: ty.Sequence,
+        __kwargs: ty.Mapping[str, ty.Any],
+    ) -> T:
+        ...  # pragma: no cover
+
+
+class NoResultAfterInvocationError(Exception):  # TODO remove in v4.
+    """Runners should raise this if the remotely-invoked function does not provide any result."""
+
+
+class NoResultAfterShimSuccess(NoResultAfterInvocationError):
+    """Raised this if the shim returns with no error, but no result is found in the blob store.
+
+    A better name for NoResultAfterInvocationError.
+    """
+
+
+class NotARunnerContext(Exception):
+    """Mops may raise this if some code intended to be run under a
+    Runner context is invoked outside that context.
+    """
+
+
+AnyStrSrc = ty.Union[ty.AnyStr, ty.Iterable[ty.AnyStr], ty.IO[ty.AnyStr], Path]
+
+
+DISABLE_CONTROL_CACHE = config.item(
+    "thds.mops.pure.disable_control_cache", default=False, parse=config.tobool
+)
+# set the above to True in order to specifically opt out of read-path caching of
+# mops-created files. This can apply to a local (stack) context, or can
+# apply globally to the process. The former may be used selectively within mops
+# for issues of known correctness, e.g. locks, whereas the latter will be useful
+# for debugging any cases where files have been remotely deleted.
+
+
+class BlobStore(Protocol):
+    """A minimal interface that can be supported by almost any type of key-value store
+    that has some basic concept of hierarchical pathing (as implemented by join and
+    split).
+
+    getfile and putfile are pathways intended for large files that are passed as arguments
+    to, or returned as results from, mops-wrapped functions.  Implementations may wish to
+    make sure they can perform streaming reads and writes. However, mops itself does not
+    generate such files itself, so your use case may not benefit from supporting
+    memory-efficient reads and writes if your application does not deal with large files
+    via pathlib.Path or thds.core.Source objects.
+
+    In the methods below, `type_hint` is a parameter that must be _accepted_ as a keyword
+    argument by the implementation, but is intended for use mainly as a hint to loggers
+    and other debugging setups.  It does not need to affect the implementation in any way.
+    """
+
+    def control_root(self, __remote_uri: str) -> str:
+        """Return the mops-specific root of the blob store for this URI.
+
+        Essentially, define a place for mops to store its control files under its own internal prefix.
+        """
+
+    def readbytesinto(
+        self, __remote_uri: str, __stream_or_file: ty.IO[bytes], *, type_hint: str = "bytes"
+    ) -> None:
+        """Allows reading into any stream, including a stream-to-disk.
+
+        May optimize reads by returning a cached version of the file if it has been seen before.
+        """
+
+    def getfile(self, __remote_uri: str) -> Path:
+        """Read a remote uri directly into a Path controlled by the implementation.
+        Optimizations involving caches for remotes may be applied.
+        The returned file is by definition read-only.
+        """
+
+    def putbytes(self, __remote_uri: str, __data: AnyStrSrc, *, type_hint: str = "bytes") -> None:
+        """Upload bytes from any stream."""
+
+    def putfile(self, __path: Path, __remote_uri: str) -> None:
+        """Upload a file that exists on the local
+        filesystem. Optimizations including softlinking into caches may be
+        applied.
+        """
+
+    def exists(self, __remote_uri: str) -> bool:
+        """Check if a file exists. May optimize by assuming that files previously seen
+        have not been deleted - since this is intended only for mops control files,
+        and mops never deletes any control files.
+        """
+
+    def join(self, *parts: str) -> str:
+        """Join multiple parts of a URI into one. In actual use, the first part will always
+        be a storage root, e.g.:
+
+        join(['adls://foo/bar', 'baz', 'beans']) -> 'adls://foo/bar/baz/beans'
+        """
+
+    def split(self, uri: str) -> ty.List[str]:
+        """Must return the storage root as a single string,
+        followed by the path component split along the same lines that join would concatenate.
+        """
+
+    def is_blob_not_found(self, __exc: Exception) -> bool:
+        ...
+
+
+Args = ty.Sequence
+Kwargs = ty.Mapping[str, ty.Any]