Add a setlist method to the Headers datastructure

[pgjones]

The update method added in baa7bdc is
meant to replace headers with the mapping passed in. If a MultDict or
Headers object is passed in it would replace headers with the final
iterated value, rather than all the values iterated over. This could
lead to unexpected results, therefore this corrects the functionality
to what I think is expected.

Consider,

h1 = Headers()
h1.add("X-Multi", "value")
h2 = Headers()
h2.add("X-Multi", "newValue")
h2.add("X-Multi", "alternativeValue")
h1.update(h2)

previously h1.getlist("X-Multi") would likely equal
["alternativeValue"] whereas now it equals ["newValue", "alternativeValue"] which is as you'd expect.

[davidism]

This doesn't match the behavior of MultiDict.update, which extends rather than replaces existing keys. I guess you mentioned this in #1687 but I missed it.

[davidism]

Although in this case it probably makes more sense to be replacing rather than extending, it seems like the more likely use case for a collection of headers. If users want the other behavior we can implement update_extend or something later.

[pgjones]

I agree. (Also I think the test issues are unrelated?)

[davidism]

They are, that test uses time.sleep and is flaky on Mac for some reason.

[davidism]

Does it make sense for keyword arguments to update to be passed to setlist if possible? Unlike MultiDict, a header can't have a list for a value, so there wouldn't be a conflict.

I'm going to say no for now, since h[key] = [a, b, c] just converts the value to a string. We might want to address that later though.

I'm going to say yes since passing a dict does that and kwargs is a dict.

[davidism]

Headers.extend already exists and looks fairly similar to this.

I can update it to do for item in iter_multi_items(other): self.add(*item) and that should be the add equivalent to update.

[davidism]

Pushed a bunch of things I caught while reviewing the related methods and MultiDict.

• setlist removes the key if values is empty.
• setlist doesn't copy the values (values[1:]) for iteration.
• update uses set instead of __setitem__. I don't think index/slice behavior is expected there.
• If a value in kwargs is a list, update passes it to setlist, extend adds each value.
• extend supports MultiDict and kwargs, it's the add equivalent to update.
• Add a setlistdefault method since MultiDict has it.
• Add the new methods to ImmutableHeadersMixin so they can't be used on EnvironHeaders.
• Add tests and changelog for all this.

[pgjones]

Cool, thanks.