[Installation] @beartype's description is so big it hurts. #203

LittleBigGene · 2023-01-09T05:19:45Z

ERROR: Could not install requirement beartype>=0.9.1 (from flet) because of HTTP error 400 Client Error: Bad Request - The package description exceeds the maximum length of 324608 bytes.

leycec · 2023-01-18T06:22:43Z

Gah! I somehow missed this in the recent scrum to release beartype 0.12.0. I've... actually never even heard of Flet. Looks pretty swag, though. That said, Flet isn't actually a package manager. It's a UI framework. I am confused, but optimistic that I can become less confused.

Which package manager were you attempting to install @beartype with? pip? Conda? Mamba? Poetry? Somebody else? Pretty sure those all work – but not certain, anymore. Perhaps @beartype's ponderous weight finally broke someone's fragile back. 😮‍💨

In any case, we might need to finally redact our package description. Admittedly, it has become obscenely large. Our README.rst currently stands at 315KB and can only grow larger with time.

LittleBigGene · 2023-01-18T17:37:35Z

I did "pip install flet", hoping to try it out.

Yes, I believe it's complaining about the size of the package description.

leycec · 2023-01-19T06:25:13Z

Yikes! Thanks so much for the rapid clarification, @LittleBigGene. Great GitHub username, too. Clever puns are a fragile work of art we appreciate here.

If pip is indeed dying on @beartype, that is awful. Tragically, I can't locally replicate this:

