thds.adls 3.0.20250116223841__py3-none-any.whl

thds/adls/md5.py

@@ -0,0 +1,60 @@
+"""Why MD5 when it's no longer a good choice for most use cases?
+Because Azure/ADLS support Content-MD5 but nothing else, and I don't
+want to lie to them and get us confused later.
+
+Thankfully, there are no real security concerns for us with purely
+internal code and data sets.
+
+That said, please _do not_ use MD5 for non-Azure things. Prefer SHA256
+if at all possible.
+"""
+import hashlib
+import typing as ty
+from pathlib import Path
+
+from thds.core.hash_cache import hash_file
+from thds.core.hashing import SomehowReadable, hash_anything, hash_using
+from thds.core.types import StrOrPath
+
+AnyStrSrc = ty.Union[SomehowReadable, ty.Iterable[ty.AnyStr]]
+# this type closely corresponds to what the underlying DataLakeStorageClient will accept for upload_data.
+
+
+def md5_file(file: StrOrPath) -> bytes:
+    """Raise exception if it cannot be read.
+
+    Safely caches the hash on your local filesystem (uses mtimes to
+    determine staleness).
+    """
+    return hash_file(file, hashlib.md5())
+
+
+def hex_md5_str(string: str) -> str:
+    return hash_using(string.encode(), hashlib.md5()).hexdigest()
+
+
+def try_md5(data: AnyStrSrc) -> ty.Optional[bytes]:
+    """Ideally, we calculate an MD5 sum for all data that we upload.
+
+    The only circumstances under which we cannot do this are if the
+    stream does not exist in its entirety before the upload begins.
+    """
+    if isinstance(data, Path):
+        return md5_file(data)
+    res = hash_anything(data, hashlib.md5())
+    if res:
+        return res.digest()
+    return None
+
+
+def is_reasonable_b64(md5: str):
+    if len(md5) == 22:
+        return True
+    if len(md5) == 24 and md5.endswith("=="):
+        return True
+    return False
+
+
+def check_reasonable_md5b64(maybe_md5: str):
+    if not is_reasonable_b64(maybe_md5):
+        raise ValueError(f"MD5 '{maybe_md5}' is not a reasonable MD5.")

thds/adls/meta.json

@@ -0,0 +1,8 @@
+{
+  "git_commit": "8119ce98e26d99335cda51ac5cbebbcd6d87c416",
+  "git_branch": "task/ci/open-source",
+  "git_is_clean": true,
+  "pyproject_version": "3.0.20250116223841",
+  "thds_user": "peter.gaultney",
+  "misc": {}
+}

thds/adls/named_roots.py

@@ -0,0 +1,26 @@
+"""Just a utility for keeping actual Storage Account+Container pairs (AdlsRoots) defined
+in a central location and referencing those by name throughout your codebase.
+"""
+
+import typing as ty
+
+from .fqn import AdlsRoot
+
+_NAMED_ROOTS: ty.Dict[str, AdlsRoot] = dict()
+
+
+def add(**named_roots: AdlsRoot) -> None:
+    """Globally sets some named roots, as a layer of indirection for ADLS URIs."""
+    _NAMED_ROOTS.update(named_roots)
+
+
+def require(name: str) -> AdlsRoot:
+    if name not in _NAMED_ROOTS:
+        raise ValueError(f"Unknown named root: {name}")
+
+    return _NAMED_ROOTS[name]
+
+
+def require_uri(name: str) -> str:
+    """For use when a system expects a URI rather than the in-house AdlsRoot representation."""
+    return str(require(name))

thds/adls/resource/__init__.py

