docs: def mutator(mutate):
      """Return an inspyred mutator function based on the given function.
      
      This function generator takes a function that operates on only
      one candidate to produce a single mutated candidate. The generator 
      handles the iteration over each candidate in the set to be mutated.
  
      The given function ``mutate`` must have the following signature::
      
          mutant = mutate(random, candidate, args)
          
      This function is most commonly used as a function decorator with
      the following usage::
      
          @mutator
          def mutate(random, candidate, args):
              # Implementation of mutation
              pass
              
      The generated function also contains an attribute named
      ``single_mutation`` which holds the original mutation function.
      In this way, the original single-candidate function can be
      retrieved if necessary.
      
      """
      @functools.wraps(mutate)
      def inspyred_mutator(random, candidates, args):
          mutants = []
          for i, cs in enumerate(candidates):
              mutants.append(mutate(random, cs, args))
          return mutants
      inspyred_mutator.single_mutation = mutate
      return inspyred_mutator