Python Bytes - #361 Proper way to comment your code!

Episode Date: November 21, 2023

Topics covered in this episode: The many shapes and sizes of keyboards appeal - a CLI framework from Larry Hastings Graphinate: Data to Graphs A Disorganized List of Maintainer Tasks Extras Joke See the full show notes for this episode on the website at pythonbytes.fm/361

Hello and welcome to Python Bytes, where we deliver Python news and headlines directly to your earbuds. This is episode 361, recorded November 21st, and I am Brian Ocken. And I am Michael Kennedy. And this episode is brought to you by Scout APM. Thank you, Scout. Listen to their portion later in the episode. If you'd like to connect to the show or with one of us, we're all on Fostodon, on Mastodon. So we're at mkennedy, at Ocken and at Python Bytes. And if you'd like to join the show and watch it live or comment in the chat while we're recording, check out, check us out at pythonbytes.fm slash live

and be part of the audience. Yeah, it's fun to have people be part of the audience. Not required, certainly not intended to be required, but fun to have them there. Yeah. What do you got for us first? Oh, well, very excited to be back together on the Eve of Turkey day, the Turkey Eve. So happy Turkey Eve by the Eve of Turkey Eve, Eve, Eve squared through Eve. I don't know how this multiplies together. Let's start talking about something snarky, a.k.a. Brett Cannon. So Brett Cannon did a nice write-up here about different keyboards.

And Brian, I know you're a fan of ergonomic keyboards. I am definitely a fan of the ergonomic keyboards, having had serious RSI issues at one point in my career. And basically, if I on like a laptop keyboard for a week, I'd have to quit. I mean, quit my job. Like I'd be done. It's like that bad, right?

I'm not making it up. Like the Carvel Tunnel stuff is real. But with the right keyboard, I can literally type 10 hours a day, no problem at all. So choosing a keyboard is something I wish I'd paid more attention to when I was younger, but is super, super important. And Brett had his knife dried up on it. So that's what I'm going to cover today. Cool. So basically he says, look, here's what I care about. I have

a bunch of different concerns, right? So, you know, for him, it was more his back that was causing him problems, but he was looking to get a fully split keyboard. He went from something kind of like my keyboard, which I'll give a shout out to in a second, to a completely split, which means the keyboard, the left, the part your left hand touches and the part your right hand touches are not attached, at least not physically, maybe through a wire just so they communicate. So, well, okay, how do we go? It talks about all the considerations, all the things that he cares about, and then goes through like a nice long list of things, right?

Yeah. What is he used before? Uh, the requirements are fully must be fully split because he's using ergonomic one. That's not fully split now. And like, this is his goal. It must tent as in it must like from the two edges, the middle must raise up and down. So like, like if you rotate your hands, um, I don't know, like this without moving your arms at all, you just like left or right, like a clock, um, that kind of rotation wants some portability. Interestingly, uh, aesthetically pleasing to his wife. Cause it has to be a visible and somewhat programmable. Okay. So I don't want to go through his whole article.

I just want to kind of give a shout out to a bunch of different keyboards and you'll get your thoughts as well. Okay. Okay. First of all, he says, Hey, look, I'm using, I think he was using, or at least was considering and like put it into the category of the Microsoft surface ergonomic keyboard. That's a fine looking little keyboard right there. Yeah.

It's like a full size keyboard or a hundred percent keyboard where it has the numbers and all of that. The numpad thing, in addition to the numbers on the top, of course, it's fixed tented, I guess you would call it, it's got a really good curve to it, but the curve you can't adjust, you can like lean it. So the starting point where like your arms start to touch is higher than the other one, if you want and so on. But I actually got this when it first came out. Maybe something's changed.

But when this first came out, I'm like, oh, this looks great. I'm going to give this a try as an alternative to the one that I use. And you know what? Unbelievably, even though it's Bluetooth, it doesn't work on macOS at all. So if you want to use this and you're using Windows, it looks pretty cool. If you're not using Windows, it's kind of more like paperweight than it is a keyboard.

Maybe something about this has changed. But I mean, I took it when Microsoft had Microsoft stores, like Apple stores, I took it back and I said, guys, I bought this. I can't seem to make it work on my MacBook. Can you? And they're like, oh, yeah, sure, of course it does. I'm like, all right, here we go.