@@ -0,0 +1,36 @@
+"""The reason for a hashed resource is that it enables worry-free caching.
+
+If under any circumstances we re-use a name/URI with different bytes,
+then having captured a hash will enable us to transparently detect the
+situation and re-download.
+
+It is strongly recommended that you construct these using `of`, as
+that will avoid the accidental, invalid creation of an
+AdlsHashedResource containing an empty hash.
+
+How to get the hash itself?
+
+From our experience, it seems that any file uploaded using Azure
+Storage Explorer will have an MD5 calculated locally before upload and
+that will be embedded in the remote file. You can look in the
+properties of the uploaded file for Content-MD5 and copy-paste that
+into whatever you're writing.
+
+Programmatically, you can instead use `resource.upload`, which will
+return to you an in-memory AdlsHashedResource object. If you want to
+store it programmatically rather than in the source code, it's
+recommended that you use `resource.to_path`, and then load it using
+`resource.from_path`.
+
+Prefer importing this module `as resource` or `from thds.adls
+import resource`, and then using it as a namespace,
+e.g. `resource.of(uri)`.
+"""
+from .core import AdlsHashedResource, from_source, get, of, parse, serialize, to_source  # noqa: F401
+from .file_pointers import resource_from_path as from_path  # noqa: F401
+from .file_pointers import resource_to_path as to_path  # noqa: F401
+from .file_pointers import validate_resource as validate  # noqa: F401
+from .up_down import get_read_only, upload  # noqa: F401
+from .up_down import verify_or_create_resource as verify_or_create  # noqa: F401
+
+AHR = AdlsHashedResource  # just an alias

thds/adls/resource/core.py

@@ -0,0 +1,79 @@
+import json
+import typing as ty
+
+from thds.core import hashing, log, source
+from thds.core.hashing import b64
+
+from ..errors import blob_not_found_translation
+from ..fqn import AdlsFqn
+from ..global_client import get_global_fs_client
+from ..md5 import check_reasonable_md5b64
+
+logger = log.getLogger(__name__)
+
+
+class AdlsHashedResource(ty.NamedTuple):
+    """See the containing package for documentation on how to use this and its motivation."""
+
+    fqn: AdlsFqn
+    md5b64: str
+
+    @property
+    def serialized(self) -> str:
+        return serialize(self)
+
+    @staticmethod
+    def of(fqn_or_uri: ty.Union[AdlsFqn, str], md5b64: str) -> "AdlsHashedResource":
+        return of(fqn_or_uri, md5b64)
+
+    @staticmethod
+    def parse(serialized_dict: str) -> "AdlsHashedResource":
+        return parse(serialized_dict)
+
+
+def of(fqn_or_uri: ty.Union[AdlsFqn, str], md5b64: str) -> AdlsHashedResource:
+    assert md5b64, "md5b64 must be non-empty"
+    fqn = AdlsFqn.parse(fqn_or_uri) if isinstance(fqn_or_uri, str) else fqn_or_uri
+    return AdlsHashedResource(fqn, md5b64)
+
+
+def from_source(source: source.Source) -> AdlsHashedResource:
+    assert source.hash, "Source must have a hash"
+    assert source.hash.algo == "md5", f"Source Hash type must be MD5! Got: {source.hash.algo}"
+    return of(source.uri, hashing.b64(source.hash.bytes))
+
+
+def to_source(resource: AdlsHashedResource) -> source.Source:
+    return source.from_uri(
+        str(resource.fqn),
+        hash=source.Hash("md5", hashing.db64(resource.md5b64)),
+    )
+
+
+def serialize(resource: AdlsHashedResource) -> str:
+    d = resource._asdict()
+    # we use uri instead of fqn in order to make these a more generic format
+    return json.dumps(dict(uri=str(d["fqn"]), md5b64=d["md5b64"]))
+
+
+def parse(serialized_dict: str) -> AdlsHashedResource:
+    actual_dict = json.loads(serialized_dict)
+    # accept either uri or fqn
+    uri = actual_dict["uri"] if "uri" in actual_dict else actual_dict["fqn"]
+    md5b64 = actual_dict["md5b64"]
+    check_reasonable_md5b64(md5b64)
+    return AdlsHashedResource.of(AdlsFqn.parse(uri), md5b64)
+
+
+def get(fqn_or_uri: ty.Union[AdlsFqn, str]) -> AdlsHashedResource:
+    """Creates an AdlsHashedResource from a remote-only file.
+
+    The file _must_ have a pre-existing Content MD5!
+    """
+    fqn = AdlsFqn.parse(fqn_or_uri) if isinstance(fqn_or_uri, str) else fqn_or_uri
+    with blob_not_found_translation(fqn):
+        props = (
+            get_global_fs_client(fqn.sa, fqn.container).get_file_client(fqn.path).get_file_properties()
+        )
+        assert props.content_settings.content_md5, "ADLS file has empty Content-MD5!"
+        return AdlsHashedResource.of(fqn, b64(props.content_settings.content_md5))

thds/adls/resource/file_pointers.py

