test: Add test cases for utiltextmunge

[Heliotrop3]

This PR looks to resolve the issue of not having unit tests for utiltextmunge.py. I ended up adding basic unit tests for all functions in utiltextmunge.py.

I'd specifically like to draw your attention to this section. As per the comment, I am unsure whether this is a worth-while test. Given it's a 1:1 copy of the function's return statement it's given to fail should the function ever change. That being said, it's unsurprisingly also the most compact way of producing the expected result...

Slipped into this PR is also the resolution of a smaller refactoring item for utiltextrepr.py

[leycec]

Thor above, but you are phenomenal. You're so phenomenal, you're a coding phenomenon that deserves his own weather system and ZIP code.

Thank you sooo much for tackling this! I only belatedly just realized that the critical replace_str_substrs() function we slaved over like the dwarves of Durin in the eldritch barrows of Moria, Gandalf rest their buried souls, was completely untested. I think I need a hanky now. 🤧

Abject apologies on the delay, too. Precipitous matters such as an unplayed video game backlog that grows ever more ponderously unbalanced (like a Jenga tower you've been meticulously erecting for hours until that one roommate topples drunkenly onto the boardgame table at 4:12AM) consumed the whole weekend, which I'll shamefully own up to.

[leycec]

Importing from pytest is guaranteed to succeed or your scarce volunteer hours back. So, from pytest import raises is safe from module scope – because it better be. Of course, there's also no harm in unconditionally isolating all imports to tests. It's mostly a matter of style and I have none.

[Heliotrop3]

...Of course, there's also no harm in unconditionally isolating all imports to tests. It's mostly a matter of style and I have none.

Definitely thought it was a style thing. Is there any objections to pulling the pytest import into the module scope across all tests?

[leycec]

Nope. Do what they wilt shall be the whole of the law under beartype. So... that's fine. Bears rule, salmon drool! 🐻 🐟

[leycec]

Hooyah! The classic x == x unit test. Quality assurance professionals who get paid lavish sums of untaxed bitcoin tumbled through St. Petersburg probably have a term for this sort of thing. x == x is a better synopsis than that term.

As you'd expect, x == x is bad – but possibly not for the reasons you'd expect. x == x is bad because it couples tests to the code being tested. In software architecture, coupling is usually bad because it increases the fragility of the two components being coupled. This is why semantic versioning and RESTful APIs are trending topics that I pretend to know things about.

In this case, x == x couples this test to the number_lines() function. That's bad, because every time we change the number_lines() function (e.g., by changing the line numbering format to '[line {:0>4d}]') we also break the test.

The solution is to decouple the test from the code its testing. Before we do that, let's take a step back from the ugly precipice of QA despair and contemplate the existential point of this whole exercise. What exactly are we trying to achieve here beyond making us both even balder?

We're trying to test that the number_lines() function vaguely behaves like we expect it to. We are not trying to test that this function exactly behaves as its implementation defines it to. We don't particularly care how this (or any other test-worthy) function exactly behaves – only that this function vaguely obeys expectations, including such lofty expectations befitting our collective genius as:

• This function should return a new string containing the same number of newlines as in the original string.
• Each line of this new string should be prefixed somewhere, somehow, in some format that we really don't care about with that line's line number.

With respect to strings, the easiest, sanest, and most robust way to test vague expectations is with regular expressions. What could be vaguer than an inscrutable symbolic metalanguage we all wish would just be replaced by Parser Expression Grammars (PEGs) already?

Here's how we might assert those expectations, if you were my twisted doppelganger Nega Leycec (also known as Dark Leycec):

from re import search

NEWLINES_COUNT = 20
CATCHY_JINGLE = 'bears, beats, battlestar galactica'
mad_fat_rhymes = f'{CATCHY_JINGLE}\n' * NEWLINES_COUNT
mad_fat_rhymes_numbered = number_lines(mad_fat_rhymes)

# Assert this function preserves newlines as is.
assert mad_fat_rhymes_numbered.count('\n') == NEWLINES_COUNT

# Assert this function prefixes lines by line numbers.
mad_fat_rhymes_numbered_lines = mad_fat_rhymes_numbered.splitlines()
for line_number in range(NEWLINES_COUNT):
    assert search(
        fr'\b{line_number + 1}\b.*\b{CATCHY_JINGLE}\b',
        mad_fat_rhymes_numbered_lines[line_number]
    ) is not None

Everything above is thoroughly untested. Expect catastrophic explosions in the sky, but don't worry! You have iodine tablets for just such an emergency... don't you? ^{Godzilla roars.}

[Heliotrop3]

With respect to strings, the easiest, sanest, and most robust way to test vague expectations is with regular expressions. What could be vaguer than an inscrutable symbolic metalanguage we all wish would just be replaced by Parser Expression Grammars (PEGs) already?

Interestingly enough, PEP 617 is about transitioning the C-Python parser to PEG

Here's how we might assert those expectations, if you were my twisted doppelganger Nega Leycec (also known as Dark Leycec):

from re import search

NEWLINES_COUNT = 20
CATCHY_JINGLE = 'bears, beats, battlestar galactica'
mad_fat_rhymes = f'{CATCHY_JINGLE}\n' * NEWLINES_COUNT
mad_fat_rhymes_numbered = number_lines(mad_fat_rhymes)

# Assert this function preserves newlines as is.
assert mad_fat_rhymes_numbered.count('\n') == NEWLINES_COUNT

# Assert this function prefixes lines by line numbers.
mad_fat_rhymes_numbered_lines = mad_fat_rhymes_numbered.splitlines()
for line_number in range(NEWLINES_COUNT):
    assert search(
        fr'\b{line_number + 1}\b.*\b{CATCHY_JINGLE}\b',
        mad_fat_rhymes_numbered_lines[line_number]
    ) is not None

Everything above is thoroughly untested. Expect catastrophic explosions in the sky, but don't worry! You have iodine tablets for just such an emergency... don't you? Godzilla roars.

I'll play around with this within the next couple of days - your insight was/is very much appreciated!

[leycec]

Interestingly enough, PEP 617 is about transitioning the C-Python parser to PEG

So much excitement. I think they've already successfully transitioned CPython from LL(1) to PEG for the most recent 3.9.0 release. I also think Guido himself made a surprise comeback for that one. Go, go, CPython! Welcome to the 21st century, fellows.

I'll play around with this within the next couple of days - your insight was/is very much appreciated!

No worries whatsoever. Your dedication to the cause of code justice continues to amaze, Tyler.

I humbly appreciate whatever scraps of after-work time you can occasionally throw our way. Meanwhile, I'll be banging on our newly reported non-compliance with PEP 561. Woopsie. 💢

[leycec]

Derp. I feel just awful for letting this linger. This is already more than sufficient as is. You've done a tremendous job here despite a high-paying day job that squanders your vast creative talents and predilection for explosive exponential growth.

I meant to merge this as is tonight and patch in my assorted sordid commentary as a subsequent commit, because we're now in the danger zone of accidentally breaking this PR with unrelated changes, which would upset my fragile emotional balance and make me feel even awfuller. Instead, I finalized PEP 561 compliance for Haren.

"So it goes," as a gutsy guy named Vonnegut said.

So, I promise you this: I will merge this on Monday evening or die trying. I hope for the former.

[Heliotrop3]

Derp. I feel just awful for letting this linger. This is already more than sufficient as is.

I think the last commit should make these test cases sufficient.

I meant to merge this as is tonight and patch in my assorted sordid commentary as a subsequent commit...

I'm glad you didn't! The work on the test cases was trivial, I just needed to find the time to sit down and be productive with respect to Beartype.

because we're now in the danger zone of accidentally breaking this PR with unrelated changes

Oh no! 😱

which would upset my fragile emotional balance...

Here here. I don't like taking a week to resolve PR requests - especially when they are arguably trivial - however weeks can get crazy

I would draw your attention to how I handled the decoupling the test for line numbers. Specifically, it's not testing for the actual line number - which could be in a variety of formats - rather it's testing the base string isn't at the start of the line but is at the end of the line. In other words, testing to see if there is SOMETHING before but nothing after the base string.

[leycec]

Bravissimo! Fortissimo! And other untranslatable Italian exclamations ending in -issimo! Janky English translation: It's in.

Thanks everything and then some for this immaculate reconception of your original changeset. I mean, that one was great too – but this one is for the revisionist history books that make you question everything you previously thought to be true.