Let's see. No, no, they couldn't get it to work either. See, I thought I've tried one. I thought I tried one on a Mac a couple of years ago. Possible, possible. I use the Microsoft Sculpt Ergonomic, which is not the Microsoft Sculpt Surface Ergonomic. Oh, this is the one I tried.

And that works everywhere. Yes, that works everywhere yes that works everywhere that works over and it's smaller and it's lighter and i think it's actually better across the board having had both this one is fine the surface one new new this one doesn't work okay so um another one he said like some people really like the apple magic keyboard which is like more art less functionality you know it's very standard for Apple hardware, you know, saving them, put the Macs and iPhones stuff aside. But like the accessories, it's like, can we just make it beautiful? I don't care if it's the most

uncomfortable thing you've ever touched, like the magic mouse or anything. This is like, I want carpal tunnel next week. I don't have it now. How can I get it? Let's try this. So I don't necessarily recommend that. And then it starts going through like the real ergonomic ones that people might consider. Starting with the Advantage 2 keyboard from Kinesis. And this is one of the weirder, more different ones. This is what I got. This is what I've been using for decades.

Okay, describe this for people. It's just... Because it's unusual. Well, it seems unusual. it's it's it seems unusual in a bad way but it's it's a split keyboard where you've got uh like basically divots where your fingers go because your because your fingers are like you know they're not flat like a keyboard they're curved around so this it's like if somebody dug a hole for the keys yeah matches matches the way your fingers move and then then because when programming, we do things like hit escape and all sorts of other stuff

and enter and backspace and home and all that stuff all the time. Instead of having your pinkies do that work, they put those keys in the middle so your thumbs can do it. Yeah. And I really love that. And one of the first things I do is because I'm a VI user or Vim user is I map one of those middle ones to escape because, yeah, it's programmable too. So it's nice.

Yeah, that's one of the big, as you start to explore these, one of the big areas is like, what does your thumbs do versus, you know, not just spacebar, but your thumbs become way more active. Yeah. And by programmable, I don't mean that you have to like write a program for it. I mean, it's just key sequence you can say, I want to remap this key to this other place, and it's pretty easy. Yeah, absolutely. All right, so that was one that was on the list of considerations. We'll see how many more of these you've experienced. So we have the Moonlander Mark I.

I've wanted to try that. It looks great. It's nice and lit up. It's, it's quite cool. It's looks like it almost has like a track, those little nipple things that come on the, um, think pads, like where there's like a, it's not a ball,

but it's like a stick. That's like a, like a joystick for the mouse almost. Yeah. Yeah. This one looks pretty interesting. It's lit up. You can think program it,

but this one's quite cool. It's fully split and it's got these little bars for the tenting. So you can adjust how side to side it's bent, which is pretty neat, I think. What do you think about this one? I'd like to use that. But one of the interesting bits is the middle keys are just blank because you can map whatever you want to them. And a bunch of other blank ones. I'd rather have some replacement ones because I'm really not going to remember how i mapped them

uh just got a sharpie i'm sharp i guess yeah and no kidding no kidding um yeah but yeah the other thing that i really that uh i think about a lot is like these keys look like they have a long up and down like key throw, like the travel of the key seems high and the travel of the keys on the sculpt ergonomic one is incredibly small, like probably less than on a MacBook. And so like you could just barely move your fingers and your typing. And some of these it's like the mechanical style of like, you know, lots of hand movement, not fan of it, but that's. I like mechanical.

Yeah. In theory I do. All right. Another one is the Kinesis gaming. Since you're a fan of Kinesis, have you looked at this thing? No, it's flat. You could know you can tilt it. No, but it's doesn't have the divots.

Oh, I see. I see. Gotcha. I know what you mean. It has no holes dug for the keys. Yeah. Yeah. This is pretty interesting. You can like tinted a lot, but it is kind of just like a, if you want the

