Update the Adaptation docs to be more concrete.

This should help provide better motivating use cases. Examples inspired by https://glyph.twistedmatrix.com/2021/03/interfaces-and-protocols.html

Also some minor typo fixes and updates to comments.

Fixes #230

Add extensive tests for this. Fixes #224.

Also adds test for, and fixes #227

Add BAR.rebuild() to fix the refcount issue, and to change datatypes.

It works by using the new methods allRegistrations() and allSubscriptions() to re-create the data in new data structures.

This makes fresh calls to subscribe() and register(). I went this way instead of trying to manually walk the data structures and create them because the logic in those methods is fully tested.

They were defined to accept a name argument, but the actual implementation doesn't. Add tests for this. Fixes #208.

Also in test_adapter.py modernize idioms from assertTrue(x in y) and assertTrue(x is y) to assertIn and assertIs.

Cooperate with InterfaceClass to ensure there is no performance penalty for this. Fixes #3

+-------------------------------------------------------------+----------------+------------------------------+------------------------------+
| Benchmark                                                   | bench_master38 | bench_issue3                 | bench_issue3_opt             |
+=============================================================+================+==============================+==============================+
| call interface (provides; deep)                             | 369 ns         | 454 ns: 1.23x slower (+23%)  | not significant              |
+-------------------------------------------------------------+----------------+------------------------------+------------------------------+
| call interface (provides; wide)                             | 373 ns         | 457 ns: 1.22x slower (+22%)  | 365 ns: 1.02x faster (-2%)   |
+-------------------------------------------------------------+----------------+------------------------------+------------------------------+
| call interface (no alternate, no conform, not provided)     | 671 ns         | 760 ns: 1.13x slower (+13%)  | 636 ns: 1.06x faster (-5%)   |
+-------------------------------------------------------------+----------------+------------------------------+------------------------------+
| call interface (alternate, no conform, not provided)        | 395 ns         | 494 ns: 1.25x slower (+25%)  | not significant              |
+-------------------------------------------------------------+----------------+------------------------------+------------------------------+
| call interface (no alternate, valid conform, not provided)  | 250 ns         | not significant              | 227 ns: 1.10x faster (-9%)   |
+-------------------------------------------------------------+----------------+------------------------------+------------------------------+
| call interface (alternate, invalid conform, not provided)   | 348 ns         | 424 ns: 1.22x slower (+22%)  | not significant              |
+-------------------------------------------------------------+----------------+------------------------------+------------------------------+

Only catch AttributeError instead of everything.

Fixes #200

Note that this does break a doctest in five.intid (it's expecting a TypeError but it now gets Acquisition's RuntimeError).

Turns out they can be called in some very strange error cases. See #162 and #163 for details.

This should fix #162 (at least the provided test case, five.intid, passes now).

It also does enough work on #163 that (a) the test can be written and run in pure-python mode, which was needed to debug it and (b) five.intid runs in pure-python mode (well, with a bunch of other small hacks to Acquisition, ExtensionClass, DocumentTemplate and AccessControl), but I won't claim that it fully fixes #163. For one thing, there are no specific tests. For another, I see more such differences.

Turns out that the C extensions build and work fine with PyPy, but don't use them by default. Let them
be forced, though.

Tests needed some refactoring to account for the various permutations.