Remove base _CachingProtocolMeta and use beartype's instead

Now that beartype/beartype#86 has landed (and made it into a release), we can remove our own base implementation and use that one instead. We still provide our own implementation that allows overriding runtime checking, but it neatly derives from ``beartype``'s.

Author: posita

README.md

@@ -121,7 +121,7 @@ AssertionError
 For example, let’s say one wanted to ensure type compatibility with primitives that support both ``__abs__`` and ``__divmod__``.
 
 ``` python
->>> from typing import TypeVar
+>>> from beartype.typing import TypeVar
 >>> T_co = TypeVar("T_co", covariant=True)
 >>> from numerary.types import (
 ...   CachingProtocolMeta, Protocol, runtime_checkable,
@@ -186,7 +186,7 @@ False
 
 ``` python
 >>> from abc import abstractmethod
->>> from typing import Iterable, Union
+>>> from beartype.typing import Iterable, Union
 >>> from numerary.types import CachingProtocolMeta, Protocol, runtime_checkable
 
 >>> @runtime_checkable
@@ -292,7 +292,7 @@ Not very well, unfortunately, at least not on its own.
 ``Union``s allow a work-around.
 
 ``` python
->>> from typing import Union
+>>> from beartype.typing import Union
 >>> from numerary.types import SupportsFloorCeil, __floor__
 >>> SupportsFloorCeilU = Union[float, SupportsFloorCeil]
 
@@ -301,7 +301,7 @@ Not very well, unfortunately, at least not on its own.
 ...   assert isinstance(arg, SupportsFloorCeil)
 ...   return __floor__(arg)
 
->>> my_floor_func(float(1.2))  # works in 3.7+
+>>> my_floor_func(float(1.2))  # works in 3.8+
 1
 
 ```