least weird keyboard, but you want to separate it. Right. So you can get like the right orientation of your wrists and stuff without causing trouble. This is a pretty good, we've got the Diagma Raze, which is also, I haven't heard of this one quite in a while. Yeah. It's, it's similar to the gaming one i think it's a little bit neater it looks like it has like pretty far key throw but it clicks together and then it clicks apart so that's kind of something you might people might care about nice magnets to mess up your phone with you that you set next to it exactly there's the ergo docks easy which is another one lots of adjustabilityability on how it's oriented and things, which is kind of cool.

Very thumb-friendly, but no markings for the programmability. So you're going to have to need a white Sharpie for this one. Yeah. Yeah. Looks fun. The ultimate hacking keyboard was Barry Warsaw recommended this one. It comes with a built-in trackball-looking thing in the middle for one of your thumbs. Yeah. Okay. Yeah.

Okay. And notice also it has the QWERTY. See, as Hoppet says QWERTY, like for a display, so you can switch it into different modes like Dvorak. Okay. Liz out in the audience says, I'm a fan of Dvorak. Yeah. Pretty cool.

Yeah. And then we have the Advantage 360 keyboard. That's on my want list. How's this different than the one that you have already? Well, it's have already well it's it's split so it's it's it oh like it's a fully fully split one and it where's yeah the advantage two is actually connected together but this one's split and it's spread apart um got it and it can tent yes it definitely looks like a content and the one that he actually went more i believe went for is the digma defy so you

can defy your limits with this one which looks pretty genius well it's kind of so intimate you can hardly see a picture of it but uh links up for all these in the show notes but this one like this one is thumb heavy brian look at how many options your thumb gets to play with there oh i like it yeah yeah yeah so apparently this one takes a little while to get but anyway i wanted to go through this cause I know there's a lot of people out there who might, even if he decided on this one, this is the one he decided on now next month, you'll order another one. I'm sure. think honestly someone who's like had hand issues don't skip on keyboards don't just think well it's weird so i'm not gonna try it like honestly it's worth not doing something that's just square that is your laptop yeah also stand up and walk around and shake yourself out once in a while exactly we'll get a chair that just every so often like the chair just springs you over in the back and flings you out and so it encourages you to get up before that happens it's actually one of the things i like about the apple watch it says like hey you should

stand up um i know it's usually great except for when you're like in an airplane like you should get up and walk around like you know what i'm in the middle seat i don't think i'm going to right now yeah thanks apple watch make me feel even more stuck where i am all right well that's it for my first item what you got okay, I want to talk about a command line interface tool. So I just, a couple of things. I just wrote a blog post about testing command line interfaces,

particularly arg parse. I should put a link in that in the extras. But also I was covering that when I was recording the PyTest course talking about testing command line interfaces. So I tried a few. I went back and tried Qlik. I tried ArcParse.

And somebody, I'm sorry, I forget who recommended this, is a, there's a new thing called Appeal, A-P-P-E-A-L. And it's by Larry Hastings. And I'm like, oh, it's probably pretty cool. And it's got a great logo, like old retro, I don't know, like the 60s or something like that. Anyway, so one of the things about it is it's just really small. It doesn't have a whole bunch of boilerplate.

So for instance, a hello world, you just import it, create an app and do app command around it. And it just picks up that, like say your hello function has a name to it. So it, the name is going to be an argument that you have to pass in. So that's neat. And then I'm like, okay, well, how about more complex things? Well, things like, oh, things like optional stuff, like default values, like, let's say I pass in a file name, like F grep, you're

going to pass in a file name. But it's optional. So you just say equals none, you just do type hints. So you're just saying that this is the command. But or that F grep is the command, but that it takes a pattern and an optional file name. And it you tell it it's optional by just saying equals none. So using type hints more, I know that like typer was using type hints, but it still has typer still has kind of a lot of boilerplate that you have to do. And so this is a very minimal, minimal API to get things done. And I'm pretty excited to try it. Also look at the contributors. So there's not, there's only five contributors, but it's Larry Hastings, Hugo, Brett Cannon, Hinnick, and I don't know Peter, but wow, already.

Yeah. Pretty cool. Yeah, that's pretty cool. It looks very interesting. So anyway. Nice and simple. Nice and simple for command line interfaces. Worth a look.

