#!/usr/bin/env python3 # --------------------( LICENSE )-------------------- # Copyright (c) 2014-2025 Beartype authors. # See "LICENSE" for further details. ''' **Beartype plugin mixin hierarchy** (i.e., public classes intended to be subclassed as mixins by users extending :mod:`beartype` with third-party runtime behaviours). Most of the public attributes defined by this private submodule are explicitly exported to external users in our top-level :mod:`beartype.plug.__init__` submodule. This private submodule is *not* intended for direct importation by downstream callers. ''' # ....................{ IMPORTS }.................... from beartype.typing import ( Optional, Tuple, ) from beartype._util.cache.utilcachecall import callable_cached # ....................{ MIXINS }.................... class BeartypeHintable(object): ''' **Beartype hintable mixin** (i.e., class intended to be subclassed as a mixin by user-defined classes extending :mod:`beartype` with class-specific runtime type-checking via the :mod:`beartype`-specific :meth:`__beartype_hint__` method). Usage ----- **You are encouraged but not required to subclass this mixin.** Doing so publicly declares your intention to implement this abstract method and then raises a :exc:`NotImplementedError` exception when you fail to do so, improving the quality of your codebase with a simple contractual guarantee. This mixin does *not* require a custom metaclass and is thus safely subclassable by everything -- including your own classes. **Beartype internally ignores this mixin.** This mixin exists *only* to improve the quality of your codebase. Instead, beartype detects type hints defining :meth:`__beartype_hint__` methods via the :func:`getattr` builtin and then replaces those hints with the new type hints returned by those methods. In pseudo-code, this logic crudely resembles: e.g., .. code-block:: python # "__beartype_hint__" attribute of this type hint if any *OR* "None". beartype_hinter = getattr(hint, '__beartype_hint__') # If this hint defines this method, replace this hint with the new type # hint created and returned by this method. if callable(beartype_hinter): hint = beartype_hinter() You care about this, because this means that: * You can trivially monkey-patch third-party classes *not* under your direct control with :meth:`__beartype_hint__` methods, constraining those classes with runtime type-checking implemented by you! * :mod:`beartype` accepts *any* arbitrary objects defining :meth:`__beartype_hint__` methods as valid type hints -- including objects that are neither classes nor PEP-compliant! Of course, doing so would render your code incompatible with static type-checkers and thus IDEs. That's a bad thing. Nonetheless, this API enables you to do bad things. With great plugin power comes great user responsibility. ''' # ....................{ METHODS }.................... @classmethod def __beartype_hint__(cls) -> object: ''' **Beartype type hint transform** (i.e., :mod:`beartype`-specific dunder class method returning a new type hint, which typically constrains this class with additional runtime type-checking). ''' raise NotImplementedError( # pragma: no cover 'Abstract base class method ' 'BeartypeHintable.__beartype_hint__() undefined.' ) # ....................{ TESTERS }.................... #FIXME: Document us up, please. #FIXME: Unit test us up, please. #FIXME: Call us elsewhere, please. @callable_cached def is_hint_beartypehintable(hint: object) -> bool: # Return true only if this hint defines the "__beartype_hint__" attribute. return hasattr(hint, '__beartype_hint__') # ....................{ TRANSFORMERS ~ more than meets the }.................... # ....................{ eye }.................... #FIXME: Document us up, please. #FIXME: Unit test us up, please. #FIXME: Significant complications exist suggesting that we should immediately #release beartype 0.12.0 and contemplate implementing this later: #* The "beartype._check.error" subpackage will need to implement a comparable # mechanism as the "beartype._check.code" subpackage for detecting and avoiding # recursion in this reduction. Curiously, "beartype._check.error" only ever # calls the sanify_hint_child() sanifier in a single place. That simplifies # things a bit. Still, we'll need to add a similar "set" somewhere in that # subpackage tracking which "BeartypeHintable" objects have already been # reduced. #* Even ignoring that, detecting and avoiding recursion in # "beartype._check.code" alone will be non-trivial. We can't pass the original # presanified type hint to the make_check_expr() factory, because that hint has # *NOT* been coerced into a memoizable singleton (e.g., think PEP 585). That # means the caller needs to pass either: # * A boolean "is_hint_beartypehintable" parameter that is true only if the # presanified root type hint was a "BeartypeHintable". # * A "beartypehintables: Optional[set]" parameter that is a non-empty set # containing the presanified root type hint if that hint was a # "BeartypeHintable" *OR* "None" otherwise. # The caller can trivially detect "BeartypeHintable" hints by calling the # is_hint_beartypehintable() tester defined above. That's *NOT* the issue, # thankfully. The issue is that we call sanify_*_root() functions in exactly # three different places. We'll now need to duplicate this detection of # "BeartypeHintable" hints across those three different places. Is this # something we *REALLY* want to do? Is there truly no better way? # #Examining the code calling sanify_*_root() functions, it superficially looks #like we might want to consider *NO LONGER DEFINING OR CALLING* sanify_*_root() #functions. Like, seriously. The logic performed by those functions has become #trivial. They're practically one-liners. That said, sanify_hint_child() is #still extremely useful and should be preserved exactly as is. Consider: #* High-level functions calling sanify_*_root() functions should instead just # call either coerce_func_hint_root() or coerce_hint_root() based on context. # Those functions should *NOT* call reduce_hint() anymore. #* Excise up all sanify_*_root() functions. #* The make_check_expr() function should now call: # * On the passed root type hint: # if is_hint_beartypehintable(hint_root): # hint_parent_beartypehintables = {hint_root,} # hint_root = transform_hint_beartypehintable(hint_root) # # hint_root = reduce_hint(hint_root) # * On each child type hint: # # This exact logic is likely to be duplicated into # # "beartype._check.error". That's not particularly a problem -- just # # something worth noting. One approach to preserving DRY here would be # # to shift this "if" statement into sanify_hint_child(). Of course, # # everything then becomes non-trivial, because we would then need to # # both pass *AND* return "hint_parent_beartypehintables" sets to and # # from the sanify_hint_child() function. *sigh* # if ( # is_hint_beartypehintable(hint_child) and # hint_child not in hint_parent_beartypehintables # ): # if hint_parent_beartypehintables is None: # hint_parent_beartypehintables = {hint_child,} # else: # hint_parent_beartypehintables |= {hint_child,} # # hint_child = transform_hint_beartypehintable(hint_child) # # hint_child = sanify_hint_child(hint_root) #FIXME: Wow. What a fascinatingly non-trivial issue. The above doesn't work, #either. Why? Two reasons: #* sanify_*_root() functions *MUST* continue to perform reduction -- including # calling both reduce_hint() and transform_hint_beartypehintable(). Why? Because # reduction *MUST* be performed before deciding "is_hint_ignorable", which # *MUST* be decided before generating code. This is non-optional. #* transform_hint_beartypehintable() *CANNOT* be performed in either: # * reduce_hint(), because reduce_hint() is memoized but # transform_hint_beartypehintable() is non-memoizable by definition. # * coerce_*_hint(), because coerce_*_hint() is permanently applied to # "__annotations__" but transform_hint_beartypehintable() should *NEVER* be. # # Actually, that's no longer true. reduce_hint() *ABSOLUTELY* performs both # cached and uncached reductions now. It has to. So, # transform_hint_beartypehintable() should *ABSOLUTELY* be implemented as an # uncached reduction. # #Altogether, this suggests that: #* All sanify_*() functions *MUST* call transform_hint_beartypehintable() # directly, outside of calls to either reduce_hint() and coerce_*_hint(). # * Actually, don't do this. See above. Reduce "BeartypeHintable" objects in a # reducer now, please. #* Frozensets should be used. Doing so enables memoization, if we wanted. #* Call transform_hint_beartypehintable() from sanify_hint_child(), whose # signature *MUST* be augmented accordingly (i.e., to both accept and return # "hints_parent_beartypehintable: Optional[frozenset]"). #* Call transform_hint_beartypehintable() from sanify_*hint_root(), whose # signatures *MUST* be augmented accordingly (i.e., to additionally return # "Optional[frozenset]"). #* Augment make_check_expr() to: # * Accept an additional # "hints_parent_beartypehintable: Optional[frozenset]," parameter. # * Add yet another new entry to each "hint_meta" FixedList as follows: # * Define a new "HINT_META_INDEX_HINTS_PARENT_BEARTYPEHINTABLE" constant. # * For the root "hint_meta", initialize the value of: # hint_root_meta[HINT_META_INDEX_HINTS_PARENT_BEARTYPEHINTABLE] = ( # hints_parent_beartypehintable) #* Restore unit testing in "_data_nonpepbeartype", please. # #That should more or less do it, folks. Phew! It's still sufficiently #non-trivial that we want to defer this until *AFTER* beartype 0.12.0, though. #FIXME: Unit test us up, please. #FIXME: Document us up, please. @callable_cached def transform_hint_beartypehintable( hint: object, hints_parent_beartypehintable: Optional[frozenset], ) -> Tuple[object, Optional[frozenset]]: # ..................{ PLUGIN }.................. # Beartype plugin API. Respect external user-defined classes satisfying the # beartype plugin API *BEFORE* handling these classes in any way. # If this hint has already been transformed by a prior call to this # function, preserve this hint as is. Doing so avoids infinite recursion and # is, indeed, the entire point of the "hints_parent_beartypehintable" set. if ( hints_parent_beartypehintable and hint in hints_parent_beartypehintable ): return (hint, hints_parent_beartypehintable) # Else, this hint has *NOT* yet been transformed by such a call. # Beartype-specific "__beartype_hint__" attribute defined by this hint if # any *OR* "None" otherwise. # # Note that usage of the low-level getattr() builtin is intentional. *ALL* # alternative higher-level approaches suffer various deficits, including: # * Obstructing monkey-patching. The current approach trivializes # monkey-patching by third parties, enabling users to readily add # __beartype_hint__() support to third-party packages *NOT* under their # direct control. Alternative higher-level approaches obstruct that by # complicating (or just outright prohibiting) monkey-patching. # * Abstract base classes (ABCs) assume that hints that are classes are # issubclassable (i.e., safely passable as the first arguments of the # issubclass() builtin). Sadly, various real-world hints that are classes # are *NOT* issubclassable. This includes the core # "typing.NDArray[{dtype}]" type hints, astonishingly. Of course, even # this edge case could be surmounted by explicitly testing for # issubclassability (e.g., by calling our existing # is_type_issubclassable() tester); since that tester internally leverages # the inefficient Easier to Ask for Forgiveness than Permission (EAFP) # paradigm, doing so would impose a measurable performance penalty. This # only compounds the monkey-patching complications that an ABC imposes. # * PEP 544-compliant protocols assume that the active Python interpreter # supports PEP 544, which Python 3.7 does not. While Python 3.7 has # probably hit its End of Life (EOL) by the time you are reading this, # additional issue exist. On the one hand, protocols impose even *MORE* of # a performance burden than ABCs. On the other hand, protocols ease the # user-oriented burden of monkey-patching. # # In short, this low-level approach effectively imposes *NO* burdens at all. # There exists *NO* reason to prefer higher-level alternatives. __beartype_hint__ = getattr(hint, '__beartype_hint__', None) # If this hint does *NOT* define the "__beartype_hint__" attribute, preserve # this hint as is. if __beartype_hint__ is None: return (hint, hints_parent_beartypehintable) # Else, this hint defines the "__beartype_hint__" attribute. #FIXME: Define a new private exception type, please. # # If this attribute is *NOT* callable, raise an exception. # if not callable(beartypehintable_reducer): # raise SomeExceptiot(...) # # Else, this attribute is callable. # Replace this hint with the new type hint returned by this callable. hint = __beartype_hint__() if hints_parent_beartypehintable is None: hints_parent_beartypehintable = frozenset((hint,)) else: #FIXME: Unsure if this works for frozensets. Probably not. *sigh* hints_parent_beartypehintable |= {hint,} # Return this transformed hint. return (hint, hints_parent_beartypehintable)