docs: def lock(tmp_dir, timeout=NOT_SET, min_wait=None, max_wait=None, verbosity=1):
      """Obtain lock.
  
      Obtain lock access by creating a given temporary directory (whose base
      will be created if needed, but will not be deleted after the lock is
      removed). If access is refused by the same lock owner during more than
      'timeout' seconds, then the current lock is overridden. If timeout is
      None, then no timeout is performed.
  
      The lock is performed by creating a 'lock' file in 'tmp_dir' that
      contains a unique id identifying the owner of the lock (the process
      id, followed by a random string).
  
      When there is already a lock, the process sleeps for a random amount
      of time between min_wait and max_wait seconds before trying again.
  
      If 'verbosity' is >= 1, then a message will be displayed when we need
      to wait for the lock. If it is set to a value >1, then this message
      will be displayed each time we re-check for the presence of the lock.
      Otherwise it is displayed only when we notice the lock's owner has
      changed.
  
      Parameters
      ----------
      str tmp_dir : str
          Lock directory that will be created when acquiring the lock.
  
      timeout : int
          Time (in seconds) to wait before replacing an existing lock.
  
      min_wait : int
          Minimum time (in seconds) to wait before trying again to get the
          lock.
  
      max_wait : int
          Maximum time (in seconds) to wait before trying again to get the
          lock (default 2 * min_wait).
  
      verbosity : int
          Amount of feedback displayed to screen (default 1).
  
      """
      if min_wait is None:
          min_wait = MIN_WAIT
      if max_wait is None:
          max_wait = min_wait * 2
      if timeout is NOT_SET:
          timeout = TIMEOUT
      # Create base of lock directory if required.
      base_lock = os.path.dirname(tmp_dir)
      if not os.path.isdir(base_lock):
          try:
              os.makedirs(base_lock)
          except OSError:
              # Someone else was probably trying to create it at the same time.
              # We wait two seconds just to make sure the following assert does
              # not fail on some NFS systems.
              time.sleep(2)
      assert os.path.isdir(base_lock)
  
      # Variable initialization.
      lock_file = os.path.join(tmp_dir, 'lock')
      random.seed()
      my_pid = os.getpid()
      no_display = (verbosity == 0)
  
      nb_error = 0
      # The number of time we sleep when their is no errors.
      # Used to don't display it the first time to display it less frequently.
      # And so don't get as much email about this!
      nb_wait = 0
      # Acquire lock.
      while True:
          try:
              last_owner = 'no_owner'
              time_start = time.time()
              other_dead = False
              while os.path.isdir(tmp_dir):
                  try:
                      with open(lock_file) as f:
                          read_owner = f.readlines()[0].strip()
  
                      # The try is transition code for old locks.
                      # It may be removed when people have upgraded.
                      try:
                          other_host = read_owner.split('_')[2]
                      except IndexError:
                          other_host = ()  # make sure it isn't equal to any host
                      if other_host == hostname:
                          try:
                              # Just check if the other process still exist.
                              os.kill(int(read_owner.split('_')[0]), 0)
                          except OSError:
                              other_dead = True
                          except AttributeError:
                              pass  # os.kill does not exist on windows
                  except Exception:
                      read_owner = 'failure'
                  if other_dead:
                      if not no_display:
                          msg = "process '%s'" % read_owner.split('_')[0]
                          logger.warning("Overriding existing lock by dead %s "
                                         "(I am process '%s')", msg, my_pid)
                      get_lock.unlocker.unlock()
                      continue
                  if last_owner == read_owner:
                      if (timeout is not None and
                              time.time() - time_start >= timeout):
                          # Timeout exceeded or locking process dead.
                          if not no_display:
                              if read_owner == 'failure':
                                  msg = 'unknown process'
                              else:
                                  msg = "process '%s'" % read_owner.split('_')[0]
                              logger.warning("Overriding existing lock by %s "
                                             "(I am process '%s')", msg, my_pid)
                          get_lock.unlocker.unlock()
                          continue
                  else:
                      last_owner = read_owner
                      time_start = time.time()
                      no_display = (verbosity == 0)
                  if not no_display and nb_wait > 0:
                      if read_owner == 'failure':
                          msg = 'unknown process'
                      else:
                          msg = "process '%s'" % read_owner.split('_')[0]
                      logger.info("Waiting for existing lock by %s (I am "
                                  "process '%s')", msg, my_pid)
                      logger.info("To manually release the lock, delete %s",
                                  tmp_dir)
                      if verbosity <= 1:
                          no_display = True
                  nb_wait += 1
                  time.sleep(random.uniform(min_wait, max_wait))
  
              try:
                  os.mkdir(tmp_dir)
              except OSError:
                  # Error while creating the directory: someone else
                  # must have tried at the exact same time.
                  nb_error += 1
                  if nb_error < 10:
                      continue
                  else:
                      raise
              # Safety check: the directory should be here.
              assert os.path.isdir(tmp_dir)
  
              # Write own id into lock file.
              unique_id = refresh_lock(lock_file)
  
              # Verify we are really the lock owner (this should not be needed,
              # but better be safe than sorry).
              with open(lock_file) as f:
                  owner = f.readlines()[0].strip()
  
              if owner != unique_id:
                  # Too bad, try again.
                  continue
              else:
                  # We got the lock, hoorray!
                  return
  
          except Exception as e:
              # If something wrong happened, we try again.
              logger.warning("Something wrong happened: %s %s", type(e), e)
              nb_error += 1
              if nb_error > 10:
                  raise
              time.sleep(random.uniform(min_wait, max_wait))
              continue