Okay. Do you know what else is worth a look? Mm-hmm. I would like to tell everybody about Scout APM. So thank you, Scout APM, for sponsoring this episode. Are you tired of spending hours trying to find the root cause of issues impacting performance? Then you owe it to yourself to check out our sponsor this week, Scout APM. Scout APM is a leading Python application performance monitoring tool

that helps you identify and solve performance abnormalities faster and easier. Scout APM ties bottlenecks such as memory leaks, slow database queries, background jobs, the dreaded N plus one queries problem common with ORMs and more directly to source code so you can spend less time debugging and more time building. You'll love Scout because it's built for developers by developers. Scout makes it easy to get up and deliver insights in less than four minutes. Seriously, you could pause this episode, set up Scout, and be back at it without missing a beat. And probably be back by the jokes, so that'd be cool. Start your free trial and get instant insights today. Visit pythonbytes.fm slash scout.

Please use this link because it truly supports the show. Thank you, Scout APM, for supporting Pythonbytes.fm slash scout. Please use this link because it truly supports the show. Thank you, Scout APM, for supporting Python Bytes. Indeed. Thank you, Scout. Very cool product. I'm going to shine a little light on something that hasn't got a ton of light on it yet, Brian. Okay. Something called graphinate.

That is the verb of to make a thing a graph, I guess. It is also a noun, the name of this project. Yeah, so this one comes to us from, one second, Aran Rivlis. And this is a project, it's Graphinate, is a Python library that aims to simplify the creation of graphed data structures from just pure data sources. So probably the best way to get a sense of this is just look at some examples. So we go down. It's badge. It's GitHub.

Read me badge game is strong, by the way. Yeah. Wow. Yeah. So if we go down a little bit, you can see some examples. Like here is a visualization of a Python python ast that looks a little bit like an advanced molecule based on benzene but like a bunch of stuff coming off of it i guess like a hexagonal thing in the middle it's kind of cool and then here's a relationship of some repositories

and dependencies on github very cool here's web page links visualized. Those are all nice visualizations, right? Yeah. That's beautiful. Looks like Dandelion fluff all connected together. Yeah, you can almost blow on it and take out a whole segment of the internet. Yeah. And so the way to make this happen, if you go back up here,

is you write a generator that defines the edges. So however you might iterate over your data source, I suppose you could even use like recursion and with yield from and all sorts of things to like go through hierarchical data models and whatnot. So you just write a function called, here he calls it edge. It doesn't have to be called edge.

You just give it a decorator called edge and whatever. And then you just say graph.materialize and create a model, create edge, and whatever. And then you just say graph dot materialize, create a model, create this function, boom, and then you get those pictures. That's pretty cool. Yeah, it is. It's pretty cool. So anyway, I thought there's must be a lot of people that want to have these graph databases. And Mike Fiedler says, graphs, not charts, important distinction there. indeed. Yeah. So if you're doing graph type of work, even cyclical graphs seem to be supported, as you can see for a benzene example.

Not really benzene. AST example. So yeah, people can check that out. I think this is pretty neat. Benzene. You're such a nerd. I know. I love chemistry.

That's pretty cool. Indeed. So short and sweet, but there it is. Yeah. Okay. Last topic I want to talk about. Do you know who David Lord is? I have heard of him.

Does he do stuff with the web? I think he does. Yeah. So David Lord is, he's the lead maintainer of Flask, Jinja, Click, and a bunch of others. He works on a project called Palettes. He's also a psf fellow and as of like just recently he finally has a blog yay david hi anyway um so there's a so thanks david for starting a blog started uh this month but he wrote it wrote this a great

article i thought it's it's just sort of a brain dump dump is called a disorganized list of maintainer tasks. And it's not like maintainers really need to know what all they're doing. But I think people that use open source projects need to know what all maintainers do. And this list is pretty big. Why isn't my feature already added for free? Yeah, no effort from me. That's what I wanted to highlight is next time when you want to ask, when is the next release? Instead, look at the project and see where you can start getting involved. The more help maintainers have, the more they can get done. And I really love this message.