@@ -546,23 +546,20 @@ Alternately, you can download [the source](https://github.com/posita/numerary) a
 
 ``numerary`` requires a relatively modern version of Python:
 
-* [CPython](https://www.python.org/) (3.7+)
-* [PyPy](http://pypy.org/) (CPython 3.7+ compatible)
+* [CPython](https://www.python.org/) (3.8+)
+* [PyPy](http://pypy.org/) (CPython 3.8+ compatible)
 
 It has the following runtime dependencies:
 
 * [``typing-extensions``](https://pypi.org/project/typing-extensions/) (with Python <3.9)
-
-``numerary`` will opportunistically use the following, if available at runtime:
-
-* [``beartype``](https://pypi.org/project/beartype/) for yummy runtime type-checking goodness (0.8+)
+* [``beartype``](https://pypi.org/project/beartype/) for caching protocols (0.10.1+)
   [![Bear-ified™](https://raw.githubusercontent.com/beartype/beartype-assets/main/badge/bear-ified.svg)](https://beartype.rtfd.io/)
 
-If you use ``beartype`` for type-checking your code, but don’t want ``numerary`` to use it internally, set the ``NUMERARY_BEARTYPE`` environment variable to a falsy[^6] value before ``numerary`` is loaded.
+``numerary`` will not use ``beartype`` internally unless the ``NUMERARY_BEARTYPE`` environment variable is set to a truthy[^6] value before ``numerary`` is loaded.
 
 [^6]:
 
-    I.E., one of: ``0``, ``off``, ``f``, ``false``, and ``no``.
+    I.E., one of: ``1``, ``on``, ``t``, ``true``, and ``yes``.
 
 See the [hacking quick-start](https://posita.github.io/numerary/0.3/contrib/#hacking-quick-start) for additional development and testing dependencies.
 

docs/notes.md

@@ -15,6 +15,19 @@
 
 # ``numerary`` release notes
 
+## [0.4.0](https://github.com/posita/numerary/releases/tag/v0.4.0)
+
+* Now relies on ``#!python beartype.typing.Protocol`` as the underlying caching protocol implementation.
+  This means that ``beartype`` is now ``numerary``’s only runtime dependency.
+  (``numerary`` still layers on its own runtime override mechanism via [CachingProtocolMeta][numerary._protocol.CachingProtocolMeta], which derives from ``beartype``’s.)
+
+  This decision was not made lightly.
+  ``numerary`` is intended as a temporary work-around.
+  It’s obsolescence will be something to celebrate.
+  Caching protocols, however, have much broader performance applications.
+  They deserve more.
+  ``beartype`` will provide what ``numerary`` was never meant to: a loving, stable, and permanent home.
+
 ## [0.3.0](https://github.com/posita/numerary/releases/tag/v0.3.0)
 
 * ~~Removes misleading advice that SCUs offer a performance benefit over merely using caching protocols.

docs/numerary.types.md

@@ -23,7 +23,7 @@
     I am working toward stability as quickly as possible, but be warned that future release may introduce incompatibilities or remove this package altogether.
     [Feedback, suggestions, and contributions](contrib.md) are desperately appreciated.
 
-In addition to the following protocols and helper functions, ``numerary.types`` also resolves importing ``Annotated``, ``Protocol``, and ``runtime_checkable`` from the best available source.
+Because ``numerary`` uses ``beartype`` in its implementation, you can use both to resolve importing ``Annotated``, ``Protocol``, and ``runtime_checkable`` from the best available source.
 This can be helpful if you need to support Python versions prior to 3.9, but don’t want to make a conditional import of ``typing_extensions`` everywhere.
 Instead of doing this all over the place …
 
@@ -37,18 +37,13 @@ except ImportError:
 … you can do this instead …
 
 ``` python
-from numerary.types import Annotated, Protocol, runtime_checkable
+from beartype.typing import Annotated, runtime_checkable
+from numerary.types import Protocol
 ```
 
 Bang.
 Done.
 
-Further, if you want to opportunistically take advantage of [``beartype``](https://github.com/beartype/beartype/) without imposing a strict runtime dependency, you can do this:
-
-``` python
-from numerary.bt import beartype  # will resolve to the identity decorator if beartype is unavailable at runtime
-```
-
 Which you should totally do, because ``beartype`` is *awesome*.
 Its author is even *awesomer*.[^1]
 
@@ -90,6 +85,7 @@ Its author is even *awesomer*.[^1]
         - "SupportsRealOps"
         - "SupportsIntegralOps"
         - "SupportsIntegralPow"
+        - "Protocol"
         - "real"
         - "imag"
         - "__pow__"

docs/perf_rational_baseline.txt

@@ -1,6 +1,6 @@
 %timeit isinstance(builtins.int(1), Rational)
-356 ns ± 15.2 ns per loop (mean ± std. dev. of 7 runs, 1000000 loops each)
+244 ns ± 8.05 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)
 %timeit isinstance(fractions.Fraction(2), Rational)
-350 ns ± 14.9 ns per loop (mean ± std. dev. of 7 runs, 1000000 loops each)
+237 ns ± 4.85 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)
 %timeit isinstance(builtins.float(3.0), Rational)
-359 ns ± 3.21 ns per loop (mean ± std. dev. of 7 runs, 1000000 loops each)
+273 ns ± 9.28 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)

docs/perf_rational_big_protocol.txt

@@ -1,6 +1,6 @@
 %timeit isinstance(builtins.int(1), SupportsLotsOfNumberStuff)
-136 µs ± 3.3 µs per loop (mean ± std. dev. of 7 runs, 10000 loops each)
+207 ns ± 9.04 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)
 %timeit isinstance(fractions.Fraction(2), SupportsLotsOfNumberStuff)
-154 µs ± 5.94 µs per loop (mean ± std. dev. of 7 runs, 10000 loops each)
+203 ns ± 1.85 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)
 %timeit isinstance(builtins.float(3.0), SupportsLotsOfNumberStuff)
-149 µs ± 8.33 µs per loop (mean ± std. dev. of 7 runs, 10000 loops each)
+220 ns ± 42 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)

docs/perf_rational_protocol.txt

@@ -1,6 +1,6 @@
 %timeit isinstance(builtins.int(1), SupportsNumeratorDenominator)
-13 µs ± 270 ns per loop (mean ± std. dev. of 7 runs, 100000 loops each)
+12.5 µs ± 1.45 µs per loop (mean ± std. dev. of 7 runs, 100,000 loops each)
 %timeit isinstance(fractions.Fraction(2), SupportsNumeratorDenominator)
-14 µs ± 761 ns per loop (mean ± std. dev. of 7 runs, 100000 loops each)
+11.1 µs ± 864 ns per loop (mean ± std. dev. of 7 runs, 100,000 loops each)
 %timeit isinstance(builtins.float(3.0), SupportsNumeratorDenominator)
-15.4 µs ± 323 ns per loop (mean ± std. dev. of 7 runs, 100000 loops each)
+12.2 µs ± 1.96 µs per loop (mean ± std. dev. of 7 runs, 100,000 loops each)

docs/perf_supports_complex.txt

@@ -1,25 +1,25 @@
 %timeit isinstance(builtins.int(1), _SupportsComplexOps)
-11.9 µs ± 279 ns per loop (mean ± std. dev. of 7 runs, 100000 loops each)
+340 ns ± 121 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)
 %timeit isinstance(builtins.int(1), SupportsComplexOps)
-312 ns ± 1.56 ns per loop (mean ± std. dev. of 7 runs, 1000000 loops each)
+258 ns ± 25.9 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)
 
 %timeit isinstance(builtins.float(2.0), _SupportsComplexOps)
-13.1 µs ± 385 ns per loop (mean ± std. dev. of 7 runs, 100000 loops each)
+224 ns ± 5.17 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)
 %timeit isinstance(builtins.float(2.0), SupportsComplexOps)
-380 ns ± 23 ns per loop (mean ± std. dev. of 7 runs, 1000000 loops each)
+221 ns ± 10.6 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)
 
 %timeit isinstance(decimal.Decimal(3), _SupportsComplexOps)
-13.3 µs ± 897 ns per loop (mean ± std. dev. of 7 runs, 100000 loops each)
+242 ns ± 18.2 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)
 %timeit isinstance(decimal.Decimal(3), SupportsComplexOps)
-322 ns ± 12.4 ns per loop (mean ± std. dev. of 7 runs, 1000000 loops each)
+245 ns ± 27.5 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)
 
 %timeit isinstance(fractions.Fraction(4), _SupportsComplexOps)
-11.9 µs ± 178 ns per loop (mean ± std. dev. of 7 runs, 100000 loops each)
+245 ns ± 27.6 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)
 %timeit isinstance(fractions.Fraction(4), SupportsComplexOps)
-314 ns ± 1.54 ns per loop (mean ± std. dev. of 7 runs, 1000000 loops each)
+234 ns ± 17.2 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)
 
 %timeit isinstance(sympy.core.numbers.Integer(5), _SupportsComplexOps)
-12 µs ± 110 ns per loop (mean ± std. dev. of 7 runs, 100000 loops each)
+227 ns ± 10.6 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)
 %timeit isinstance(sympy.core.numbers.Integer(5), SupportsComplexOps)
-315 ns ± 4.39 ns per loop (mean ± std. dev. of 7 runs, 1000000 loops each)
+225 ns ± 13.3 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)
 

numerary/__init__.py

@@ -8,7 +8,7 @@
 
 from __future__ import annotations
 
-from typing import Tuple, Union
+from beartype.typing import Tuple, Union
 
 from .types import *  # noqa: F401,F403