@@ -0,0 +1,54 @@
+import os
+import typing as ty
+from pathlib import Path
+
+from thds.core.hashing import b64
+
+from ..global_client import get_global_fs_client
+from .core import AdlsHashedResource, parse, serialize
+
+_AZURE_PLACEHOLDER_SIZE_LIMIT = 4096
+# it is assumed that no placeholder will ever need to be larger than 4 KB.
+
+
+def resource_from_path(path: ty.Union[str, Path]) -> AdlsHashedResource:
+    """Raises if the path does not represent a serialized AdlsHashedResource."""
+    with open(path) as maybe_json_file:
+        json_str = maybe_json_file.read(_AZURE_PLACEHOLDER_SIZE_LIMIT)
+        return parse(json_str)
+
+
+class MustCommitResourceLocally(Exception):
+    """Means you need to read the message and commit the change to the repo."""
+
+
+def _check_ci(resource_json_path: ty.Union[str, Path], resource: AdlsHashedResource):
+    if os.getenv("CI"):
+        print("\n" + resource.serialized + "\n")
+        # Because we can't modify+commit in CI, this should fail
+        # if it's recreating a resource in a CI environment.
+        raise MustCommitResourceLocally(
+            "In CI, a newly built resource cannot be recorded."
+            " However, it did successfully build and upload!"
+            f" You should paste '{resource.serialized}'"
+            f" into '{resource_json_path}' locally, and commit."
+        )
+
+
+def resource_to_path(
+    path: ty.Union[str, Path], resource: AdlsHashedResource, *, check_ci: bool = False
+) -> None:
+    if check_ci:
+        _check_ci(path, resource)
+    with open(path, "w") as json_file:
+        json_file.write(serialize(resource) + "\n")
+
+
+def validate_resource(srcfile: ty.Union[str, Path]) -> AdlsHashedResource:
+    res = resource_from_path(srcfile)
+    fqn, md5b64 = res
+    props = get_global_fs_client(fqn.sa, fqn.container).get_file_client(fqn.path).get_file_properties()
+    md5 = props.content_settings.content_md5
+    assert md5, f"{fqn} was incorrectly uploaded to ADLS without an MD5 embedded."
+    assert md5b64 == b64(md5), f"You probably need to update the MD5 in {srcfile}"
+    return res

thds/adls/resource/up_down.py

