docs: def prepare_package(err, path, expectation=0, for_appversions=None,
                      timeout=-1):
      """Prepares a file-based package for validation.
  
      timeout is the number of seconds before validation is aborted.
      If timeout is -1 then no timeout checking code will run.
      """
  
      package = None
      try:
          # Test that the package actually exists. I consider this Tier 0
          # since we may not even be dealing with a real file.
          if not os.path.isfile(path):
              err.error(('main', 'prepare_package', 'not_found'),
                        'The package could not be found')
              return
  
          # Pop the package extension.
          package_extension = os.path.splitext(path)[1]
          package_extension = package_extension.lower()
  
          def timeout_handler(signum, frame):
              raise validator.ValidationTimeout(timeout)
  
          if timeout != -1:
              signal.signal(signal.SIGALRM, timeout_handler)
              signal.setitimer(signal.ITIMER_REAL, timeout)
  
          if package_extension == '.xml':
              test_search(err, path, expectation)
          elif package_extension not in ('.xpi', '.jar'):
              err.error(('main', 'prepare_package', 'unrecognized'),
                        'The package is not of a recognized type.')
          else:
              package = open(path, 'rb')
              test_package(err, package, path, expectation, for_appversions)
  
          err.metadata['is_extension'] = err.detected_type == PACKAGE_EXTENSION
  
      except validator.ValidationTimeout:
          err.system_error(
              msg_id='validation_timeout',
              message='Validation has timed out',
              signing_severity='high',
              description=('Validation was unable to complete in the allotted '
                           'time. This is most likely due to the size or '
                           'complexity of your add-on.',
                           'This timeout has been logged, but please consider '
                           'filing an issue report here: '
                           'https://bit.ly/1POrYYU'),
              exc_info=sys.exc_info())
  
      except Exception:
          err.system_error(exc_info=sys.exc_info())
  
      finally:
          # Remove timers and signal handlers regardless of whether
          # we've completed successfully or the timer has fired.
          if timeout != -1:
              signal.setitimer(signal.ITIMER_REAL, 0)
              signal.signal(signal.SIGALRM, signal.SIG_DFL)
  
          if package:
              package.close()
  
          decorator.cleanup()