code: def _copy_file(src, dest, cache):
      """Transfer a single file from a source to a target dataset
  
      Parameters
      ----------
      src : Path or str
        Source file path
      dest : Path or str
        Destination file path
      cache : StaticRepoCache
  
      Yields
      ------
      dict
        Result record.
      """
      lgr.debug("Attempt to copy: %s -> %s", src, dest)
      str_src = str(src)
      str_dest = str(dest)
      if not op.lexists(str_src):
          yield dict(
              path=str_src,
              status="impossible",
              message="no such file or directory",
          )
          return
  
      # at this point we know that there is something at `src`,
      # and it must be a file
      # get the source repository, if there is any.
      # `src_repo` will be None, if there is none, and can serve as a flag
      # for further processing
      src_repo = cache[src]
      # same for the destination repo
      dest_repo = cache[dest]
      if not dest_repo:
          yield dict(
              path=str_dest,
              status="error",
              message="copy destination not within a dataset",
          )
          return
  
      # whenever there is no annex (remember an AnnexRepo is also a GitRepo)
      if src_repo is None or not issubclass(
          src_repo.get_repotype(), AnnexRepo
      ):
          # so the best thing we can do is to copy the actual file into the
          # worktree of the destination dataset.
          # we will not care about unlocking or anything like that we just
          # replace whatever is at `dest`, save() must handle the rest.
          # we are not following symlinks, they cannot be annex pointers
          lgr.info(
              "Copying file from a location which is not an annex dataset: %s",
              src,
          )
          _replace_file(str_src, dest, str_dest, follow_symlinks=False)
          yield dict(
              path=str_src,
              destination=str_dest,
              status="ok",
          )
          # TODO if we later deal with metadata, we might want to consider
          # going further
          return
  
      # now we know that we are copying from an AnnexRepo dataset
      # look for URLs on record
  
      # pull what we know about this file from the source repo
      finfo = src_repo.get_file_annexinfo(src)
      if "key" not in finfo or not issubclass(
          dest_repo.get_repotype(), AnnexRepo
      ):
          lgr.info(
              "Copying non-annexed file or copy into non-annex dataset: %s -> %s",
              src,
              dest_repo,
          )
          # the best thing we can do when the target isn't an annex repo
          # or the source is not an annexed files is to copy the file,
          # but only if we have it
          # (make default True, because a file in Git doesn't have this property)
          if not finfo.get("has_content", True):
              yield dict(
                  path=str_src,
                  status="impossible",
                  message="file has no content available",
              )
              return
          # follow symlinks to pull content from annex
          _replace_file(
              str_src,
              dest,
              str_dest,
              follow_symlinks=finfo.get("type", "file") == "file",
          )
          yield dict(
              path=str_src,
              destination=str_dest,
              status="ok",
          )
          return
  
      #
      # at this point we are copying an annexed file into an annex repo
      if (
          not dest_repo._check_version_kludges(
              "fromkey-supports-unlocked"
          )
          and dest_repo.is_managed_branch()
      ):
          res = _place_filekey_managed(
              finfo, str_src, dest, str_dest, dest_repo
          )
      else:
          res = _place_filekey(
              finfo, str_src, dest, str_dest, dest_repo
          )
      if isinstance(res, dict):
          yield res
          return
      dest_key = res
  
      # are there any URLs defined? Get them by special remote
      # query by key to hopefully avoid additional file system interaction
      whereis_by_sr = src_repo.get_whereis_key_by_specialremote(
          finfo["key"]
      )
      if not whereis_by_sr:
          yield dict(
              path=str_src,
              destination=str_dest,
              message="no known location of file content",
              status="impossible",
          )
          return
  
      avail_remote = []
      urls_by_sr = {
          k: v["urls"]
          for k, v in whereis_by_sr.items()
          if v.get("urls")
      }
      if urls_by_sr:
          # some URLs are on record in the for this file
          avail_remote.extend(
              _register_urls(
                  dest_repo,
                  dest_key,
                  urls_by_sr,
                  src_repo.get_special_remotes_wo_timestamp(),
              )
          )
  
      if not avail_remote and not dest_repo.get_file_annexinfo(
          dest
      ).get("has_content"):
          # not having set any remotes is not a problem, if the file content got
          # here via other means
          yield dict(
              path=str_src,
              destination=str_dest,
              message="no usable/supported remote for file content",
              status="impossible",
          )
          return
  
      # TODO prevent copying .datalad of from other datasets?
      yield dict(
          path=str_src,
          destination=str_dest,
          message=dest,
          status="ok",
      )
  
imports: import logging
  import os.path
  from shutil import copyfile
  import sys
  from datalad.interface.base import Interface
  from datalad.interface.base import build_doc, eval_results
  from datalad.support.constraints import EnsureStr, EnsureNone
  from datalad.interface.common_opts import save_message_opt
  from datalad.support.param import Parameter
  from datalad.distribution.dataset import Dataset, require_dataset
  from datalad.support.annexrepo import AnnexRepo
  from datalad.support.exceptions import CapturedException
  from datalad.utils import ensure_list, get_dataset_root, Path
  from datalad.distribution.dataset import EnsureDataset, datasetmethod, resolve_path
  from functools import lru_cache
label_desc: Use image node_id 3 for calling a global function with example usage: _copy_file(src, dest, cache) without return types