@@ -0,0 +1,245 @@
+"""Tools for using and creating locally-cached resources."""
+
+import typing as ty
+from pathlib import Path
+
+from azure.core.exceptions import HttpResponseError, ResourceModifiedError
+from azure.storage.blob import ContentSettings
+
+from thds.core import files, fretry, hashing, link, log, scope, tmp
+
+from .._progress import report_upload_progress
+from .._upload import metadata_for_upload, upload_decision_and_settings
+from ..conf import UPLOAD_FILE_MAX_CONCURRENCY
+from ..download import download_or_use_verified
+from ..errors import BlobNotFoundError
+from ..fqn import AdlsFqn
+from ..global_client import get_global_blob_container_client, get_global_fs_client
+from ..ro_cache import Cache, global_cache
+from .file_pointers import AdlsHashedResource, resource_from_path, resource_to_path
+
+logger = log.getLogger(__name__)
+_SLOW_CONNECTION_WORKAROUND = 14400  # seconds
+
+
+# DOWNLOAD
+def get_read_only(
+    resource: AdlsHashedResource,
+    local_path: ty.Optional[Path] = None,
+    cache: Cache = global_cache(),
+) -> Path:
+    """Downloads a read-only resource if it is not already present in
+    the cache or at the local_path.
+
+    Because the resource includes a hash, we can save a lot of
+    bandwidth if we can detect that it already is present locally.
+
+    By default, downloads through the machine-global cache. Caching
+    cannot be disabled, but the location of the cache can be changed.
+    """
+    cache = cache or global_cache()
+    local_path = local_path or cache.path(resource.fqn)
+    download_or_use_verified(
+        get_global_fs_client(resource.fqn.sa, resource.fqn.container),
+        resource.fqn.path,
+        local_path,
+        md5b64=resource.md5b64,
+        cache=cache,
+    )
+    return local_path
+
+
+# UPLOAD
+UploadSrc = ty.Union[Path, bytes, ty.IO[ty.AnyStr], ty.Iterable[bytes]]
+
+
+def _write_through_local_cache(local_cache_path: Path, data: UploadSrc) -> ty.Optional[Path]:
+    @scope.bound
+    def _try_write_through() -> bool:
+        if isinstance(data, Path) and data.exists():
+            link.link_or_copy(data, local_cache_path, "ref")
+            return True
+        out = scope.enter(tmp.temppath_same_fs(local_cache_path))
+        if hasattr(data, "read") and hasattr(data, "seek"):
+            with open(out, "wb") as f:
+                f.write(data.read())  # type: ignore
+            data.seek(0)  # type: ignore
+            link.link_or_copy(out, local_cache_path)
+            return True
+        if isinstance(data, bytes):
+            with open(out, "wb") as f:
+                f.write(data)
+            link.link_or_copy(out, local_cache_path)
+            return True
+        return False
+
+    if _try_write_through():
+        try:
+            # it's a reflink or a copy, so the cache now owns its copy
+            # and we don't want to allow anyone to write to its copy.
+            files.set_read_only(local_cache_path)
+            return local_cache_path
+        except FileNotFoundError:
+            # may have hit a race condition.
+            # don't fail upload just because we couldn't write through the cache.
+            pass
+    return None
+
+
+@scope.bound
+@fretry.retry_sleep(
+    # ADLS lib has a bug where parallel uploads of the same thing will
+    # hit a race condition and error.  this will detect that scenario
+    # and avoid re-uploading as well.
+    fretry.is_exc(ResourceModifiedError),
+    fretry.expo(retries=5),
+)
+def upload(
+    dest: ty.Union[AdlsFqn, str],
+    src: UploadSrc,
+    write_through_cache: ty.Optional[Cache] = None,
+    *,
+    content_type: str = "",
+    **upload_data_kwargs: ty.Any,
+) -> ty.Optional[AdlsHashedResource]:
+    """Uploads only if the remote does not exist or does not match
+    md5.
+
+    Always embeds md5 in upload if at all possible. In very rare cases
+    it may not be possible for us to calculate one. Will always
+    be possible if the passed data was a Path. If one can be
+    calculated, an AdlsHashedResource is returned.
+
+    Can write through a local cache, which may save you a download later.
+
+    content_type and all upload_data_kwargs will be ignored if the file
+    has already been uploaded and the md5 matches.
+    """
+    dest_ = AdlsFqn.parse(dest) if isinstance(dest, str) else dest
+    if write_through_cache:
+        _write_through_local_cache(write_through_cache.path(dest_), src)
+        # we always use the original source file to upload, not the cached path,
+        # because uploading from a shared location risks race conditions.
+
+    blob_container_client = get_global_blob_container_client(dest_.sa, dest_.container)
+    blob_client = blob_container_client.get_blob_client(dest_.path)
+    decision = upload_decision_and_settings(blob_client.get_blob_properties, src)  # type: ignore [arg-type]
+    if decision.upload_required:
+        # set up some bookkeeping
+        n_bytes = None  # if we pass 0 to upload_blob, it truncates the write now
+        if isinstance(src, Path):
+            n_bytes = src.stat().st_size
+            src = scope.enter(open(src, "rb"))
+        elif isinstance(src, bytes):
+            n_bytes = len(src)
+
+        adls_meta = metadata_for_upload()
+        if "metadata" in upload_data_kwargs:
+            adls_meta.update(upload_data_kwargs.pop("metadata"))
+
+        upload_content_settings = decision.content_settings or ContentSettings()
+        if content_type:
+            upload_content_settings.content_type = content_type
+
+        # we are now using blob_client instead of file system client
+        # because blob client (as of 2024-06-24) does actually do
+        # some one-step, atomic uploads, wherein there is not a separate
+        # create/truncate action associated with an overwrite.
+        # This is both faster, as well as simpler to reason about, and
+        # in fact was the behavior I had been assuming all along...
+        blob_client.upload_blob(
+            report_upload_progress(ty.cast(ty.IO, src), str(dest_), n_bytes or 0),
+            overwrite=True,
+            length=n_bytes,
+            content_settings=upload_content_settings,
+            connection_timeout=_SLOW_CONNECTION_WORKAROUND,
+            max_concurrency=UPLOAD_FILE_MAX_CONCURRENCY(),
+            metadata=adls_meta,
+            **upload_data_kwargs,
+        )
+
+    # if at all possible (if the md5 is known), return a resource containing it.
+    if decision.content_settings and decision.content_settings.content_md5:
+        return AdlsHashedResource.of(dest_, hashing.b64(decision.content_settings.content_md5))
+    return None
+
+
+def verify_remote_md5(resource: AdlsHashedResource) -> bool:
+    try:
+        props = (
+            get_global_fs_client(resource.fqn.sa, resource.fqn.container)
+            .get_file_client(resource.fqn.path)
+            .get_file_properties()
+        )
+        if props.content_settings.content_md5:
+            return hashing.b64(props.content_settings.content_md5) == resource.md5b64
+    except HttpResponseError:
+        return False
+    except Exception:
+        logger.exception("Unable to verify remote md5")
+    return False
+
+
+# DOWNLOAD if exists, else CREATE and UPLOAD
+
+
+def verify_or_create_resource(
+    resource_json_path: Path,
+    get_adls_fqn: ty.Callable[[], AdlsFqn],
+    creator: ty.Callable[[], Path],
+    cache: ty.Optional[Cache] = global_cache(),
+) -> AdlsHashedResource:
+    """Return an MD5-verified resource if it already exists and
+    matches the FQN _and_ the MD5 embedded in the resource JSON file.
+
+    Does not download the actual resource if it can be verified to
+    exist and match what is expected.
+
+    If if does not exist or does not match, creates the resource and
+    uploads it to the requested path as well.
+
+    Basically an idempotent get-or-create pattern, applied to things
+    that are more expensive to build than to upload, and that result
+    in a single file.
+
+    For this to work correctly, you will need the FQN itself to change
+    based on some kind of key that can be considered unique to a
+    particular version of the resource. Think of it like a cache
+    key. For instance, if you have a resource that gets changed every
+    time your library gets built, then your library version could be
+    part of the Adls FQN.
+
+    If running in CI, will create and upload your resource from CI,
+    but will then raise an exception, since you need to commit the
+    serialized resource to the resource_json_path.
+    """
+    remote_fqn = get_adls_fqn()  # this is lazy to allow partial application at a module level.
+    if resource_json_path.exists():
+        try:
+            resource = resource_from_path(resource_json_path)
+            try:
+                if resource.fqn == remote_fqn:
+                    if verify_remote_md5(resource):
+                        return resource
+                    else:
+                        logger.info("Resource MD5 does not match; must recreate.")
+                logger.info("Resource FQN does not match - it needs to be recreated.")
+            except BlobNotFoundError:
+                logger.info(f"Resource does not exist at {resource.fqn}; will create.")
+            except Exception:
+                logger.exception(f"Failed to get resource from {resource.fqn}, will recreate.")
+        except Exception:
+            logger.exception(f"Unable to parse a resource from {resource_json_path}; must recreate.")
+
+    logger.info(f"Creating resource for {remote_fqn}...")
+    created_path = creator()
+    sz_mb = created_path.stat().st_size / 2**20  # 1 MB
+    logger.info(
+        f"Uploading created resource of size {sz_mb:.1f} MB to {remote_fqn} from {created_path} ..."
+    )
+    uploaded_resource = upload(remote_fqn, created_path, write_through_cache=cache)
+    assert (
+        uploaded_resource
+    ), "Cannot create a shared resource without being able to calculate MD5 prior to upload."
+    resource_to_path(resource_json_path, uploaded_resource, check_ci=True)
+    return uploaded_resource

