Shortcut operators for union, intersection and difference

[azmeuk]

Fixes #142
Implementation of __sub__, __or__ and __and__ as shortcuts for difference, union and intersection.

This makes the usage of BTrees datastructures closer to native python sets, that support those operators.

[jamadden]

This is looking pretty good to me! Thank you!

I think the only things missing are a change note about the added operators and a mention in the documentation. I think we should say what types support these operations with what sort of arguments — it's not entirely clear to me. It's probably fine to just refer to the original functions. Our sphinx configuration for autodoc does document special members, but I don't see any docstrings for these. It may be best to add them to the interfaces and document them there.

[azmeuk]

I just set this line of documentation because I was not sure on which interface to add the new operators. Is it ok like this? Or should I add the operators to the IBTree, ITreeSet and ISet interfaces?

[jamadden]

It's the modules (e.g., BTrees.OOBTree) that implement IMerge, so I don't think the method definitions of the operators belong here. It doesn't hurt anything to mention in the main docstring here that there are operator synonyms for the functions defined by this interface, but I think that the operator method definitions should be moved to the appropriate datatype interfaces.

[azmeuk]

So, just to be sure, IBTree, ITreeSet and ISet ?

[jamadden]

That sounds right to me. (I don't think there's an IBucket.)

[mgedmin]

All the OS X builders failed because

Checking dist/BTrees-4.7.3.dev0-cp38-cp38-macosx_10_9_x86_64.whl: FAILED
  `long_description` has syntax errors in markup and would not be rendered on PyPI.
    line 42: Error: Unknown interpreted text role "meth".
  warning: `long_description_content_type` missing.  defaulting to `text/x-rst`.

no Sphinx markup is allowed in README.rst and CHANGES.rst because those are used for long_description.

(In the past I've sometimes resorted to a judicious str.replace() to overcome this problem.)

[jamadden]

👍

[jamadden]

Since the long_description error is just coming from CHANGES.rst directly, I personally would probably just remove the :meth: tags and just turn the references into double-backtick code.

[azmeuk]

Everything should be good now :)

[jamadden]

Looks great! Thank you!

I just have two minor nits.