Implements Py3-compatible rich comparison for all Bio.PDB objects

[JoaoRodrigues]

This pull request addresses issue #1356 and refactors #1189 and PR #1291. It implements rich comparisons for every object of the SMCRA hierarchy, including disordered wrappers. This allows direct comparison of any two objects and allows calling the sorted method directly, unifying the API.

The test suite was expanded and refactored to test all these possibilities. The a_structure.pdb test PDB was slightly tweaked to avoid adding yet another file. I had to fix a number of other tests to accomodate these changes. All tests pass under Python 2.7 and Python 3.

Thanks @harryjubb for raising the problem that led to this fix, and @peterjc for the earlier work and usual leadership 👍

I hereby agree to dual licence this and any previous contributions under both
the Biopython License Agreement AND the BSD 3-Clause License.

I am happy to be thanked by name in the NEWS.rst and
CONTRIB.rst files.

I have read the CONTRIBUTING.rst file and understand that AppVeyor and
TravisCI will be used to confirm the Biopython unit tests and flake8 style
checks pass with these changes.

[peterjc]

Should that not be self.child_list.sort() for an in-place sorting of the list?

[JoaoRodrigues]

Well spotted!

[peterjc]

Is it worth adding public .sort() methods to each level of objects? i.e. Where there used to be a private ._sort() method until #1189

[peterjc]

Are you happy with running flake8 locally with the plugins as described in the CONTRIBUTING file? The TravisCI style checks are failing right now:

$ flake8 Bio/
Bio/PDB/Residue.py:92:1: D202 No blank lines allowed after function docstring

After that it will run flake8 Tests/ as well.

[JoaoRodrigues]

Is it worth adding public .sort() methods to each level of objects? i.e. Where there used to be a private ._sort() method until #1189

I would actually propose removing them altogether and have people use the sorted method instead. This is already supported anyway.

Are you happy with running flake8 locally with the plugins as described in the CONTRIBUTING file? The TravisCI style checks are failing right now

Yes. I'll do that. I had a linter plugin for Atom (the editor) but that kept leaving Python processes hanging after I closed the program (100% CPU for hours...). I'll run locally. Do we have a pre-commit hook for this somewhere? Would be nice to have at hand...

[peterjc]

OK - should we deprecate the single public .sort() method then?

For the git pre-commit hook, see issue #493 and possible implementation on #1188

[peterjc]

You'll need to remove this blank link to make flake8 happy:

$ flake8 Bio/
Bio/PDB/Residue.py:92:1: D202 No blank lines allowed after function docstring

[JoaoRodrigues]

OK - should we deprecate the single public .sort() method then?

I would vote for that.

[JoaoRodrigues]

@etal @peterjc Some tests are failing on Py 3.4 and made me realize I might have misunderstood how to write these methods. For example, for an __eq__ method for equality, should I explicitly write what I expect to compare in the other object - i.e. return self.id == other.id - or should I leave it to the language and implement it on both objects like return self.id == other? It seems that the latter is the best choice because it tries to figure out how to compare the objects first and if it cannot, then it raises the normal error 'Cannot compare objects x and y' instead of a missing attribute in case the other object is say, a list. Any thoughts? Object equality is not really taught in biology classes :)

Edit: Added a test for isinstance(other, type(self)) to avoid these problems, as suggested in several places. Trying a comparison between any of our objects and anything else returns NotImplemented if they are not of the same type, which then defaults to whatever Python decides (equality based on id comparison, TypeError for >.>=,<, and <=).

[codecov]

Codecov Report

Merging #1360 into master will decrease coverage by 0.12%.
The diff coverage is 46.29%.

@@            Coverage Diff             @@
##           master    #1360      +/-   ##
==========================================
- Coverage   84.48%   84.36%   -0.13%     
==========================================
  Files         319      319              
  Lines       48920    49100     +180     
==========================================
+ Hits        41332    41423      +91     
- Misses       7588     7677      +89

Impacted Files	Coverage Δ
Bio/PDB/Chain.py	63.38% <28.12%> (-28.93%)	⬇️
Bio/PDB/Residue.py	68.9% <42.85%> (-18%)	⬇️
Bio/PDB/Atom.py	76.21% <50%> (-10.81%)	⬇️
Bio/PDB/Entity.py	83.24% <61.76%> (-4.84%)	⬇️
Bio/PDB/MMCIF2Dict.py	100% <0%> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 32ca898...fd356bc. Read the comment docs.

[peterjc]

change "deprecated" to "removed" (or change the tense to "... has been deprecated in favour of...")

[JoaoRodrigues]

Done.

[JoaoRodrigues]

The coverage is decreasing because of all the rich comparison methods, which have a few conditionals in there, but the testing is actually more extensive than before. If others agree with these changes, we should merge this.

[peterjc]

Seems fine to me - @etal, @lennax, etc any comments before we merge this?