Partly is looking through this list and saying, huh, if there's a project I want to work on, or I'd like to have move faster, what could I help? Like you could help automate the release process, document a manual, the manual process for releases. You might not know that stuff though. So maybe improve the test coverage. I like, like that one. Maybe help update the docs. So one of the, like I, a lot of these things I didn't think about, but they definitely are time consuming. One of them, I'm not going to be able to find it right away. Oh, here it is turning questions and answers into documentation improvements. So when you get questions on on mastodon, or an email or something saying, Hey, how do I do this? That's a great

place to put it in the documentation. But that is work. That's extra things that need done. So it'd be great to like even reach out to a maintainer and say, hey, is there any parts of the documentation that you'd like help with or something like that? So I kind of love this and I'm kind of overwhelmed. My list is not this big, but wow, David, thanks for all your work. But if you look at Flask and GitHub,

there's a little bit of attention on that project, right? Like 65,000 stars, 16,000 forks. That's a high level of maintainer business, right? Yeah. Yep. Yeah, there's a lot going on there. And Click. I've been kind of using Click more also.

So there's a good project. That's right. Yeah, so very cool. It's almost like a good projects that's right yeah so very cool it's almost like a reverse lookup of how can i contribute to open source yeah um and i actually this is not um i think we covered uh like non-code contributors um this is all technical work it's it's not it's not non-technical it's a technical work work to answer questions and filter PRs and things like that. Yeah. All sorts of great things to help out with.

All right. Well, those are our topics for the day. Do you have anything extra for us? I have, I believe, three extras I want to cover real quick. Got a quick glimpse of them there as I was just showing the stars. First of all, in the weird world of marketing, it is Black Friday as of Monday. As of this, yeah. Starting this week. I'm not a big fan of it, but people really appreciate it. I know they wait up for it.

So over at TalkBython Training, we have a different deal this year than we had last year. And there's two cool aspects of it. So I just wanted to give a quick shout out and let people know like, hey, if you're looking to take a course now would be an affordable time to do so. And there's a good cost. So what I'm doing this year is I took five of our most popular courses or most anticipated courses that maybe are not even 100% done, but are almost done, and put them out as early access. So we have Visual Studio Code for the Python developers coming out, which is a really awesome course. I'm just like, how do I change my view?

It's good to do this and that. And what am I doing? How do I make it do that? So this is in early access by Brian Clark and Cecil Phillip. And we'll be out in a little bit. But you can sign up for it now. It's like 2 3rds of the way done. So still lots to get there. Async MongoDB with Beanie and Pil Phillip, and we'll be out in a little bit, but you can sign up for it now. It's like two thirds of the way done. So it still has to get there. Async MongoDB with Beanie and Pydantic up and running with Git, like a more visual, more beginner friendly way to get going

with Git. Effective PyCharm because I love PyCharm and our beginner course. All those are 50% off for the week. So that's our Black Friday. Nice. And the other part is we are taking 10% of the revenue and donating it to the Hidden Genius Project, which trains and mentors black male youth in technology, creation, entrepreneurship, leadership, basically a lot of kids who are in places where they might not see a lot of hope or don't think tech applies to them. And they run even up to like 15 months long, not accelerator that's not exactly fast but like mentorship journeys for them and they've had like 10 000 students and we've done a lot of things at like pycon and whatnot so that's the other half that's pretty cool yeah nice thanks okay uh two more. Python 3.13 Alpha is out. And boy, oh boy, how do you want to push your luck?

Friday, October 13th. So Friday the 13th, we're going to release Python 13 Alpha. No, I'm sure it's fine. I'm sure it's fine. But people can check out the new Alpha. If you want to start seeing what's coming and the new version. I mean, we just got 3.12, but it's now time to move on and start adding features to the alpha. What do you think?

I think that's, sorry, I think that's great. I just was reminded of a couple years ago, one of my kids said that they heard somebody at school say, did you know that this year, Halloween's going to be on Friday the 13th? Maybe a little bit backwards. No, it's not going to be. This is actually a little bit old, but I just realized it was something I listed to talk about and I skipped it. But 3.13 is already underway.

People want to check it out, get going on it. Yeah, we won't cover the new features that they're planning, but maybe we can cover that in an upcoming episode episode yeah we can go that uh you know new features will come alpha one is not the end of features right that's when we get to the beta so that's quite always off yeah more to come yeah all right last thing from my extras is the psf and jet brains have over the last couple years done their done their survey, right? I think JetBrains is, yeah, again. So the Python developer survey for 2023 is now open for the taking, as in take your time, please go there, fill it out, submit your thoughts.

