Help @beartype help numerary

[leycec]

Greetings and salacious salutations, fellow wayward traveller on the congested superhighway of questionable human experience. Per beartype/beartype#84, I'd love to promote numeric health in downstream code by elevating numerary above lesser and baser alternatives for type-checking numbers with @beartype.

Python numbers are a fathomless well of squalid darkness. I need you to man the lonely walls with me. I have no idea what I do. You do. Together, let us bring light to the dank codebases that think accepting a bool as an int is good API practice.

Consider this hypothetical FAQ entry with your keen hawk eye:

How do I type-check numbers...?

tl;dr: Prefer the third-party numerary package unless you have a compelling reason not to (e.g., you either don't want to add an additional mandatory runtime dependency to your Jenga-like app stack or you do but one of the use cases below already provides a tighter fit).

"Numbers" means many things to many people. Some people think booleans are numbers. Technically, these people are not wrong. Pragmatically, these people are wrong. ^{Don't hire these people.}

Stop! Disambiguate and listen. You really want to type-check...

...builtin numeric types covariantly?

You want to type-check int, float, or complex numbers including instances of subclasses of those types? O frabjous day! This is the trivial case, because beartype already does exactly what you want out-of-the-box.

Just annotate with any builtin numeric type as is: e.g.,

@beartype
def fawlty_towers(rare_diseases: int) -> int:
    return rare_diseases ^ 0xDEADBEEF

Be forewarned that any bool is also an int and thus satisfies the above API. If you don't want that, ^{spoiler alert: you don't want that} the next question is your codebase's BFFL.

...builtin numeric types invariantly?

Something, something, something. I got exhausted and fell down onto the bed in a dishevelled heap here. This is the toll that type-checking numbers takes on the unprepared body, @posita.

Don't let this happen to you.

[leycec]

Diversionary trainwreck alert: you have implemented something suspiciously fast and dangerously beautiful with the homegrown private caching protocol API (HPCPAPI) that is the beating heart of numerary. Would incorporating that API directly into beartype itself be feasible?

Here is what I am cogitating. typing.Protocol is slower than good ol' Southern molasses. beartype.typing.Protocol is currently just a trivial alias for typing.Protocol and thus also slower than that foodstuff. beartype.typing.Protocol doesn't need to be a trivial alias, however; in theory, beartype.typing.Protocol could be redefined to be your HPCPAPI. Every problem is now solved. Structural subtyping is now genuinely usable.

There's a caveat. If caching dramatically increases space complexity for downstream consumers in unexpected ways, the userbase will abandon @beartype after doxxing me on 4chan. That's bad. You've probably already tackled this concern (...maybe with an internal LRU cache?). If so, I have no remaining concerns and (with your generous permission and all the glory attributed directly to you as I abase myself before your complex throne of head-spinning protocols) will shortly assimilate your HPCPAPI into beartype.typing.Protocol. That's good.

[posita]

SUBSTANTIAL EDIT WARNING: My prior comment(s) responsive to #7 (comment) have been migrated to #8 (comment).

Yes, even with the prominent "diversionary trainwreck alert" I still could not stop myself from focusing on the shiny object. Cleaning up the debris now, and keeping this on track in the spirit of the OP, which I am still digesting….

But, before I forget:

Stop! Disambiguate and listen.

🧊🧊👶

[posita]

Oh! I may have misread your #7 (comment) as a true diversion to the original post rather than a supplement to it. I think the original issue may have been inviting a conversation around how broadly useful numerary's exclusionary mechanisms were, and could those be moved to beartype (i.e., the heart of my "What about manual overrides?" question from #8 (comment)). If that's true, forgive me. I'm slow, but I'll get there eventually. (And apologies for bifurcating discussions, perhaps unnecessarily.) Maybe I should close #8 as a dup and migrate all my comments back here? EDIT: I think this issue is about a proposed beartype FAQ that would advertise numerary. I think #8 is about porting the core caching mechanism from numerary to beartype. If I got that right, my apologies for being so slow.

FWIW, I have do have thoughts on this. There are pitfalls and asymmetries (as I'm sure will come as no shock to you), but we can dig into those gritty details and see if I can be of any help to beartype at any layer.

Buuut… to get to the heart of one of your main side questions: numerary does not limit its cache size. 😳 Working a further embarrassment (if such a thing was possible), numerary doesn't access/update its cache in a [edit: deliberately] thread-safe way. 😳😬😞 Perhaps those deficiencies should be addressed…. 🤔 EDIT: Discussions ongoing in #8 and likely soon to happen in beartype/beartype#86.

[posita]

SUBSTANTIAL EDIT WARNING: Additional discussion topics moved to #8, since I now understand this issue is about a FAQ entry.

[posita]

Regarding a FAQ entry, I like it. Thought: Maybe we should see where #8 and beartype/beartype#86 takes us first, and then figure out what (if any) messaging around numerary is helpful to beartype customers. It may end up largely in the same spot, but one never knows…. I'm open to the idea that numerary is largely superfluous to beartype's critical use cases. Heck, I'd like it if it was superfluous everywhere! (I appreciate the willingness to advertise on its behalf, though!)

[leycec]

Actually, let's temporarily set aside this whole help @beartype help numerary (help @beartype help numerary (he–Recursion Error: Left hand helping the right hand blew up the known universe, because the two hands were in fact the same hand. deal.

Why? Because I have a more pertinent question first:

Would you like to become an official @beartype collaborator with all of the rights, privaleges, and unsettling potential for codebase abuse that entails?

You're the first I've asked and likely to be the first I ever ask¹, because my fundamental position on the rabble at the gates is: "Smile widely first. Sic Main Coon cat with frothing mouth foam later."

^{1. Within the expected lifetime of my wheezing 10-year-old desktop that even Gentoo Linux now looks askance at with arms akimbo, a Fry squint, and the log statement "This is fine." repeated 42 times in its startup dmesg.}

Your spate of high-velocity, hard-hitting, roundhouse-kicking pull requests both here and against friggin' CPython itself have confirmed deep-seated suspicions that you and you alone hold the unthinkable power of Greyskull. Also, I now consider you a GHBFFL. We see eye-to-eye. ^{←zomg don't click that suspicious link at work i'm dying with laughter here as the cat's staring me down}

Should you choose to accept this impossible mission, I'd just like to reassure everyone in the waiting room that this might even be painless. You shouldn't feel a thing aside from the expected eruption of bedsores. You don't have to actually do anything, either. All I ask is that, if you have anything plus-sized and/or questionable to commit, you reluctantly route your changeset through the PR workflow so that Spen can capably dissect it with his disconcertingly self-aware neural net first.

Should you choose to reject this impossible mission (...because impossible), I'd also like to reassure everyone that this offer is available for an unlimited time should you ever reconsider.

Lastly, whatever you choose, thanks so much for everything you've already done. I really appreciate the effusive outpouring of support – and so will @beartype's vast and amoeba-like userbase after I finally do something and drop the beartype 0.10.0 bomb for great justice.

This bear emoji's for you. 🧔

[posita]

I am humbled and touched. I accept your terms and will honor and respect the intent with which they are offered. I solemnly pinky swear to tread if not lightly then at least respectfully and in the spirit of the Ursine Creator.

❤️ Love the bear emoji and am now debating whether to intentionally grow back my beard.¹ (It happens accidentally all the time.) Also, I am stealing the term "GHBFFL".

And thank you (for some definition of "thank you" 🤣) for that video. (The whole duet-with-oneself-in-chromatically-opposing-suits thing was a nice touch.) I am glad (for some definition of "glad") that I made the extra effort to look up the lyrics. (Worth it, and not just for the superfluous apostrophes!) Rest assured, that one's making the rounds. 😏

---

¹ As I'm sure you'll appreciate, the wife has veto power, and properly so.

[leycec]

I accept your terms...

Wondrous day. Your posh invitation has now been shipped and should arrive shortly by bearded gnome carrier to an e-mail inbox adjacent to you. Because I should never be let anywhere near administrative access controls, I've elected to add you as a full-blown member of the @beartype organization. Oh, yes. It's happening.

I'm mostly unclear as to the distinction between GitHub members and outside collaborators. Luckily, so is everyone else. Once you accept the holy sacrament of the Bear Clan and are fully vested as a bearded bear bro, the incorrigible GitHub UI suggests:

• You'll be able to provision your own @beartype repositories and teams! I beseech you to publicly beg me first before you cross either Rubicon, because I frankly have no idea what a GitHub team even is. That said, I'm almost certainly down with whatever you're down with. Rejoice, for bearlynumerate can now be an official thing! ^...heh.
• I might need to additionally grant you push access to the main beartype/beartype repository. If this is the case, I'll giddily push that red button while twirling the handlebars of my luxurious manstache.

I made the extra effort to look up the lyrics.

zomg this cannot be

MAKE LOVE WITH EYE TO EYE

YOUR FACE AND GLORIOUS EYE'S I' CAN SEE WITH MY SPECTRUM EYE'S

STYLISH EXCELLENT HUMAN'S EYE'S

SUBSTANTIAL LOVE IS HEAVEN FOR PRECISE EYE'S.

My glorious spectrum eye's see your stylish excellent human's eye's and raise you substantial precise eye's.

[posita]

✋😔 I solemnly swear not to manipulate any GH administrative primitives without first securing your informed consent.¹

As an aside, I think GH "Teams" are kind of like user groups, so you probably don't need to consider them until you amass a threshold number of professionals keeping the Beartype Ecosystem humming in full force, including future synergistic endeavors I know you can't wait to tackle, like the Beartype Whatsapp Plugin, the BearCoin eCommerce Marketplace Solutions Network, the Beartype Marketing Insights Platform, the Beartype Workflow Management Engine, and the entire Bear2Bear Collaborative Logistics Facilitation Product Suite and related Consulting Services. But for now, yeah, GH Teams are probably best left to the side as an unnecessary complication.

---

¹ "But wait, Matt, isn't all consent informed? I mean how can you consent to something without understanding what you're consenting to? Isn't that the primary pillar behind establishing an 'age of consent', namely that young persons lack capacity to understand what they're getting into?" Sadly, the legal standard for consent in many situations does not mean that one is actually informed, just that one has the opportunity to have been informed. In practice, this means you can easily nudge someone into legally consenting really, really easily without them ever understanding it until it's too late.

Yay. 😒

So, no. The "informed" is tragically not redundant, but it is the standard I will strive for in this relationship. 😊

[leycec]

You may now caper with glee. Ursula Horribilis, the munificent bear deity of the North ("Praise be to Her Bloody Muzzle."), has now granted you direct write access to the main beartype/beartype repository.

...the Beartype Whatsapp Plugin, the BearCoin eCommerce Marketplace Solutions Network, the Beartype Marketing Insights Platform, the Beartype Workflow Management Engine, and the entire Bear2Bear Collaborative Logistics Facilitation Product Suite and related Consulting Services.

I sense a man so hip-deep in Enterprise-Grade DevOps Solution Stacks that he now thinks in capital letters. Also, I guffawed continuously – much to the dismay of our insomniac Main Coon that insistently watches me pound sand into random keyboard keys all evening in the hopes of divining a causal motive behind her master's madness. You'll never understand me, elongated furball with claws! Never!

Lastly, "Bear2Bear." Srsly. "Bear2Bear," people. B2B's right out. That only leaves Be2Be as our marketable trending buzzword. I already feel the looming TED talks. They're crawling up my red and sweaty neck like so many susurrating beetles, chittering as they feast on the very fabric that sustains me.

^{Welp, that intensified fast.}

In practice, this means you can easily nudge someone into legally consenting really, really easily without them ever understanding it until it's too late.

You're depressing me over here. This is like every upvoted thread on /r/OffMyChest, except I've never heard of that subreddit and would absolutely never, ever frequent it even if I had. I can only surmise that the current top thread there might have a title that reads:

"My roommate and all his coworkers drank out of my pee cup. I never told him."

Informed consent: where were you when we needed you?

[leycec]

@posita: I summon thee with a flourish of my wand (AKA, a half-rotted knobbly branch I found outside and now call "Ron Stickamy"). To no one's surprise, I never did author the FAQ entry imagined above. Nonetheless, I have unrelated questions for you:

• Would you like to host numerary under the @beartype organization? I suspect you might be kinda tired of open-source and more inclined to just (DM|GM) away these dismal winter days, but... if you were so inclined, I'd be delighted to have numerary live at https://github.com/beartype/numerary. This would give numerary a bit of a visibility boost, which it so richly deserves. Karma and upvotes will be yours! Oh, yeeees.
• Would you like to be my next-of-GitHub-kin? Basically, I have an autoimmune disease that will probably eventually kill me – just like it did my Dad. I sigh. Since my continued existence is by no means certain, I'd like to designate someone I deeply trust as my "GitHub inheritor." Obviously, no obligation whatsoever should you accept. I don't quite know why I implicitly trust you, but I do; I mean, you're clearly awesome. Clearly. But it's more than that. You're... innately good. And not just the "Lawful Good"-style of innately good, which is the worst possible kind. I'm talkin' real, honest-to-goodness goodness. I've learned to trust these weird but strong assumptions my wife calls "intuitive downloads." Let's do that here.

Lastly, hope you're doin' awesome! Late-stage capitalism is the endless grind I wish I could free all humans from. Sadly, we all labour in quietude and make our fitful peace with moneyed interests as best we can. Despite that, I hope you and your family are enjoying a warm yet fun winter. Wherever life may find you, grasp it by the 2D6 and roll! 🎲 🎲

[posita]

@leycec, please accept my apologies for my inability to prioritize anything beyond the basic staples of family life. Better late than never¹, right? Although, upon reflection, given the gravity of the request, you and beartype deserved better. I am a bad mother, but I am learning to be good.

Regarding your first request, I am totally cool with borgtype—er, I mean—beartype absorbing numerary, as long as we have an open an honest discussion about what we're getting into. To be clear, numerary doesn't fix the real problem of Python lacking true generics. It provides a sad, insufficient work-around for very specific cases. I have been reluctant to spend more time on that for reasons too numerous and boring to enumerate here, but carrying that torch forward remains a fantasy back-burner project of mine that I hope to return to in earnest one of these [plural periodic time unit].

Now that we've dispensed with the easy part—and speaking of open and honest discussions—I turn to your second (and more sober) request. Let me start by acknowledging it for the honor it is. I am sincerely humbled by it. (And, quite frankly, inspired to try to live up to the ideal gathered in your view of me.) Before I accept, I'd like to know more. Assuming it's not too invasive, perhaps we could do that in a more personal setting? Maybe via ZoomFace or TeleSignal or whatever the kids use these days, or maybe just a good old fashioned phone call?

---

¹ Not legal advice. Important exceptions apply, like drinking spoiled milk or getting stabbed. Please apply common sense or consult an adult to help you if you are unsure.

[leycec]

I am totally cool with borgtype—er, I mean—beartype absorbing numerary

🥳

When you find a precious spare moment in between meaningful family interactions that will sculpt and mould the brightest child minds of the 21st Century into the future saviours of our race, it'd be super-swell if you could follow these six simple doomsday instructions to transfer numerary to the @beartype organization.

I solemnly promise to immediately appoint you sole maintainer and proprietor of the newly transferred beartype/numerary project. I may not even need to do that, since you're already an anointed member of the @beartype fold. Trust in the growling bear and you shall bath in golden honey on the morrow. 🍯 🛀

To be clear, numerary doesn't fix the real problem of Python lacking true generics.

Fantastic! That's perfect, because you just synopsized the @beartype Way: pretend you're fixing something that can't actually be fixed, but do it quietly and cleverly enough so that nobody notices the actual difference.

After all, everything in Python is really just legerdemain, prestidigitation, smoke, mirrors, and five elephants on the back of a giant snake. There's very little that's actually built into the language itself. The core language is really just a small handful of types implemented in C purely for efficiency reasons. Unsurprisingly, those types don't work particularly well. They don't scale. They're still too slow, despite being implemented in C. They mostly can't even be subclassed or weakly referenced. The entire field of AI is built on the back of ignoring those types by replacing them with third-party stand-ins that actually do work like NumPy, SymPy, JAX, and [ insert API-of-the-Day here, ChatGPT! ].

The prior paragraph now means that CPython devs are raising GoFundMe funds to raze @leycec's cottage into a charnal pool of ash and tear-stained cinders. Do it, CPython devs! The insurance payout only feeds @beartype and makes it stronger.

But my unsubstantiated point that is almost certainly wrong still stands. The 99.99% of Python that is not hardcoded at the C layer (i.e., what everyone thinks of as "Python") is obfuscatory and non-trivial hand-waving to usefully generate the illusion of a working programming language.

That's all keyboard jockeys like us ever trade in: illusions. That's all @beartype is, too: we can't actually perform full-blown linear-time O(n) runtime type-checking, because we can't do that without destroying performance. All we can do is fake it until we make it. We pretend that we can make informed decisions from randomly sampled data. Like everything in Python, this is just a lie and therefore shouldn't work. Like everything in Python, this is just a convincing lie and therefore works.

@beartype invites numerary to frantically wave its hands around in a confident manner while ominous smoke issues forth from the nearest fissure. 👋 🌋 👋

It provides a sad, insufficient work-around for very specific cases.

You're too humble. I love that. Since I myself lack this trait, your humility humbles and then shames me. Deep down, however, your subconscious self that awakens only during lucid dreaming, astral projection, and remote viewing ^{...just kidding! ...totally not kidding} to solve everything you suffered through in the prior day suspects that your work is actually phenomenal.

@beartype invites you to accept that this is the case.

...I'd like to know more.

Knowledge is a good idea. Sadly, I too am ignorant. I think GitHub inheritorship means that GitHub would automatically assign you ownership over my @leycec account on my untimely demise. (There may be a perverse incentive there.)

Thankfully, that's probably two decades away... probably. My wife's a published biophysicist. I blindly obey the scientific protocol she developed after trawling through reams of unreadable and extremely boring peer-reviewed metastudies on my behalf. In return, I continue living. I feel that this is a fair trade. Smiley cat agrees. You'd better, smiley cat! 😸

Important exceptions apply, like drinking spoiled milk or getting stabbed.

Childhood flashback intensifies.

[posita]

'Tis done. I probably need your help setting up collaborator permissions, secrets, etc., but numerary is now officially part of the beartype ecosystem. My condolences, beartype. Thanks for takin' one for the team.

✊🐻

[leycec]

So proud of all you've accomplished. numerary is such h0tness.

I've immediately escalated you to Administrator! As a thunderous roar fills the pungent air, you have regained all the powers you once had. Ravens caw; trees tremble; fissures open; the Earth herself groans tremulously; mystical energy cascades through the fey leylines of the Old Ways. Arise, numerary! Thy time has come.

</ahem>

I'll publicly push numerary as the only type-checking solution for scalar numerics that anyone should consider in the changelog for @beartype's next stable release. Sample text:

Everyone, use numerary or fail type-checks. The choice is yours. But is that really a choice?

Press F for FAQ

Relatedly, @beartype now actually has a real ReadTheDocs-hosted documentation site. I've finally sucked the venom out of the rattlesnake! Sphinx hurts, but surely the pain will end soon.

If you ever find a spare minute lying around somewhere, it would be wondrous if you could doctor up a new FAQ entry synopsizing how to type-check scalar numerics. It's non-trivial stuff and you are the domain expert I defer to. Something like:

• First, just use int | float.
• When that fails to scale, generalize to numbers.Integral.
• When that's too slow (or otherwise bad), generalize to numerary.{insert-fast-protocol}.
• Maybe also namedrop beartype.typing.Supports(Int|Float|...) protocols, too?

I'm desperate. Don't worry about a PR, unless you really want to. Throw the text up anywhere and I'll giddily use it. I'll take anything: Markdown, MyST, reStructuredText (rST), lewd ASCII art. You name it! If it's ASCII art, please feature a bear rolling dice. This is all I ask.