thds/adls/ro_cache.py

@@ -0,0 +1,126 @@
+import os
+import sys
+import typing as ty
+from pathlib import Path
+
+from thds.core import config, log
+from thds.core import types as ct
+from thds.core.files import set_read_only
+from thds.core.home import HOMEDIR
+from thds.core.link import LinkType, link_or_copy
+
+from .fqn import AdlsFqn
+from .md5 import hex_md5_str
+
+GLOBAL_CACHE_PATH = config.item("global-cache-path", HOMEDIR() / ".adls-md5-ro-cache", parse=Path)
+MAX_FILENAME_LEN = config.item("max-filename-len", 255, parse=int)  # safe on most local filesystems?
+MAX_TOTAL_PATH_LEN = config.item(
+    "max-total-path-len", 1023 if sys.platform == "darwin" else 4095, parse=int
+)
+logger = log.getLogger(__name__)
+
+LinkOpts = ty.Union[bool, ty.Tuple[LinkType, ...]]
+# if True, order is reflink, hardlink, softlink, copy
+
+
+class Cache(ty.NamedTuple):
+    """Immutable struct declaring what cache behavior is desired."""
+
+    root: Path
+    link: LinkOpts
+
+    def path(self, fqn: AdlsFqn) -> Path:
+        p = _cache_path_for_fqn(self, fqn)
+        # we do not call this function anywhere unless we're planning
+        # on downloading, so in general this should not create
+        # empty directories that we didn't expect to use.
+        p.parent.mkdir(parents=True, exist_ok=True)
+        return p
+
+
+def global_cache(link: LinkOpts = ("ref", "hard")) -> Cache:
+    """This is the recommended caching configuration."""
+    return Cache(GLOBAL_CACHE_PATH(), link)
+
+
+def _compress_long_path_part(part: str, max_bytes: int) -> str:
+    md5_of_entire_part = "-md5-" + hex_md5_str(part) + "-"
+    start_of_excised_section = (len(part) - len(md5_of_entire_part)) // 2
+    end_of_excised_section = start_of_excised_section + len(md5_of_entire_part)
+
+    while True:
+        compressed_part = (
+            part[:start_of_excised_section] + md5_of_entire_part + part[end_of_excised_section:]
+        )
+        num_bytes_overage = len(compressed_part.encode()) - max_bytes
+        if num_bytes_overage <= 0:
+            return compressed_part
+
+        if len(part) - end_of_excised_section < start_of_excised_section:
+            start_of_excised_section -= 1
+        else:
+            end_of_excised_section += 1
+        # this is a very naive iterative approach to taking more 'bites' out of the middle of the filename.
+        # we can't easily reason about how many bytes each character is, but we also can't
+        # operate at the byte level directly, because removing bytes out of Unicode characters
+        # will inevitably lead to invalid UTF-8 sequences.
+
+        assert start_of_excised_section >= 0, (
+            part,
+            compressed_part,
+            start_of_excised_section,
+        )
+        assert end_of_excised_section <= len(part), (
+            part,
+            compressed_part,
+            end_of_excised_section,
+        )
+
+
+def _cache_path_for_fqn(cache: Cache, fqn: AdlsFqn) -> Path:
+    """
+    On Linux, file paths can be 255 bytes per part, and the max full path limit is
+    4095, not including the NULL terminator.  On Mac, the max total length is 1023, and
+    the max part length is 255.
+    """
+    # we assume that neither the SA nor the container will ever be more than MAX_FILENAME_LEN bytes.
+    # However, we know that sometimes the path parts _are_, so in rare
+    # cases we need unique yet mostly readable abbreviation for those.
+    parts = list()
+    for part in fqn.path.split("/"):
+        part_bytes = part.encode()
+        if len(part_bytes) > MAX_FILENAME_LEN():
+            part = _compress_long_path_part(part, MAX_FILENAME_LEN())
+        parts.append(part)
+
+    full_path = str(Path(cache.root.resolve() / fqn.sa / fqn.container, *parts))
+    if len(full_path.encode()) > MAX_TOTAL_PATH_LEN():
+        full_path = _compress_long_path_part(full_path, MAX_TOTAL_PATH_LEN())
+
+    return Path(full_path)
+
+
+def _opts_to_types(opts: LinkOpts) -> ty.Tuple[LinkType, ...]:
+    if opts is True:
+        return ("ref", "hard")
+    elif opts is False:
+        return tuple()
+    return opts
+
+
+def from_cache_path_to_local(cache_path: ct.StrOrPath, local_path: ct.StrOrPath, link_opts: LinkOpts):
+    set_read_only(cache_path)
+
+    link_type = link_or_copy(cache_path, local_path, *_opts_to_types(link_opts))
+    if link_type in {"ref", "", "same"}:
+        # hard and soft links do not have their own permissions - they
+        # share the read-only permissions of their target.  reflinks
+        # and copies will not, so those should not be marked as
+        # read-only since edits to them will not affect the original,
+        # cached copy.
+        os.chmod(local_path, 0o644)  # 0o644 == rw-r--r-- (user, group, all)
+
+
+def from_local_path_to_cache(local_path: ct.StrOrPath, cache_path: ct.StrOrPath, link_opts: LinkOpts):
+    link_or_copy(local_path, cache_path, *_opts_to_types(link_opts))
+    set_read_only(cache_path)