And then in, I don't know what, a couple of months, six months, hopefully quicker than that, we'll get results. Now we can go talk about it, right? But the way we can talk about it is if people take it, take it right brian yes it's pretty cool that it's out already i'm wanting to think about it so i am as well it'd be awesome if it came out while it was still in 2023 so we don't have to like explain i know the results say for 2023 and it's 2024 but it actually applies to the most you know what i mean mean? That kind of, that kind of talk. And, um, Hugo also says alpha three 13, sorry, three, three 13 alpha two is due out today. So I just snuck in under the, this is super outdated news, Michael's deadline.

What gives man? All right. That's it for my extras. Okay. Well, I just have a couple extras. Um, I, uh, this morning I met with the JetBrains and PyCharm team and did a webinar about, do you do enough testing PyTest to the rescue? And it was really fun. It was Paul Everett and Helen Scott, and we had a lot of fun this morning. And we had like 200 people show up, which was great.

And then it's already had 500 views since three hours ago. So nice. That's awesome. It was fun. So check that that out people are wondering if they actually do do enough testing and so they came to check it out well and it's always fun when you're with paul and those guys as well yeah so the focus of this i kind of got some technical stuff especially with the parameterized ids sorry about the nerdiness but the um but the point was trying to get people to realize how easy it is to get starting. I'd like to get people to not be afraid of it. Speaking of PyTest, the PyTest Complete course or the Complete PyTest course is coming along. It's going to be 16

chapters. I've got 11 published already. The 12th is already recorded and the 13th should be recorded soon so i'm definitely on track to getting this done this year um and it's of course it's our all for sale um and i was going to ask you this after recording but do you think it'd be a good idea to black friday sale yeah it might be okay i suspect people would be interested in it okay well i'll probably set up that so if you show up today before i get a chance and it's not there yet i'll probably by tomorrow i'll do have the black friday sale on there yeah put the link in the show notes when you get it set nice all right well that's all of my extras all right brian do you know it's important to comment your code people tell you this right

yeah as long as the comments are right. Yeah, well, sometimes people, that's part of it. Sometimes people can just mess up the comments or, you know, they might be inconsistent or they could just be boring. It could just not attract, like you might leave the function with a hollow sense of this was just, there was no joy here.

You know what I mean? Okay, so here's a image that says the proper way to comment your code. Let me see how I can do. I did study math. So the function is called calculate circle area given, and the parameter is a radius. Okay. And it does what you would expect. But the comment is even more than the function. It says, in mathematical fields where circles weave, with pi's grace, a mystic number we conceive, radiance orbs in their geometric trance, circles area, poets rhythmic dance.

3.14159, our constant true, in pi's embrace, the circle secrets do. Where radius meets its boundless quest, area blooms in geometry's bequest and then it does colon calculate circular it's nice right yeah yeah i love also the the the uh the it's four lines of code and eight lines of comment um and exactly and that's never gonna be wrong uh right i mean that's i think that's our takeaway is be wrong. Right. I mean, that's,

I think that's our takeaway is yes. As long as your comments are just loosely related to the code below it, it's probably not going to be wrong ever. So you're good. And you just want to call this function for the joy of the, yeah, the description. And Peter beans points out indeed,

this is where AI might help you write some code. Oh, gosh. Dear co-pilot thing, write me a poem about this function. That's awesome. I think it could totally do it. That's a great use of AI in chat GPT. And try it now before the entire system explodes and implodes on itself. Exactly.

There's some drama in that world right now. Yeah. More of a shift, like a weird dramatic shift. Anyway, people go check the news. And with that, Brian, I bid you happy poem and haiku writing for your code. I'm more of a limerick man, but you know. Okay. Fair. We can make that happen. All right. and haiku writing for your code. I'm more of a limerick man, but you know. Okay, fair.

We can make that happen. All right. Thanks a lot. And thanks everybody for listening. Thank you for showing up to the live episode and everybody listening later. We love you. Talk to you later. Bye.

Yep. See y'all later. Bye.