Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
This minor release expands the infinitely vast (yet mostly empty) universe of @beartype into the hitherto uncharted realms of **configuration,** **exception identification,** **Nuitka,** **`typing.NamedTuple`,** and **Python 3.11.** Also, other things were done. We swear it! This minor release resolves **16 issues** and merges **2 pull requests.** Noteworthy changes include: ## Compatibility Improved. * **Python 3.11.** This is the first @beartype support to officially support the recently released Python 3.11. Notably, this release: * Synchronizes our public `beartype.typing` subpackage against upstream changes in the standard `typing` module introduced in Python 3.11. * Supports PEP-compliant type hints subscripted by the empty tuple (e.g., `typing.Tuple[()]`), whose low-level implementation fundamentally changed under Python 3.11. * Updates our GitHub Actions-based continuous integration (CI) workflow to exercise @beartype against Python 3.11. * **Nuitka.** This is the first @beartype release to officially support Nuitka (i.e., the increasingly popular Python compiler that stuns us all), resolving feature request #197 kindly submitted by @shenwpo (also known as the giant flaming metallic letter e). This includes a new `test_nuitka()` integration test showing that Nuitka successfully compiles a minimal-length example (MLE) runtime type-checked by @beartype. * **`typing.NamedTuple`.** This release adds support for deeply type-checking subclasses of the PEP 484-compliant `typing.NamedTuple` superclass. Specifically, this release improves the resiliency of our PEP 563 resolution mechanism (i.e., the public `beartype.peps.resolve_pep563()` function) against callables whose `__module__` dunder attributes lie. This includes *all* `typing.NamedTuple` subclasses, which synthesize callables whose `__module__` dunder attributes erroneously claim to reside in the non-existent `"namedtuple_Foo"` module. Doing so resolves issue #181 kindly submitted by probably ingenious "Probabilistic Machine Learning" author @murphyk (Kevin P. Murphy). ## Features Added * **Beartype configuration API.** This release publishes a new public API for externally configuring @beartype via the now-official `beartype.BeartypeConf` type and `beartype.BeartypeStrategy` enumeration. Specifically, this release adds: * **`beartype.BeartypeConf.is_color`,** a new tri-state boolean enabling end users to control how and whether beartype colours **type-checking violations** (i.e., :class:`beartype.roar.BeartypeCallHintViolation` exceptions) with POSIX-compliant ANSI escape sequences for readability, resolving issue #178 kindly submitted by the foxy ZeroGuard and River Oakfield founder @foxx (Cal Leeming). Rejoice, typing acolytes, for you have now been freed from the prismatic shackles of the rainbow! * **`beartype.BeartypeConf.is_pep484_tower`**, a new standard boolean enabling end users to control whether @beartype supports the [implicit numeric tower standardized by PEP 484](https://peps.python.org/pep-0484/#the-numeric-tower) or not, resolving issue #174 kindly submitted by dashing French Canadian @felixchenier (Félix Chénier). * **`beartype.BeartypeStrategy.O0`**, a new **no-time strategy** (i.e., beartype configuration option generalizing the standard `@typing.no_type_check` decorator). Enabling this strategy instructs the `@beartype` decorator to recall and preserve previously applied no-time strategies; internally, `@beartype` detects and reduces configurations resembling `conf=BeartypeConf(strategy=BeartypeStrategy.O0, ...)` to the `@typing.no_type_check` decorator. Users may now blacklist specific callables from being type-checked by configuring this strategy as documented in our front-facing `README.rst` documentation... *somewhere.* It's in there somewhere, people. * **Beartype exception API.** This release publishes a new public API for externally identifying the cause of **type-checking violations** (i.e., instances of the `beartype.roar.BeartypeCallHintViolation` exception class) raised by @beartype. These exceptions now publicly expose the user-defined objects responsible for those violations via a new `BeartypeCallHintViolation.culprits` property, resolving feature request #180 kindly submitted by @Jasha10 the Supremely Patient and Understanding GitHubber. For safety, this property dynamically returns a non-empty tuple of the one or more responsible culprits defined as either: * For each culprit that supports weak references and is still alive (i.e., has yet to be garbage-collected), that culprit as is. * Else, the machine-readable string representation of that culprit truncated to a reasonable number of characters. ## Features Deprecated * **`beartype.roar.BeartypeAbby*Exception`.** This release deprecates all lingering remnants of the prior `beartype.abby` subpackage – including: * `beartype.roar.BeartypeAbbyException`, supplanted by `beartype.roar.BeartypeDoorException`. * `beartype.roar.BeartypeAbbyHintViolation`, supplanted by `beartype.roar.BeartypeDoorHintViolation`. * `beartype.roar.BeartypeAbbyTesterException`, supplanted by `beartype.roar.BeartypeDoorException`. ## Static Type-checking Improved * **@beartype exports.** This release terminally pacifies: * Mypy by publicizing all exported attributes from the top-level `beartype` package via a new `beartype.__all__` dunder attribute. Thanks to the stylishly pink-haired @pinkwah (Zohar Malamant) for the rapid pull request (PR). * `pyright` by explicitly re-exporting all public attributes of the top-level `beartype` package, resolving issue #169 kindly submitted by MIT AI mastermind @rsokl (Ryan Soklaski). * **Continuous integration (CI).** This release integrates our GitHub Actions-based continuous integration (CI) workflow (i.e., `.github/workflows/python_test.yml`) with third-party GitHub Actions statically type-checking beartype against both `mypy` and `pyright` at CI time – including on every commit as well as pull request (PR). For both robustness and efficiency, this release prevents functional tests in our test suite that perform these same static type-checks from running under CI. Doing so resolves a furious spate of spurious CI complaints. So what we did there? We rhymed. Notably, this release: * Leverages @jakebailey's superb `jakebailey/pyright-action` action to exercise @beartype against `pyright` at CI time. * Manually installs and runs `mypy` in a low-level manner under CI *without* leveraging @jpetrucciani's otherwise stellar `jpetrucciani/mypy-check` action -- which @beartype hopes to revisit at a later date when the issue tracker settles there a bit. Thanks so much, @jpetrucciani! You dah real QA MVP. ## Issue Resolved * **`beartype.door.TypeHint` comparisons.** This release significantly improves the robustness of comparison operators overloaded by the object-oriented `beartype.door.TypeHint` API, resolving issue #198 kindly submitted by @wesselb the phenomenal Amsterdammer of [Plum](https://github.com/wesselb/plum) fame. This includes edge cases when: * Comparing unions against both other unions *and* non-unions (e.g., `typing.Any`, isinstanceable classes). * Comparing tuple type hints against `typing.Any`. * **`beartype.BeartypeConf` caching.** This release resolves a critical (yet ultimately trivial) caching issue with respect to `beartype.BeartypeConf` singletons, in which singletons initialized with different parameters could conceivably have been erroneously cached to the same object. Hash collisions! I see hash collisions everywhere! * **Call stack iteration robustness.** This release resolves an edge case in our private `beartype._util.func.utilfuncframe.iter_frames()` generator iterating over stack frames on the current call stack. Specifically, this generator now safely reduces to the empty generator (i.e., noop) when the caller requested that generator ignore more stack frames than exist on the call stack. Although raising an exception would also be feasible, doing so would only needlessly increase the fragility of this already fragile mission-critical generator. ## Documentation Resolved * **Broken anchor links.** This release repairs broken anchor links dotted throughout our monolithic `README.rst` to actually point to valid (sub)sections. * **Sphinx configuration.** This release reconfigures the lackluster coffin that is our Sphinx configuration, en-route to resolving issue #8 (!) kindly submitted a literal lifetime ago by visionary computer vision export and long-standing phenomenal Finn @felix-hilden (Felix Hildén). Specifically, this release: * **Enables Furo,** switching from the default Read The Docs (RTD) Sphinx theme to the third-party Furo theme. We selected this theme according to mostly objective (albeit ultimately subjective) heuristic criteria. In descending order of importance, we selected the theme with: 1. The most frequent git commit history. 2. The open issues and pull requests (PRs). 3. The most GitHub stars as a crude proxy for aggregate rating. Furo handily bested all other themes across all three criteria. Furo is very well-maintained, frequently closes out open issues and merges open PRs, and sports the highest quantity of GitHub stars by an overwhelming margin. `\o/` * **Enables the builtin `intersphinx` extension,** enabling attributes defined by the standard library (e.g., the `typing` module, the `types.GenericAlias` type) to be cross-referenced as a fallback when *not* already defined by this project. * **Reconfigures RTD** through our top-level `.readthedocs.yml` configuration to: * Build under the most recent Long Term Service (LTS) release of Ubuntu. * Build under the most recently released minor version of CPython. * Configure Sphinx via our `doc/source/conf.py` script. * **Restores the standard `sys.path` hack** – which, for unknown reasons, @leycec disabled but thankfully left commented out. Doing so re-resolves issue #120, kindly submitted by @kloczek (Tomasz Kłoczko) five friggin' months ago. Thanks so much for the fast patch and rapid turn-around, @kloczek! * **Improves pathname robustness** by intelligently detecting documentation paths via the standard `pathlib.Path` API. * **Enables `autoapi`.** This release successfully transitions from Sphinx's builtin (but insane) `autodoc` and `autosummary` extensions to Read The Doc (RTD)'s non-builtin (but sane) `autoapi` extension. * **Adds a local URI store** (i.e., hidden reStructuredText (reST) document centralizing common URI links in reST format, automatically exposed to all other reST documents in this project via the `rst_epilog` setting in `conf.py`) at `doc/src/_links.rst`. * **Removes obsolete cruft,** which accrues with time like entropic motes in God's eye. That was a reference to a Golden Age of Scifi book, people! Don't ask why God only has one eye. It's better not to contemplate these matters. * **Ruthlessly circumvents upstream issue sphinx-doc/sphinx#4961,** causing Sphinx to emit literally hundreds of ignorable warnings resembling ``"WARNING: more than one target found for cross-reference 'TypeHint':`` ``beartype.door._doorcls.TypeHint, beartype.door.TypeHint"`` with a [trivial circumvention shamelessly pilfered from @RDFLib](https://github.com/RDFLib/rdflib/blob/3a418218d6bcdb46f78342e14c024063e2f53e71/docs/conf.py#L255). ## Documentation Added * **[Beartype Object-oriented API](https://github.com/beartype/beartype/tree/76aebd63b5f32ac6bdab6420eb0c9bfa2ca09b29#id36).** This release prefaces our "Beartype Object-oriented API" subsection with a human-readable discussion of the Decidedly Object-Oriented Runtime-checking (DOOR) – also known as "That API Which Breaks Hearts and Minds Alike." * **[Procedural Showcase]**(https://github.com/beartype/beartype/#procedural-showcase). This release adds a new *Procedural Showcase* subsection containing a new *Detect API Breakage* subsubsection exhibiting a real-world usage for our recently published `beartype.door.is_subhint()` tester: detecting API breakage across the type hints annotating arbitrary callables in exactly ten lines of code. * **[Near-real-time FAQ entry](https://github.com/beartype/beartype/#beartype-realtime).** This release adds a new FAQ entry entitled *What does "near-real-time" even mean?*, justifying our recent categorization of @beartype as a "near-real-time runtime type-checker." Let's pretend @leycec knows what he's talking about. * **[JAX, Numpy, and PyTorch FAQ entries](https://github.com/beartype/beartype/#jax-arrays).** This release expands our existing FAQ with entries on typing JAX and NumPy arrays and PyTorch tensors to highlight the stupefying potential unlocked by the third-party `jaxtyping`, `nptyping`, and TorchTyping packages, resolving issue #98 submitted a literal lifetime ago by Edinburgh NLP researcher @amitkparekh (Amit Parekh). * **[VSCode FAQ entry](https://github.com/beartype/beartype/tree/76aebd63b5f32ac6bdab6420eb0c9bfa2ca09b29#id28).** This release rewrites our entire FAQ entry on `pyright` + Pylance + VSCode to be significantly more charitable towards `pyright`, resolving issue #170 kindly submitted by MIT AI mastermind @rsokl (Ryan Soklaski). * **[Type narrowing FAQ entry](https://github.com/beartype/beartype/tree/76aebd63b5f32ac6bdab6420eb0c9bfa2ca09b29#id30).** This release adds a new FAQ entry on type narrowing, strongly inspired by (*...wait for it*) MIT AI mastermind @rsokl (Ryan Soklaski)'s equally masterful writing at issue #166. (*Powerful bowers full of flowers!*)
- Loading branch information
