Provide ImmutableSet factory methods which ban duplicate additions

[gabbard]

This can sometimes be very helpful for debugging.

[qpwo]

Would this be an option to the builder and Builder methods for the various collections? Would this effect e.g. ImmutableSet.add or ImmutableSet.__or__ in any way?

[gabbard]

@qpwo :The Builders are deprecated, so they don't need to be updated. Instead we now create the collections via factory methods like immutableset. I think all that needs to happen is adding a new factory method immutableset_from_unique_elements or something like that. Note that for implementation you can first construct the immutablelist and then compare its len to the len of the input Iterable

@ConstantineLignos

[qpwo]

Okay should those functions be provided in immutablecollections/__init__.py?

[qpwo]

Does the input to immutableset always provide a __len__? I suppose we need to grab the length before we make the collection in case the iterable is consumed

[qpwo]

Discussion with @ConstantineLignos & @rgabbard & @berquist has lead to some conclusions about naming:

• Both a new factory function and a kwarg to the original factory will be added
  • A new factory is much more convenient with attrs than a kwarg
• Factory will be called immutableset_from_unique_elements
• Kwarg will be called forbid_duplicate_elements (and default to false)
• The solution to immutabledict and immutablemultidict is more complex and so will be in a new issue

[gabbard]

re: __len__ of the input - I think the thing to do is to list-ify the input Iterable if it does not implement Sized. There is some performance hit for this, though, so only do it if forbid_duplicate_elements is true.

[qpwo]

That ending up being unnecessary. You'll see on the PR in a moment