class_docstr: Base class for the downloaders
class_docstr_tok: ["Base","class","for","the","downloaders"]
docstr: Download content into a file
  
  Parameters
  ----------
  url: str
    URL to download
  path: str, optional
    Path to file where to store the downloaded content.  If None,
    filename deduced from the url and saved in curdir
  size: int, optional
    Limit in size to be downloaded
  
  Returns
  -------
  None or string
    Returns downloaded filename
docstr_tok: ["Download","content","into","a","file","Parameters","--","--","--","--","--","url",":","str","URL","to","download","path",":","str",",","optional","Path","to","file","where","to","store","the","downloaded","content",".","If","None",",","filename","deduced","from","the","url","and","saved","in","curdir","size",":","int",",","optional","Limit","in","size","to","be","downloaded","Returns","--","--","--","-","None","or","string","Returns","downloaded","filename"]
code: def _download(
      self, url, path=None, overwrite=False, size=None, stats=None
  ):
      """Download content into a file
  
      Parameters
      ----------
      url: str
        URL to download
      path: str, optional
        Path to file where to store the downloaded content.  If None,
        filename deduced from the url and saved in curdir
      size: int, optional
        Limit in size to be downloaded
  
      Returns
      -------
      None or string
        Returns downloaded filename
  
      """
  
      downloader_session = self.get_downloader_session(url)
      status = self.get_status_from_headers(downloader_session.headers)
  
      target_size = downloader_session.size
      if size is not None:
          target_size = min(target_size, size)
  
      #### Specific to download
      if path:
          download_dir = op.dirname(path)
          if download_dir:
              os.makedirs(download_dir, exist_ok=True)
          if isdir(path):
              # provided path is a directory under which to save
              filename = downloader_session.filename
              if not filename:
                  raise DownloadError(
                      "File name could not be determined from {}".format(
                          url
                      )
                  )
              filepath = opj(path, filename)
          else:
              filepath = path
      else:
          filepath = downloader_session.filename
  
      existed = op.lexists(filepath)
      if existed and not overwrite:
          raise DownloadError("Path %s already exists" % filepath)
  
      # FETCH CONTENT
      # TODO: pbar = ui.get_progressbar(size=response.headers['size'])
      try:
          temp_filepath = self._get_temp_download_filename(filepath)
          if exists(temp_filepath):
              # eventually we might want to continue the download
              lgr.warning(
                  "Temporary file %s from the previous download was found. "
                  "It will be overridden" % temp_filepath
              )
              # TODO.  also logic below would clean it up atm
  
          with open(temp_filepath, "wb") as fp:
              # TODO: url might be a bit too long for the beast.
              # Consider to improve to make it animated as well, or shorten here
              pbar = ui.get_progressbar(
                  label=url, fill_text=filepath, total=target_size
              )
              t0 = time.time()
              downloader_session.download(fp, pbar, size=size)
              downloaded_time = time.time() - t0
              pbar.finish()
          downloaded_size = os.stat(temp_filepath).st_size
  
          # (headers.get('Content-type', "") and headers.get('Content-Type')).startswith('text/html')
          #  and self.authenticator.html_form_failure_re: # TODO: use information in authenticator
          self._verify_download(
              url, downloaded_size, target_size, temp_filepath
          )
  
          # adjust atime/mtime according to headers/status
          if status.mtime:
              lgr.log(
                  5,
                  "Setting mtime for %s to be %s",
                  temp_filepath,
                  status.mtime,
              )
              os.utime(temp_filepath, (time.time(), status.mtime))
  
          # place successfully downloaded over the filepath
          os.replace(temp_filepath, filepath)
  
          if stats:
              stats.downloaded += 1
              stats.overwritten += int(existed)
              stats.downloaded_size += downloaded_size
              stats.downloaded_time += downloaded_time
      except (AccessDeniedError, IncompleteDownloadError) as e:
          raise
      except Exception as e:
          ce = CapturedException(e)
          lgr.error(
              "Failed to download %s into %s: %s", url, filepath, ce
          )
          raise DownloadError(ce) from e  # for now
      finally:
          if exists(temp_filepath):
              # clean up
              lgr.debug(
                  "Removing a temporary download %s", temp_filepath
              )
              unlink(temp_filepath)
  
      return filepath
  
imports: import msgpack
  import os
  import sys
  import time
  from abc import ABCMeta, abstractmethod
  import os.path
  from os.path import exists, join, isdir
  from ..None import cfg
  from ..ui import ui
  from ..utils import auto_repr, ensure_unicode, unlink
  from .credentials import CompositeCredential
  from datalad.downloaders import CREDENTIAL_TYPES
  from ..support.exceptions import AccessDeniedError, AccessPermissionExpiredError, AnonymousAccessDeniedError, CapturedException, DownloadError, IncompleteDownloadError, UnaccountedDownloadError
  from ..support.locking import InterProcessLock, try_lock, try_lock_informatively
  from logging import getLogger
label_desc: Use image node_id 9 for calling the BaseDownloader obj's underlying member method code with example usage: obj._download(url, path, overwrite, size, stats) and returns: filepath