Don't hide CachingProtocolMeta (#17)

Fixes #15.

README.md

@@ -238,7 +238,8 @@ More attributes means more comparisons.
 Further, it performs these comparisons … Every. Single. 🤬ing. Time.
 
 Protocols provided by ``numerary`` use instead [``CachingProtocolMeta``](https://posita.github.io/numerary/0.4/numerary.types/#numerary.types.CachingProtocolMeta) as their meta class.
-``CachingProtocolMeta`` derives from ``type(Protocol)`` and overrides ``__instancecheck__ `` to cache results based on instance type.
+``CachingProtocolMeta`` derives from ``type(beartype.typing.Protocol)`` which caches results based on instance type.
+``numerary``’s version allows for runtime check overrides of those results.
 
 Conceptually:
 

docs/notes.md

@@ -18,8 +18,9 @@
 ## [0.4.3](https://github.com/posita/numerary/releases/tag/v0.4.3)
 
 * Migrates from [``setuptools_scm``](https://pypi.org/project/setuptools-scm/) to [``versioningit``](https://pypi.org/project/versioningit/) for more flexible version number formatting.
-* Adds work-around for [posita/numerary#16](https://github.com/posita/numerary/issues/16).
+* Adds work-around for ``numpy``’s typing updates ([posita/numerary#16](https://github.com/posita/numerary/issues/16)).
 * Allows deployments to PyPI from CI based on tags.
+* Exposes ``CachingProtocolMeta`` ([posita/numerary#15](https://github.com/posita/numerary/issues/15)).
 
 ## [0.4.2](https://github.com/posita/numerary/releases/tag/v0.4.2)
 
@@ -33,20 +34,20 @@
 
 * Now relies on ``#!python beartype.typing.Protocol`` as the underlying caching protocol implementation.
   This means that ``beartype`` has emerged as ``numerary``’s sole runtime dependency.
-  (``numerary`` still layers on its own runtime override mechanism via [CachingProtocolMeta][numerary._protocol.CachingProtocolMeta], which derives from ``beartype``’s.)
+  (``numerary`` still layers on its own runtime override mechanism via [CachingProtocolMeta][numerary.protocol.CachingProtocolMeta], which derives from ``beartype``’s.)
   It also means that ``numerary`` loses Python 3.7 support, but that was largely illusory anyway.
 
   This decision was not made lightly.
   ``numerary`` is intended as a temporary work-around.
-  It’s obsolescence will be something to celebrate.
+  Its 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.
-  They *could* under very specific circumstances (where ``numerary`` probably isn’t going to be helpful anyway), but not always, and probably aren’t worth the trouble if performance is the only concern.~~
+  They *could* under very specific circumstances (where ``numerary`` probably will not help anyway), but not always, and probably aren’t worth the trouble if performance is the only concern.~~
   Actually, removes SCUs altogether and documents a surgical example for those rare occasions where it might be needed.
 * Finally removes ``SupportsNumeratorDenominatorProperties`` as promised.
 
@@ -77,9 +78,9 @@
 
 ## [0.1.0](https://github.com/posita/numerary/releases/tag/v0.1.0)
 
-* Adds [``CachingProtocolMeta.includes``][numerary._protocol.CachingProtocolMeta.includes],
-  [``CachingProtocolMeta.excludes``][numerary._protocol.CachingProtocolMeta.excludes], and
-  [``CachingProtocolMeta.reset_for``][numerary._protocol.CachingProtocolMeta.reset_for]
+* Adds [``CachingProtocolMeta.includes``][numerary.protocol.CachingProtocolMeta.includes],
+  [``CachingProtocolMeta.excludes``][numerary.protocol.CachingProtocolMeta.excludes], and
+  [``CachingProtocolMeta.reset_for``][numerary.protocol.CachingProtocolMeta.reset_for]
   cache override functions.
 * Retires ``…SCT`` tuples as unnecessary, especially in light of cache overrides.
   (Runtime ``isinstance`` protocol checking is fast enough.)

docs/numerary.protocol.md

@@ -0,0 +1,41 @@
+<!---
+  Copyright and other protections apply. Please see the accompanying LICENSE file for
+  rights and restrictions governing use of this software. All rights not expressly
+  waived or licensed are reserved. If that file is missing or appears to be modified
+  from its original, then please contact the author before viewing or using this
+  software in any capacity.
+
+  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+  !!!!!!!!!!!!!!! IMPORTANT: READ THIS BEFORE EDITING! !!!!!!!!!!!!!!!
+  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+  Please keep each sentence on its own unwrapped line.
+  It looks like crap in a text editor, but it has no effect on rendering, and it allows much more useful diffs.
+  Thank you!
+-->
+
+# ``#!python numerary.protocol`` package reference
+
+!!! warning "Experimental"
+
+    This package is an attempt to ease compatibility between Python’s numbers and types.
+    If that sounds like it shouldn’t be a thing, you won’t get any argument out of me.
+    Anyhoo, this package should be considered experimental.
+    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.
+
+``numerary`` has donated its core caching protocol implementation to (and now depends on) [``beartype``](https://github.com/beartype/beartype).
+``beartype`` is *awesome*, and its author is even *awesomer*.[^1]
+``numerary``’s version (in this package) augments that implementation to allow for runtime check overrides.
+
+[^1]:
+
+    I acknowledge that the subject of who is awesomer, beartype or the man who made it, is [hotly contested](https://github.com/beartype/beartype/issues/66#issuecomment-960495976).
+
+::: numerary.protocol
+    rendering:
+      show_if_no_docstring: false
+      show_root_heading: false
+      show_root_toc_entry: false
+    selection:
+      members:
+        - "CachingProtocolMeta"

docs/numerary.types.md

@@ -23,19 +23,6 @@
     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.
 
-``numerary`` has donated its core caching protocol implementation to (and now depends on) ``beartype``.
-``beartype`` is *awesome*, and its author is even *awesomer*.[^1]
-
-[^1]:
-
-    I acknowledge that the subject of who is awesomer, beartype or the man who made it, is [hotly contested](https://github.com/beartype/beartype/issues/66#issuecomment-960495976).
-
-
-::: numerary._protocol.CachingProtocolMeta
-    rendering:
-      show_if_no_docstring: false
-      show_root_heading: true
-
 ::: numerary.types
     rendering:
       show_if_no_docstring: false

mkdocs.yml

@@ -16,6 +16,7 @@ nav:
   - License: license.md
   - API:
     - <tt>numerary</tt>: numerary.md
+    - <tt>numerary.protocol</tt>: numerary.protocol.md
     - <tt>numerary.types</tt>: numerary.types.md
 
 # See:

numerary/types.py

@@ -26,8 +26,8 @@
 from beartype.typing import SupportsInt as _SupportsInt
 from beartype.typing import SupportsRound as _SupportsRound
 
-from ._protocol import CachingProtocolMeta
 from .bt import beartype
+from .protocol import CachingProtocolMeta
 
 if TYPE_CHECKING:
     from typing import Protocol