$ pip3 install beartype==0.11.0
Defaulting to user installation because normal site-packages is not writeable
Collecting beartype==0.11.0
  Downloading beartype-0.11.0-py3-none-any.whl (702 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 702.5/702.5 kB 60.6 kB/s eta 0:00:00
Installing collected packages: beartype
Successfully installed beartype-0.11.0

I wonder if this might be a platform-specific issue of some sort. Are you on Windows or macOS, perchance? pip on Linux behaves itself, but that doesn't seem to be extending to other platforms. In any case, you're not wrong and I absolutely do not doubt you.

Regardless of whether I can replicate this or not, we must decrease the size of our package description. This is sort of a duplicate of issue #8, because hosting our documentation with Read The Docs (RTD) should resolve this. But let's leave this open until I belatedly do something. 😉

langfield · 2023-01-19T14:57:14Z

Could the package description simply use a less bulky version of the README.rst?

leycec · 2023-01-20T06:39:46Z

Totally. You got it. I suspect I might even do the opposite, which might be even easier:

Shift our entire README.rst onto Read the Docs (RTD) all at once. In theory, this is trivial. Our documentation already works here; it should work there, too. In practice, I weep silently.
Reduce the README.rst file hosted at this repository to just the introduction followed by a bold-face big red link redirecting everybody to RTD.
Sloooowly begin splitting up our documentation on RTD into multiple interlinked documents (as sanity requires).

Since our project description pulls directly from README.rst, this then feeds three birds with one outstretched palm. Read this five-year plan and believe my convenient promises, everyone. 🤲

leycec · 2023-01-20T07:06:16Z

@langfield: Oh, and thanks a heap overflow for your overwhelming generosity! Please e-mail me sometime at Bear Bro <leycec@gmail.com> when you find a spare moment and I'll happily inject your favourite URL and/or witty one-liner at the head of @beartype release changelogs.

I meant to contact you sooner about that earlier. I swear! But I couldn't find your e-mail, because my Google-stalking skills have decayed with time. (I feel old now.)

Also, Anki. Feels so nostalgic it physically hurts with the 懐かしい. Can I interest you in a gentlemanly Japanese visual novel for inquiring minds? @leycec guarantees satisfaction. 😸

@LittleBigGene

This commit is the first in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit successfully (*...at least, locally*) converts the introduction of our `README.rst` into Sphinx-compatible form. In theory, RTD should then render this introduction automatically. Inquiring GitHubbers now want to know what RTD thinks about these hard and valiant efforts. Let's see, everybody! *But don't get your hopes up.* (*Unending NANDs of doom!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit fundamentally reconfigures our RTD configuration to avoid pinning exact versions of Sphinx and Sphinx plugins. Doing so failed painfully by constraining us to obsolete Sphinx versions known to be broken. *Woops.* In theory, RTD should now render the introduction of this documentation automatically. Inquiring GitHubbers now want to know what RTD thinks about these hard and valiant efforts. Let's see, everybody! *But don't get your hopes up.* (*Unyielding elderberries of minty merriment!*)

leycec · 2023-01-20T09:04:15Z

So. It begins... yet again. Die, Sphinx! Die! 😮‍💨

Sphinx, we face thee valiantly with great exhaustion in our hearts.

leycec · 2023-01-20T09:07:49Z

Hah! Through the power of slathering jaws slick with rabies, @beartype finally forced its introduction through the Read the Docs (RTD) parser. Sure, most links are hideously busted. That's a given when you've neglected documentation for two years. But we will succeed. Somehow.

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit improves documentation for both the `die_if_unbearable()` raiser *and* the related `BeartypeCallHintViolation` exception type. (*Ostentatious mountaineers on Austin Martins!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit transitions our *Install* section from `README.rst` to RTD. Glory is becoming manifest! (*Adroit androids!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit circumvents a mostly ignorable complaint concerning tables of contents emitted by the Furo Sphinx theme. Silence, Furo! Feel the fury of @leycec. Feel it. (*Philatelic philanthropist of angelic solipsism, arthropod!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit fully transitions our *Overview* section and partially transitions our *FAQ* section from `README.rst` to RTD. Documentation emerges from the primordial soup of @beartype's shameless past for which we cannot be blamed. @leycec was young and dumb back then. (*Urge to splurge, too!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit fully transitions all subsections up to but *not* including our **Beartype Validators** discussion from `README.rst` to RTD. Documentation emerges from the primordial soup of @beartype's shameless past for which we cannot be blamed. @leycec was young and "spirited" back then. (*Nefarious planetarium inside an insidious terrarium!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit continues transitioning all subsections up to but *not* including our **Beartype Validators** discussion from `README.rst` to RTD. Documentation emerges from the primordial soup of @beartype's shameless past for which we cannot be blamed. @leycec was young and "spirited" back then. (*Utterly plugged lug nut!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit begins defining a new introductory **Beartype Decoration** subsection detailing usage of our core ``@beartype.beartype`` decorator. Documentation emerges from the primordial soup of @beartype's shameless past for which we cannot be blamed. @leycec was young and "spirited" back then. (*Obstructive obstetricians!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit finalizes our new introductory **Beartype Decoration** subsection detailing usage of the core ``@beartype.beartype`` decorator. Documentation emerges from the primordial soup of @beartype's shameless past for which we cannot be blamed. @leycec was young and "spirited" back then. (*Burdensome den of some burdock!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit splits our leading **Install** section into a new file entirely -- the first of many such splits intended to substantially improve the navigability of @beartype docos. Documentation emerges from the primordial soup of @beartype's shameless past for which we cannot be blamed. @leycec was young and "spirited" back then. (*Instructive minstrels destructively bash a dashing mini-kestrel!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit updates our installation instructions to note @beartype's recent availability as an official package in both Gentoo Linux's Portage tree *and* Arch Linux's Arch User Repository (AUR). Truly, this can only be the final mark of pride. Relatedly, this commit also resolves a perplexing issue preventing Sphinx-specific `conf.py` files remotely run by ReadTheDocs (RTD) from containing `@beartype`-decorated objects. We shrug noncommittally. (*Maddening sadness gladly unsettles badness!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this temporarily ceases attempting to resolve a perplexing issue preventing Sphinx-specific `conf.py` files remotely run by ReadTheDocs (RTD) from containing `@beartype`-decorated objects. We shrug noncommittally. Although non-ideal, nobody else cares about this and our documentation is in critical disrepair. In other words, we have burning dumpster fires that need attending to. Ignore this, RTD! (*Silence, licensed silos!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this temporarily ceases attempting to resolve a perplexing issue preventing Sphinx-specific `conf.py` files remotely run by ReadTheDocs (RTD) from containing `@beartype`-decorated objects. We shrug noncommittally. Although non-ideal, nobody else cares about this and our documentation is in critical disrepair. In other words, we have burning dumpster fires that need attending to. Ignore this, RTD! Yes, we really insist we know what we're doing here. (*Fry, dry, and cry!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit: * Temporarily disables usage of the otherwise exemplary third-party `sphinxext.opengraph` Sphinx extension, due to outstanding issue wpilibsuite/sphinxext-opengraph#98. * Extricates the leading "ELI5" section into its own `eli5.rst` document. * Repairs all external references to that document. *We doin' this.* (*Major merger!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit: * Successfully extracts our FAQ into a new `faq` subdocument. * Circumvents upstream's long-standing issue with empty left sidebars at pydata/pydata-sphinx-theme#221 via the requisite template hack that we now riskily embed in our Sphinx tree. Hang on, folks! The ride ahead is perilous, indeed. (*Discursive cursive discourse is the discus' course!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit successfully extracts our feature matrix into a new `pep` subdocument. Slowly, we increment to the baleful finish line. (*Ireful bales of balefire!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit successfully extracts our cheatsheet into a new `tl;dr` subdocument. Slowly, we increment to the baleful finish line. (*Cotton-candy clouds loudly hop randy clods of mutton!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit **publicly advises everyone to begin referencing our new RTD-hosted documentation rather than our `README.rst` file.** This means you, because you are reading this. Hah! Don't think we don't see you lurking behind that keyboard. (*Corpulent opulence!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit circumvents upstream theme issues pydata/pydata-sphinx-theme#90 and pydata/pydata-sphinx-theme#221 with the "standard" `_templates/sidebar-nav-bs.html` hack shamelessly copy-pasted into literally *every* project requiring that theme. This includes @beartype, because why not spew boilerplate that nobody understands everywhere? (*Intimate intimations of illegitimate legerdemain!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit circumvents upstream theme issues pydata/pydata-sphinx-theme#90, pydata/pydata-sphinx-theme#221, and pydata/pydata-sphinx-theme#1181 with the "standard" `_templates/sidebar-nav-bs.html` hack shamelessly copy-pasted into literally *every* project requiring that theme. This includes @beartype, because why not spew boilerplate that nobody understands everywhere? Sadly, doing so now requires pinning to a maximum obsolete version of this theme that will also surely die soon. And this is why I facepalm. (*Illogical ontological topology!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit isolates our manually generated API (...lol) into a new `api.rst` document *and* continues transitioning API documentation from `README.rst` into that document. It is a heavy weight we bear, but we bear it so that you need not. (*Lonesome burden, unordained denizen!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit continues transitioning API documentation from `README.rst` into our new `api.rst` document. It is a heavy weight we bear, but we bear it so that you need not. (*Zen-like netizen frolics in fields of irksome nettles!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit finalizes transitioning *all* API documentation from `README.rst` into our new `api.rst` document. It is a heavy weight we bear, but we bear it so that you need not. (*Flask or cask? It's a heavy ask!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit transitions our timings and math discussion from `README.rst` into a new `math.rst` document. It is a heavy weight we bear, but we bear it so that you need not. (*Unflagging flagon!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit transitions our code generation discussion from `README.rst` into a new `code.rst` document. This commit signals the end of the grand mass migration. Our `README.rst` document is now superfluous dead weight and will be truncated shortly. All remaining work is further subdividing the existing `api.rst` document into smaller documents and properly interlinking the remainder of the documents to attributes documented in those smaller documents. (*Wondrous wanderers in a susaf lustrousness!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit isolates the "Beartype Validators" subsection of our existing `api.rst` document into its own `api/vale.rst` subdocument -- substantially improving the readability of both. (*Insatiably poignant poinsettia!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit: * Isolates the remaining sections of our existing `api.rst` document into their own subdocuments in the `api/` subdirectory. * Begins refactoring API documentation in these subdocuments from its current ad-hoc state to properly marked up Sphinx directives. (*Litigious contiguity!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit temporarily disables the classic `_templates/sidebar-nav-bs.html` template -- which sadly appears to be silently broken on ReadTheDocs (RTD) but *not* locally. Thus, we sigh. (*Inspirational navigation of notional spires!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit unpins `pydata-sphinx-theme` to update to arbitrarily new versions on RTD. In theory, doing so *should* resolve the disastrously empty sidebar. In practice, doing so *will* reduce to a noop causing us to pull even more of our hair out. (*Dance of happy happenstance!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit: * Repins `pydata-sphinx-theme` to the most recently released stable version of that package. * Removes the problematic `sidebar-nav-bs.html` template entirely. In theory, doing so *should* resolve the disastrously empty sidebar. In practice, doing so *will* reduce to a noop causing us to pull even more of our hair out. (*Floppy mops!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit resolves a subtle string formatting issue in our Sphinx configuration. This is why @leycec cries like a mewling cat with no milk. (*Milky silk!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit attempts to discover why the empty sidebar is still empty. Seriously. Why. (*Wizened raisins!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit circumvents the dreaded empty sidebar issue (which actually appears to be a remote RTD-specific issue at this belated point, which is pretty much the worst-case outcome) by simply flattening our `doc/src/` subdirectory structure (which is insane, but welcome to 2023). Absolutely *not* happy about any of this, but it's unclear whether anyone living is even to blame. I blame only myself for not embracing `mkdocs` when I had the opportunity. (*Absolved ablutions!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit circumvents the dreaded empty sidebar issue (which actually appears to be a remote RTD-specific issue at this belated point, which is pretty much the worst-case outcome) yet again by: * Repinning back to the antiquated (but presumably working) `pydata-sphinx-theme 0.7.3`. * Restoring our prior infamous `sidebar-nav-bs.html` template kludge. All bear claws are crossed. This has increased our Luck stat. In theory, doing so allows us to now pass this critical stat check. Go, go, go!!!! (*Critical Brit horticulture!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit lightly revises our "Beartype Decorator" API subsection for sanity. (*Motile motel!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit substantially improves all this insanity thanks to a risky yet profitable 5-hour documentation spree. The only significant remaining roadblacks are the `api_door.rst` and `api_roar.rst` documents, which have yet to be properly Sphinx-ified. In any case, we're well on-target to **officially truncating** our `README.rst` documentation this Friday. Readable docos: *engage!* (*En garde, engaging gauge!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit properly Sphinx-ifies the `api_roar.rst` document.. The only significant remaining roadblack is the `api_door.rst` document, which have yet to be properly Sphinx-ified. In any case, we're well on-target to **officially truncating** our `README.rst` documentation this Friday. Readable docos: *engage!* (*Timely temerity, timorous moroseness!*)

@LittleBigGene

This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit begins Sphinx-ifying the `api_door.rst` document. We're *kinda* still on-target to **officially truncate** our `README.rst` documentation this Friday. Readable docos: *engage!* (*Miserly commiseration, commissar!*)

@LittleBigGene

This commit is the last in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), resolving both issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell) and ancient issue #8 kindly submitted by @felix-hilden (AKA the Finnish computer vision art genius that really made all of this possible). Specifically, this commit: * Finishes Sphinx-ifying our entire frickin' document base. * Officially truncates our `README.rst` documentation. Readable docos: *engage!* (*Illegible legerdemain has no domain!*)

leycec · 2023-03-04T09:06:01Z

Resolved by 86b79db.

Beartype documentation now officially lives at ReadTheDocs (RTD). Our README.rst file has been truncated to a shadow of its former self. So this is what it feels like when bears cry.

@ulfaslakprecis

This minor release delivers pulse-quickening support for **pandera (pandas) type hints,** **PEP 484,** **PEP 585**, **PEP 591**, **PEP 647**, **PEP 3119**, and **pseudo-callables.** This minor release resolves **12 issues** and merges **2 pull requests.** But first, a quiet word from our wondrous sponsors. They are monocled QA wizards who serve justice while crushing bugs for humanity. High fives, please! ## Beartype Sponsors * [**ZeroGuard:** The Modern Threat Hunting Platform](https://zeroguard.com). *All the signals, All the time.* Thunderous applause echoes through the cavernous confines of the Bear Den. 👏 🐻‍❄️ 👏 And now... the moment we've waited for. A heinous display of plaintext that assaults all five senses simultaneously. ## Compatibility Added * **Pandera (pandas) type hints** (i.e., ad-hoc PEP-noncompliant type hints validating pandas `DataFrame` objects, produced by subscripting factories published by the `pandera.typing` subpackage and validated *only* by user-defined callables decorated by the ad-hoc PEP-noncompliant `@pandera.check_types` runtime type-checking decorator), resolving feature request #227 kindly submitted by @ulfaslakprecis (Ulf Aslak) the Big Boss Typer. @beartype now: * Transparently supports pandera's PEP-noncompliant `@pandera.check_types` decorator for deeply runtime type-checking arbitrary pandas objects. * *Always* performs a rudimentary `O(1)` `isinstance()`-based type-check for each Pandera type hint. Doing so substantially improves usability in common use cases, including: * Callables annotated by one or more pandera type hints that are correctly decorated by @beartype but incorrectly *not* decorated by the pandera-specific `@pandera.check_types` decorator. * (Data)classes annotated by one or more pandera type hints. * Pandera type hints passed as the second argument to statement-level @beartype type-checkers – including: * `beartype.door.is_bearable()`. * `beartype.door.die_if_unbearable()`. * Implements a non-trivial trie data structure to efficiently detect all type hints produced by subscriptable factories in the `pandera.typing` submodule. Let us pretend this never happened, @ulfaslakprecis. * **PEP 484- and 585-compliant generator constraints.** This release relaxes prior constraints erroneously imposed by @beartype prohibiting both asynchronous and synchronous generator callables from being annotated as returning unsubscripted standard abstract base classes (ABCs) defined by the `collections.abc` module. Now, @beartype permits: * Asynchronous generator callables to be annotated as returning the unsubscripted `collections.abc.AsyncGenerator` type. * Synchronous generator callables to be annotated as returning the unsubscripted `collections.abc.Generator` type. * **PEP 591** (i.e., `typing.Final[...]` type hints), partially resolving issue #223 kindly submitted by the acronym known only as @JWCS (Jude). @beartype now trivially reduces *all* `typing.Final[{hint}]` type hints to merely `{hint}` (e.g., `typing.Final[int]` to `int`). In other words, @beartype no longer raises exceptions when confronted with final type hints and instead at least tries to do the right thing. This still isn't *quite* what everyone wants @beartype to do here; ideally, @beartype should also raise exceptions on detecting attempts to redefine instance and class variables annotated as `Final[...]`. Doing so is *definitely* feasible and exactly what @beartype should *eventually* do – but also non-trivial, because whatever @beartype *eventually* does needs to preserve compatibility with all implementations of the `@dataclass` decorator across all versions of Python now and forever. Cue that head-throbbing migraine. It's comin'! Oh, I can feel it! * **PEP 647** (i.e., `typing.TypeGuard[...] type hints`), resolving feature request #221 kindly submitted by Google X researcher extraordinaire @patrick-kidger. @beartype now trivially reduces *all* `typing.TypeGuard[...]` type hints to the builtin `bool` type. ## Compatibility Improved * **PEP 3119.** @beartype now detects both **non-isinstanceable classes** (i.e., classes whose metaclasses define PEP 3119-compliant `__instancecheck__()` dunder methods unconditionally raising `TypeError` exceptions) and **non-issubclassable classes** (i.e., classes whose metaclasses define PEP 3119-compliant `__subclasscheck__()` dunder methods unconditionally raising `TypeError` exceptions) more narrowly for safety, resolving issue #220 kindly submitted by *ex*traordinary Google X researcher @patrick-kidger (Patrick Kidger). Notably, @beartype now *only* accepts `TypeError` exceptions as connoting non-isinstanceability and non-issubclassability. Previously, @beartype broadly treated any class raising any exception whatsoever when passed as the second parameter to `isinstance()` and `issubclass()` as non-isinstanceable and non-issubclassable. Sadly, doing so erroneously raises false positives for isinstanceable and issubclassable metaclasses that have yet to be fully "initialized" at the early time the `@beartype` decorator performs this detection. ## Features Added * **Pseudo-callable monkey-patching support.** `@beartype` now supports **pseudo-callables** (i.e., otherwise uncallable objects masquerading as callable by defining the `__call__()` dunder method), resolving feature request #211 kindly submitted by Google X typing guru @patrick-kidger (Patrick Kidger). When passed a pseudo-callable whose `__call__()` method is annotated by one or more type hints, `@beartype` runtime type-checks that method in the standard way. ## Documentation Revised * **Literally everything,** also known as the release that migrated `README.rst` -> [Read the Docs (RtD)](https://beartype.readthedocs.io), resolving both issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell) and ancient issue #8 kindly submitted by @felix-hilden (AKA the Finnish computer vision art genius that really made all of this possible). Readable documentation slowly emerges from the primordial soup of @beartype's shameless past for which we cannot be blamed. @leycec was young and "spirited" back then. Specifically, this release: * Coerces our prior monolithic slab of unreadable `README.rst` documentation into a website graciously hosted by Read the Docs (RtD) subdividing that prior documentation into well-structured pages, resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). * Documents *most* previously undocumented public APIs in the @beartype codebase. Although a handful of public APIs remain undocumented (notably, the `beartype.peps` submodule), these undocumented APIs are assumed to either be sufficiently unpopular or non-useful to warrant investing additional scarce resources here. * Updates our installation instructions to note @beartype's recent availability as official packages in the official package repositories of various Linux distributions. Truly, this can only be the final mark of pride. These include: * Gentoo Linux's Portage tree. * Arch Linux's Arch User Repository (AUR). * Improves the Python code sample embedded in the ["Are We on the Worst Timeline?" subsection of our **Beartype Errors** chapter](https://beartype.readthedocs.io/en/latest/api_roar/#are-we-on-the-worst-timeline). Thanks to @JWCS for their related pull request (PR) #210, which strongly inspired this bald-faced improvement to the usability of our `beartype.typing` API. * Circumvents multiple long-standing upstream issues in the PyData Sphinx theme regarding empty left sidebars via the requisite `_templates/sidebar-nav-bs.html` template hack shamelessly copy-pasted into literally *every* project requiring this theme. This includes @beartype, because why not spew boilerplate that nobody understands everywhere? Sadly, doing so requires pinning to a maximum obsolete version of this theme that will surely die soon. And this is why I facepalm. These issues include: * pydata/pydata-sphinx-theme#90. * pydata/pydata-sphinx-theme#221. * pydata/pydata-sphinx-theme#1181. * Truncates our `README.rst` documentation to a placeholder stub that just directs everyone to RtD instead. * Improves `linecache` integration commentary. Specifically, a pull request by @faangbait (AKA the little-known third member of Daft Punk) improves internal commentary in our private `beartype._util.func.utilfuncmake.make_func()` factory function responsible for dynamically synthesizing new in-memory functions on-the-fly. Our suspicious usage of `None` as the second item of tuples added as values to the standard `linecache.cache` global dictionary has now been documented. Thanks so much for this stupendous contribution, @faangbait! ## Tests Improved * **Mypy integration.** This release improves our `test_pep561_mypy()` integration test to intentionally ignore unhelpful non-fatal warnings improperly emitted by mypy (which encourage usage of `typing_extensions`, oddly enough). * **Sphinx integration.** This release resolves multiple intersecting issues involving integration testing of Sphinx + @beartype, including: * `test_beartype_in_sphinx()` h0tfix is h0t. This release generalizes our test-specific `test_beartype_in_sphinx()` integration test to support arbitrary versions of Sphinx, resolving issue #209 kindly submitted by @danigm the sun-loving Málaga resident who frolics in the sea that Canadians everywhere are openly jealous of. Specifically, this release fundamentally refactors this integration test to fork a new Python interpreter as a subprocess of the current `pytest` process running the `sphinx-build` command. * A Python 3.7-specific failure in our continuous integration (CI) workflow caused by Sphinx attempting to call deprecated functionality of the third-party `pkg_resources` package. This release simply avoids installing Sphinx entirely under Python 3.7; although admittedly crude, it's unclear how else @beartype could possibly resolve this. Since Python 3.7 has almost hit its official End-Of-Life (EOL) and thus increasingly poses a security concern, this is hardly the worst resolution ever. Really! Believe what we're saying. Break nothing! It's the @beartype way. This is why @leycec cries like a mewling cat with no milk. (*Thrilling chills spill towards an untoward ontology!*)

leycec changed the title ~~Cannot install due to package description size.~~ [Installation] @beartype's description is so big it hurts. Jan 18, 2023

leycec mentioned this issue Feb 15, 2023

[ENH] Allow setting the startdepth parameter for the left sidebar pydata/pydata-sphinx-theme#1181

Open

leycec closed this as completed Mar 4, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Installation] @beartype's description is so big it hurts. #203

[Installation] @beartype's description is so big it hurts. #203

LittleBigGene commented Jan 9, 2023

leycec commented Jan 18, 2023 •

edited

LittleBigGene commented Jan 18, 2023

leycec commented Jan 19, 2023 •

edited

langfield commented Jan 19, 2023

leycec commented Jan 20, 2023 •

edited

leycec commented Jan 20, 2023 •

edited

leycec commented Jan 20, 2023

leycec commented Jan 20, 2023

leycec commented Mar 4, 2023

[Installation] @beartype's description is so big it hurts. #203

[Installation] @beartype's description is so big it hurts. #203

Comments

LittleBigGene commented Jan 9, 2023

leycec commented Jan 18, 2023 • edited

LittleBigGene commented Jan 18, 2023

leycec commented Jan 19, 2023 • edited

langfield commented Jan 19, 2023

leycec commented Jan 20, 2023 • edited

leycec commented Jan 20, 2023 • edited

leycec commented Jan 20, 2023

leycec commented Jan 20, 2023

leycec commented Mar 4, 2023

leycec commented Jan 18, 2023 •

edited

leycec commented Jan 19, 2023 •

edited

leycec commented Jan 20, 2023 •

edited

leycec commented Jan 20, 2023 •

edited