docs: def _mix(color1, color2, weight=None):
      """
      Mixes together two colors. Specifically, takes the average of each of the
      RGB components, optionally weighted by the given percentage.
      The opacity of the colors is also considered when weighting the components.
  
      Specifically, takes the average of each of the RGB components,
      optionally weighted by the given percentage.
      The opacity of the colors is also considered when weighting the components.
  
      The weight specifies the amount of the first color that should be included
      in the returned color.
      50%, means that half the first color
          and half the second color should be used.
      25% means that a quarter of the first color
          and three quarters of the second color should be used.
  
      For example:
  
          mix(#f00, #00f) => #7f007f
          mix(#f00, #00f, 25%) => #3f00bf
          mix(rgba(255, 0, 0, 0.5), #00f) => rgba(63, 0, 191, 0.75)
  
      """
      # This algorithm factors in both the user-provided weight
      # and the difference between the alpha values of the two colors
      # to decide how to perform the weighted average of the two RGB values.
      #
      # It works by first normalizing both parameters to be within [-1, 1],
      # where 1 indicates "only use color1", -1 indicates "only use color 0",
      # and all values in between indicated a proportionately weighted average.
      #
      # Once we have the normalized variables w and a,
      # we apply the formula (w + a)/(1 + w*a)
      # to get the combined weight (in [-1, 1]) of color1.
      # This formula has two especially nice properties:
      #
      # * When either w or a are -1 or 1, the combined weight is also that number
      # (cases where w * a == -1 are undefined, and handled as a special case).
      #
      #   * When a is 0, the combined weight is w, and vice versa
      #
      # Finally, the weight of color1 is renormalized to be within [0, 1]
      # and the weight of color2 is given by 1 minus the weight of color1.
      #
      # Algorithm from the Sass project: http://sass-lang.com/
  
      c1 = ColorValue(color1).value
      c2 = ColorValue(color2).value
      p = NumberValue(weight).value if weight is not None else 0.5
      p = 0.0 if p < 0 else 1.0 if p > 1 else p
  
      w = p * 2 - 1
      a = c1[3] - c2[3]
  
      w1 = ((w if (w * a == -1) else (w + a) / (1 + w * a)) + 1) / 2.0
  
      w2 = 1 - w1
      q = [w1, w1, w1, p]
      r = [w2, w2, w2, 1 - p]
  
      color = ColorValue(None).merge(c1).merge(c2)
      color.value = [c1[i] * q[i] + c2[i] * r[i] for i in range(4)]
  
      return color