Tuesday, March 06, 2018

On the threshold of a journey with a Jedi, a Sphinx, and a Homebrew.

Feels like practice.
It all started some days ago, late at night,
with a comment made by someone on the internet...
"Threshold does not take keyword arguments"
As is often the case when you want to correct
something on the internet,
this comment lead me on a journey
(not one where I sell numpy for 22 million monies,
a different type of journey
involving text editors and compilers,
and lots of failing tests).
Software archeology -- not with Indiana,
but at least there was a Jedi and a Sphinx.

"Relax. Don't worry. And have a homebrew." -- Charlie Papazian

And with a warm brew in hand,
herein begins my tale...

Starting at the end, where all poor stories start,
with the comment I will send "TheBob427" (actual real nick),
right after I publish this blog post... [-1]





Dear TheBob427,

yes, this function doesn't take keyword arguments and you are right
that it's super buggy. However, now after some days of bashing my keyboard,
it should actually work. Additionally it should be slightly less weird.
It was a fun journey. I guess you'll have to wait for the next release to use it.
Which should be here 'soon'. Which in open source minutes is 
approximately the same amount of time as 'when it's done'.

yours sincerely,
illume

ps. you could also use PixelArray.replace instead.



So, I updated the pygame.transform.threshold function, tests and docs [0].
Apart from that function being buggy and super confusing...

It was sort of a test of how we could improve all the pygame functions for pygame 3000.
Whilst it still doesn't follow the new pygame C API yet[1],
I wanted to try a few things like 'new' C99/C11 features
(thanks ffmpeg for tricking MS into dragging their compiler into the 90s),
new docs features (param types, and examples) and such like.

It's quite a bit of C and python test changes,
and took me quite a few days longer than I expected.
Simplifying here. Simplifying there. Simplifying everywhere.

One thing it does now is use sphinx type parameters.
Apart from the docs being improved, tools like
jedi can use them for autocomplete and type inference.

So, now editors like vim, sublime, and vscode can autocomplete with pygame.
(I had to change a few things for the 'odd' but 'cool' pygame
'missing module' imports feature so the type inference worked in jedi [2])

Fancy.

For examples, sphinx can now easily include source code.
So we can include pygame.examples code, or even test cases.
The 'nulledge' python search code search doesn't seem all that good
for many pygame things, and it lacks https. So i'm thinking of dropping
that and manually linking to relevant examples/test code.

Additionally, we can link to github source code, and even
the documentation files themselves. Which is handy for
'edit this'/'fork on github' style buttons.


Feels like practice.



[-1] a comment, https://www.reddit.com/r/pygame/comments/80zyqg/threshold_does_not_take_keyword_arguments/dvae53d/
[0] threshold function pr, https://github.com/pygame/pygame/pull/408
[1] pygame C api issue, https://github.com/pygame/pygame/issues/333
[2] jedi confused with pygame pr, https://github.com/pygame/pygame/pull/413

No comments: