If you maintain projects on places like GitHub, you know that having a classy readme is important
and that maintaining a changelog can be helpful for you and consumers of your project.
It can also be a pain. That's why I'm excited to welcome Ned Batchelder to the show.
He has a lot of tools to help here, as well as some opinions we're looking forward to hearing.
We cover his tools and a bunch of others he and I found along the way.
This is Talk Python to Me, episode 395, recorded Monday, December 5th, 2022.
Welcome to Talk Python to Me, a weekly podcast on Python.
This is your host, Michael Kennedy.
Follow me on Mastodon, where I'm @mkennedy and follow the podcast using @talkpython.
Both on fosstodon.org.
Be careful with impersonating accounts on other instances.
There are many.
Keep up with the show and listen to over seven years of past episodes at talkpython.fm.
We've started streaming most of our episodes live on YouTube.
Subscribe to our YouTube channel over at talkpython.fm/youtube
to get notified about upcoming shows and be part of that episode.
This episode is brought to you by the Local Maximum Podcast over at LocalMaxRadio.com.
And it's brought to you by Sentry.
Don't let those errors go unnoticed.
Use Sentry.
Get started at talkpython.fm/sentry.
Transcripts for this episode are sponsored by Assembly AI,
the API platform for state-of-the-art AI models
that automatically transcribe and understand audio data at a large scale.
To learn more, visit talkpython.fm/assemblyai.
Ned, welcome back to Talk Python to me.
Hey, thanks for having me.
This is always fun.
Yeah.
And it's always a good time to have you on the show.
Got such interesting things to talk about.
I think we've previously spoken about coverage.py, beginners and experts,
and several other things probably if I go back through the old search engine.
I've had many opinions about many things.
Perfect.
Well, we're looking forward to hearing your opinions on...
The title might suggest on the ReadMe,
but I think maybe we've got to expand it to a couple other markdown files,
maybe on a project as well to get the holistic picture.
But basically, we're going to talk about tools and ideas and techniques
for making your project more accessible,
feeling more polished and welcoming to people
when they land on your project on GitHub or GitLab or wherever.
So that'll be fun.
Yeah.
It's an interesting topic too, because as a project maintainer,
there's all this project level automation that goes on,
and there are all these fascinating tools to get parts of it done
in different ways and competing philosophies.
Yeah, absolutely.
I know some of them because I fork different projects,
and then I'll sync it or something,
and it'll say that my automation couldn't run.
I'm like, well, that wasn't my automation, but that's okay.
It's fine if it runs or it doesn't run.
I'm just here to follow.
But before we get into all that,
maybe let's just do a quick recap for those of you,
those listeners out there who don't know you.
Maybe what's the elevator pitch,
and what have you been up to the last six months or so?
So I've been working in the Python world for a very long time.
I don't know, 20 years now or something crazy like that.
But my day job is at edX, which is part of 2U now,
an education tech company.
And I do open source logistics there.
edX.org runs an open source software that we've created called Open edX,
which also runs a couple of thousand other sites.
And my main day job is making sure that that collaboration continues well
between the people inside 2U and the people out in the community.
So it's an interesting dynamic of open source.
But on the side, I also maintain a number of projects,
including coverage.py, which has been going for 18 years now
and is used by a lot of people.
So that's a whole other kind of open source that I do in the Python world.
Yeah.
That's a really rewarding job, right?
It's not optimizing ad clicks or other things like that, right?
It's helping people.
Right.
It's a noble goal.
We're educating the world and we're giving away software to help other people educate the world.
Yeah.
It's really good.
Yeah.
Fantastic.
And, you know, and speaking of open source projects,
I think we might touch on a couple more of yours as we get going.
Yeah.
They tend to multiply somehow.
I haven't learned my lesson yet.
Yeah.
Just got these puppies running everywhere.
I don't know what's going on.
That's right.
Exactly.
They breed.
I don't know when it happens.
They breed.
Exactly.
All right.
Well, let's start off with one.
I don't know if you're familiar with this.
Readme.so.
I don't know what the SO stands for, but I think of this as readme as a service.
Interesting.
Yeah.
Or Stack Overflow.
No, .so isn't Stack Overflow.
I don't know.
I don't know why they chose .so.
I don't either.
The woman who maintains it works at GitHub.
I'm pretty sure.
We're going to find out when I get to the bottom.
But I don't think it has an association with Stack Overflow.
Right.
And usually two letters are country codes.
I don't know what SO stands for.
I don't either.
As a country.
Sorry, .so, folks.
But this place, readme.so, it says, this is the easiest way to create a readme.
Now, before we get into the details of this, maybe we should just talk about, you know,
let me pull up coverage.
Coverage.py on GitHub.
Not to put you on the spot or anything.
I don't mean to do that.
But let's just talk about what kind of stuff should you put on your project.
And like I said, we're going to have to expand a little bit.
Like, for example, there's tags and there's a link and there's should you have releases
shown and other stuff that you might kind of think of what you get when you land on a project.
So maybe start there with kind of how you think about what should be here.
Then we'll talk about some of the tools.
The first thing your readme should do is say what the project is.
And that's sometimes difficult for people to wrap their head around.
And it really gets at one of the fundamental problems of writing almost anything,
which is you have to decide who you're writing for.
And it's hard to know who might show up on your front page of your GitHub project.
And you don't know what they already know.
And so you don't know what you have to tell them.
So it's a little bit tricky to get all that information out there.
But for instance, under about here, it says the code coverage tool for Python,
which was the sort of pithiest, shortest description I could come up with to say,
what is coverage.py?
And I think that covers it pretty well.
I don't try to explain what code coverage is,
because that's a topic you can Google for if you don't know what it is.
But so that covers it.
If you don't know what it is and you don't know you want it,
you might not care about this.
So that's not your audience, right?
Right.
Why are you here if you don't?
Right.
Exactly.
But go ahead and start on your way out the door, please.
Thank you very much.
Right.
Exactly.
Yeah.
By the way, I could use a bunch more stars on coverage.py,
because it's not a JavaScript project and it didn't start on GitHub.
So it's a little low on stars.
Yeah.
But so, yeah, the read me.
So I try to say what it is and then how to get started on it.
And I think those might be the front top two things.
I've got a thing there about Ukraine and badges,
which we're going to get to.
But it's sort of there's the first paragraph there,
coverage.py measures, code coverage,
typically during text execution.
So it tries to give sort of a little bit deeper explanation of it,
what you can run it on, and then getting started.
There's a for enterprise thing there that links off to Tidelift.
But then the getting started tries to be very quick about,
you just want to try it.
Here's some commands you can run to see how it works for you.
Because a lot of people, they just want to get going.
And if you can give them a quick instruction,
then they'll be really happy.
Yeah.
Often four or five lines of code.
Here's how you use my thing.
Do I put a decorator onto a function and it does caching?
Do I await a database call?
Or like, what am I doing with this thing?
Right?
You don't have to be super complicated.
Right.
And sometimes it's not even clear.
Some people forget to mention,
is this thing an application or is it a library?
Like just the big picture.
Like as a developer, you can be so, you know,
in the trenches with your code.
You forget.
People don't know what it is yet.
Like what shape it takes.
Now, my readme is pretty short.
And actually the getting started doesn't show the commands.
It links to the getting start,
the quick start section of the docs.
And the change history links to a separate part of the docs.
So it's actually a pretty short readme.
Some readmes can be very long, a little overwhelming.
You have to scroll past all the getting started to get to the change history.
For instance, I decided to take a different approach,
which was to make it almost like a table of contents
to the places you might want to start in the larger docs.
That is a decision you have to make, right?
Do you try to put enough in there that it's basically standalone in a sense?
Or do you encourage folks to find their way over to a much more holistic sort of place, right?
That's an information architecture problem.
You know, the thing about writing a good readme is it's documentation.
And documentation has challenges all of its own
that most developers haven't been trained in formally.
It's not really their first interest.
It involves thinking about other people,
which let's just say some developers aren't skilled at.
But also the curse of knowledge, right?
Once you know what code coverage is,
you don't feel the need to explain it or set the state.
You're just like, well, we want code coverage.
Of course you do.
And here's the tool, you know, for example.
Yeah.
So it's hard to decide what words to put in there,
how much to say, how to organize it.
Those are all real challenges.
Well, it's quite popular with 7.5 million downloads a week.
Is that what it's up to?
Yeah, that's crazy.
That's what it says, right?
That's kind of insane, right?
And it supports all the versions of Python, even the fast one.
So that's cool.
Well, it's interesting.
So this is a point we might get to later.
So you're looking at the Python versions it supports on the badge.
Yes.
But if you actually read the text, it's actually mentioned,
which goes up, the badge goes up to 3.11.
The text says it goes up to 3.12.
The alpha, yeah.
Alpha 2.
And that's because of how the badges work.
And there's reasons why people don't like badges because of that.
But badges look cool.
So you want the badges in.
What's going on here is that the badges show the status of the latest release on PyPI.
And so they're not in sync with what's in the repo.
And it's kind of a challenge to figure out what you want to do about that, unfortunately.
I do see, though, that you are a believer of badges.
You know, I kind of got into badges.
There's, what do we got on the screen here?
Six rows of badges, which honestly is a bit much.
And I should probably, I mean, it's just kind of a mosaic of green and blue at this point.
And it's kind of hard to get real.
But I'm kind of excited to see that you have a Mastodon badge.
The newest one.
I put a Mastodon badge on there, exactly.
Because that's the new crisis is moving from Twitter to Mastodon.
So I'm finding Mastodon to be a really nice place.
I mean, sort of sidebar for a second.
How are you thinking about this whole Twitter, Mastodon, open source community on social media thing?
Yeah, I'm looking at it as an opportunity to try out Mastodon.
And the thing that's really struck me about Mastodon is how many names of bloggers from 20 years ago I'm seeing again on Mastodon that I had lost track of.
And thinking like, oh yeah, I used to read that guy's blog 20 years ago.
And now we're connected on Mastodon.
And so we're kind of resetting back to a more distributed personal style of communication.
Twitter was great in that everyone was in one place.
So it was kind of easier to find people.
But Mastodon feels a little bit more like old internet.
Yeah.
It feels like open source social media.
I mean, and not just the fact that the underlying code is, but the philosophy of the federation and the different servers and the different smaller groups.
Right.
There's some downsides to it too.
You know, the server I'm on had some downtime while they were like rejiggering all their infrastructure because they suddenly had 30,000 users.
And all right, you know, I can do without, you know, Twitter slash Mastodon for six hours while they figure that out.
And then they're back and we're going.
Yeah.
I'm going to go for a walk or get some work done.
Yeah, exactly.
Awesome.
All right.
Well, that's a cool badge.
We'll come back to badges later.
I think that that sets the stage.
One more thing before we get into some of the tools.
There's places like, I think Tailwind CSS might land in this realm.
It's just too popular to search.
Let's see.
Just the Tailwind CSS, please.
Or I know Poetry.
I can't search for that alone, but Poetry with Python.
If you go to their websites, they've got like a fancy website.
Yes.
You know what I mean?
Yes.
And I see some open source projects like Vue.js maybe is like this, where it's almost like there's a marketing landing page for the project.
And the newer ones, of course, it is.
They'll have like a dark mode button.
And do you, how do you think about this?
When you see this, you're like, oh, I need to do this.
Or is this kind of.
I've never been tempted to build a page like this, partly because I don't think I have the skills to build a page like this.
And the things that I make are aimed at developers.
I mean, you're showing a Poetry page landing page here, which is also aimed at developers.
But I guess my feeling is developers don't need that kind of flash.
Yeah.
And honestly, if people use a different thing because it's flashier, that's okay.
I'm not out to corner the market.
Yeah.
It's not JavaScript code coverage.
It's not JavaScript.
That's right.
But also, I think sometimes it can be a little misleading.
And just to go back to Mastodon for a sec.
So one of the problems that people have with Mastodon is that they have to choose a server.
And that's the first choice they have to make.
And it's a difficult choice because it's an unfamiliar choice.
If you go to joinmastodon.org, it's a flashy site with cartoon elephants and things on it.
And it looks very easy.
But then the first button you have to pick presents you with a choice that's hard.
Here's your thousand choices.
Pick one.
Don't get it wrong.
It might have been less cognitive dissonance if the page looked a little bit harder so that when you got that choice, you knew what you were getting into.
It would kind of ease you into that hard choice.
Yeah.
I can see.
Actually, I hadn't looked at the page in the last few weeks.
They've actually changed it from choose a server to create account, which is good.
Yeah.
Because that feels more like what you're doing is creating an account rather than choosing a server.
But you click create account and you're on the page that says servers.
Yeah.
Oh, well.
They'll smooth that out.
You know, people used to be confused by Twitter.
We figured it out.
Yeah, I know.
But I agree that it's an interesting kind of marketing angle for software, which is a little bit weird.
Right.
But I should say, so coverage.py does have a mascot, which was drawn by my son.
Nice.
So it's got that cute aspect to it, but not the whole page isn't cute.
And actually, you're scrolling it on the screen.
I'm noticing the mascot isn't on the GitHub.
Should I go to the docs?
Page.
Yeah.
If you go to the docs, you'll see the mascot there in the upper left.
Very cute.
Sleepy snake.
Yeah.
So I've got a little bit of that, but that's because I've got a son who can draw like that.
And he made me a mascot.
If he hadn't done that, I wouldn't have anything cute on the-
Covered with a blanket.
Got it.
Yeah.
He's relaxing because he knows his tests are all covering his product and he's sleeping well.
This portion of Talk Python to Me is brought to you by the Local Maximum Podcast.
It's an interesting and technical podcast that dives into trends in technology, stats, and more.
But rather than tell you about it, let's hear from Max and Aaron about their show.
We are now on with Talk Python to Me.
Let's say hi to all the Python fans.
Hi, Python fans.
I'm Max Sklar.
I have actually done a lot with Python myself, so I am a fan of Talk Python.
Do you know Python, Aaron?
I took a course years ago, but I am a little rusty.
We are here today to talk about our podcast, The Local Maximum.
We've been on a roll lately with a new episode every week, and I wanted to share with you what
we've been up to.
Here on The Local Maximum, we tackle subjects in software and technology, topics as diverse
as the philosophy of probability to Elon Musk's next move.
For Talk Python listeners, I want to highlight a couple of recent episodes of The Local Maximum.
In 248, for example, I found out about an open source library that maps the world into hexagons.
And some pentagons.
I had a discussion with an author about games and puzzles, and another on a novel approach
to doing the job search well.
We discussed the ramifications of AI-generated art.
Have we reached peak creativity, or is this just another Local Maximum?
So check out The Local Maximum podcast available on your podcast app.
Okay, well, I think that's at the stage for this conversation pretty well.
Let's talk about ReadMe as a service.
Have you played with this any?
So I haven't played with this.
I tend to be very low tech in the way I approach things.
You know, edit some text files, build some tooling to make the result you want, and get
going.
So this looks like a good way to get started.
Like if you don't know what to do, this looks like a good on-ramp.
So it looks great.
If that's the way you like to approach things, definitely do it.
My philosophy is any way you can get a good ReadMe is a good way to get a good ReadMe.
So if this is going to help people, then I'm all for it.
It's not something you tie into your ReadMe.
It's a web app.
And it looks like one of these marketing page, landing page builders.
So on the left, it's got a bunch of different sections.
Like you can drag them in.
So you drag in the title and description.
You drag in the acknowledgements and fill it out.
And it will create the skeleton markdown.
And then you just take the markdown and run with it.
Right.
But it gives you a lot of structure.
Like, well, here's how a lot of people put their author acknowledgements.
Or here's how they put their example code or FAQ.
If this is...
So I haven't played with it.
But if the output of this is a markdown file that you then own and edit later on,
this is just a sort of a quick start templating thing.
I'm pretty sure that's how it works.
Yeah.
Any way to do it.
I'm personally always a little bit skeptical about new tools that I have to keep in my tool
chain and keep working and hope will remain maintained.
Personally, like low tech approaches.
Like I said, if you...
I have a text file that I can edit.
Great.
I'm all set.
So I like that this tool is a way to get started, but then gives you the text file that you then
own.
Yeah, exactly.
So when you're in a section, you just are working on these various pieces.
It kind of is like a function.
I'm just editing the internal, but it puts it all together in a whole thing and you get
just a raw markdown with a copy button.
And it seems pretty neat to me.
It is neat.
And because some of this stuff can be overwhelming.
I mean, markdown syntax is designed to be as straightforward as possible.
But once you get to badges, which are images with alt text with links, the syntax is no longer
simple and it's hard to remember how to do it.
So having a way to mash a button and have a badge show up on the page.
Great.
Let's do it.
So this was created by Catherine Olsner.
Olster?
Olsner.
And yeah, she works at GitHub.
So that's pretty cool.
But yeah, it's just basically a start from scratch and generate if you don't have a good
example.
So I kind of like that one.
Yeah.
And GitHub, in general, has one of their philosophies is we'll make on ramps for people
to do open source, right?
And like they've got in their documentation and their help, they've got how to use a console,
which isn't their problem to solve.
But they know that people are stuck getting into GitHub if they don't know how to use the
console.
So they're teaching people how to use the console.
They've got choosealicense.com because people don't know how to choose a license and they
need to in order to do open source well.
And so on and so forth.
So I love the on ramps that GitHub has built for these things.
Yeah.
And just the community as well, right?
You know, if you put your time and energy into this, there's a chance that people will
come along, appreciate what you've built and contribute to it as opposed to...
It's a social coding site.
That's their tagline.
Yeah, that definitely is.
They seem to be living up to it.
Okay.
Another one that comes from...
Yeah, this is the other end of the spectrum.
This is the other end.
There's a couple of other ones here.
This is from Hinnick.
This is your fancy project deserves a fancy pants readme based on Hatch or with Hatch.
Right.
Yeah.
So what do you know about this one?
Have you done anything with it?
I looked at this a bit and this looks like I said the other end of the spectrum.
So readme.so is kind of a visual graphical way to get started.
This thing by Hynick Slowak is a templating tool where you can automate the putting together
of your readme from different bits of information from all over your repo.
And it is a little bit overwhelming how much is there.
You look at the examples and you're editing .toml files with five dotted nested sections to get
the right pieces in place.
There we go.
And I totally understand this because I have built tools like this too where I thought,
you're a developer.
You can write me a regex when it comes time to tell me what to do.
So I totally understand this and I need to look more at it because it looks like it solves
some problems that I might be facing myself and my own.
Like if you look at the coverage.py repo, there's a lot of custom tooling to do these sorts of
things.
And if I can find other people's supported tools to do the right things, I would like to
use them.
I mean, like I said, I tend to spawn new side projects when I need tooling, but that's not
a scalable solution to things.
I should use other people's tools more.
They built AF, they built some good ones that are out there.
So here, let me see if I can find a section.
There's a little part.
That's it.
The impressive thing.
So when I first came to this, I thought I haven't heard of this Hatch Fancy PyPI readme
project, but under showcases, the black readme is built using this tool.
And that's fine credential right there that the black project is using it.
Yeah, absolutely.
And you've also...
As well as a bunch of others.
Yeah.
Structlog and JSON schema.
Yeah.
JSON schema.
Yeah.
So maybe I could read this one paragraph and this might give people the sense.
Do you want your PyPI readme to be the project readme, but without badges followed by the
license file and the changelog section only for the latest release?
Well, you've come to the right place.
So it's like...
He's got this whole assembly line model of there's already a bunch of information out
there.
So don't copy it around.
Don't try to write it in two places.
Instead, have a tool, pick up the information and then put it together into the readme, which
is what you want.
And I totally understand that because I've got some...
I've done some of that kind of tooling myself in my projects so that I can put a piece of
information in just one place and then it goes to where it has to go to be read.
It's a bit like a static site generator.
A bit.
A little bit.
The thing I still haven't wrapped my head around here is that what feels like it could
be one template.md file or something that says, you know, grab this from there and that
from there is instead in your PyProject.toml sections.
So you don't end up with sort of what looks like a readme.md file with callouts to where
the information should come from.
It's pieced together from the PyProject.toml sections.
I see.
The toml lets you reach into the different segments of the thing that's there.
Yeah.
And I understand why he's taking that approach because the PyProject.toml is there and this
is a hatch plugin.
So he's already got access to that information and it's bolted into the process of building
the distribution, which is the exact best time to build the readme.
So it's cool that he's explored it this way.
I have to take a deeper look at it to see if it would fit in with my workflow.
I don't use hatch.
Yeah.
Hatch is nice and hatchlane is nice.
And I've done a little bit of work with it.
And I can see why if you're already working in that mode, how to kind of extend it.
Absolutely.
Yeah.
One of the problems with coverage.py, which is my main side project is because it's 18
years old, there are bits of it that are using the latest, greatest technology as of 15 years
ago.
And because it's just kept working, you know, until it breaks, I'm not going to go and fiddle
with it or until I'm interested in fiddling with it, I might fiddle with it.
But there's a lot of stuff that's just old and weird and just keeps rattling along.
For such a highly used project, I can see the danger here.
But have you considered or have you run it through things like Flint to convert all the
strings to fstrings?
Have you or some of these like upgrade to the latest idioms where you can say, I want it to
be 3, 7 and above.
And anything that's older than that, you know, kind of rework it.
I have used pi upgrade on it when I dropped 2.7, which was a couple of years back.
And there are now fstrings all through it.
But for instance, I don't use black.
I there is a pull request to add type annotations to it.
But it's a big project that doesn't not gaining the momentum it needs to get done.
So I tend to, you know, let sleeping dogs lie where it's working.
And or if I don't, I don't know what I'm going to get out of it.
For instance, I use opt parse to parse the command line arguments.
And that wasn't even the right thing to use in 2.7.
That was the old thing that arg parse replaced.
But it still works.
It's still in there.
It's fine.
You know, sometimes there's no value in possibly adding bugs to something that you don't intend
to touch at all.
Right, right.
Exactly.
But maybe if you were to say, like, we're going to really dramatically expand the way
that it can take arguments and do things.
Well, then maybe all of a sudden you are like, we could get more flexibility with a new thing.
But if you're not going to touch it, then just let it be.
Yeah.
All right.
Let's get to the next one here.
Shields.io.
Yes.
If you want a badge, come to the place.
Shields.io, they will make a badge for you.
And this Shields.io is a very impressive service, I have to say, because they give you lots of
ways to make badges, including ways that I didn't even understand they could do.
I found this out when actually when I made that Mastodon badge that you can tell Shields.io
to go and grab some JSON from some other website and extract data from that JSON response and
include it in your badge.
So you just call the Mastodon API, public API to get stuff about your account and pull it.
If you look at my Mastodon badge, which is on GitHub slash Nedbat or on the coverage.py page,
it has my count of followers.
And that's coming from a JSON response from the Mastodon API on my server, on my Mastodon server.
And then Shields.io is incorporating that number into the image that it then serves to GitHub
to display into the readme. I don't want to think about how many computers are actually
involved to get that stupid number on that page. But it's very impressive that I can do all that.
I sure hope it's cash somewhere.
I hope so. I don't know.
How interesting.
Yeah, they've got a bunch of these prebuilt badges that can tell you all sorts of things.
Like, you know, what version of your project is current on PyPI and what Python versions it
supports and what your license is and all sorts of things. It's very impressive.
Yeah, it supports not just Python, but I saw Node.js, Nougat, PowerShell.
Yeah.
Stuff that I don't spend as much time on over here.
Yeah, there's things I've never even heard of that it shows here.
SourceForge.
They don't even document all the things it can do. I mentioned earlier that the badge on the
PyPI page will show the status of the latest PyPI release, which means if you go back 10 years to
the coverage.py, you know, version 3 release, there's a badge on it that shows you that it
supports Python 3.11 because the badge is showing you the most recent release, even though you're
looking at the badge on the 10-year-old release.
Yeah.
There's a syntax in Shields.io that will let you say, show me this factoids as of this particular
release 3.0.
I see.
And they don't document it, so I didn't realize I could do that. So there's an awful lot going
on in Shields.io.
Yeah. So if you want a Shield for one of those little badges for basically anything, these are,
you know, got downloads, users, test coverage, all these things. There's just a...
Right.
Basically, they give you a URL, right, that you put in into your readme, and that becomes the badge
as it resolves, right?
Right. The URL returns you an image with the information on it that you want. Either information
that you put into the URL, you can just make a URL that says, you know, Michael Kennedy is cool,
and it will return to you an image that says Michael Kennedy is cool. So, you know, it'll just format
things for you, but it also has ways of getting information and then formatting it to give back to
you.
Okay. You probably could put this personally onto places, not just on your project.
Right.
But maybe on your GitHub profile, potentially.
Absolutely. Yeah, my GitHub...
Like the social.
I'm embarrassed to talk about how over-automated my GitHub profile page is.
I love it. All right. Shields.io, that's a section for the live badges. This one is hot off
the presses. Let's see if we can find... Oh, it says initial commit. We got it 10 days ago.
Will McGuggan of Rich... Rich and Textual. And Textual, yeah. Put out a tool to generate a GitHub
flavored FAQ.markdown document. This is pretty neat. This is a tool. I just took a quick look at it. It's
in a similar vein that you want to make little bits of information in a convenient way and then have it
published as a monolithic piece of information. In this case, he's talking about FAQ questions. And I think
he said somewhere here, I got tired of answering the same questions over and over, so I made a tool
to make an FAQ or something like that. Yeah. I don't know. I don't have the same problem of needing
FAQs produced or why it's easier to put them all in separate little files that are combined together
later than just editing one big FAQ page. But Will's a smart guy. He must have had a problem and he solved
with this tool and it's cool to see. This is a little more similar to the way you described how
you might see building up the readme. Instead of defining an automo file, reaching into a giant
document, have a bunch of small ones to get assembled into a result here. Right. And that's a lot like some
of the change log management tools that we're going to get to also. Yeah. One of the things that prompted
Will to do this, he says here is people will ask the same question over and over and he in issues and
he's like, you know, I can't, I just can't answer it again. How to make a table. I mean, or can I make it?
So yes, you can make a table. Here's the link, whatever that is. So it has a fuzzy, fuzzy matching
on suggest. So I think this is why it's separate because you can put alias questions to the frequent
question. Yeah. And then you can just on the terminal on the shell, you can say factory suggest.
And if you have some kind of input to it, like I took the question that somebody asked me and I want
to point them at the thing so I can just jam that into the terminal and it'll go actually that matches
over to this FAQ response. I think that's the idea. And he says that it's designed to be used with a
GitHub action to post an automated response on an issue, I guess is the point is that if he's getting
a ton of issues that all need to be answered, instead of saying, go and read the FAQ, he can,
he's automated the process of putting the answer right onto the issue, which is cool. That's,
I didn't realize that aspect of it. So that's very cool. So this is all of 10 days old. People can
check that out if they want. Hot off the presses, torn from today's headlines. Exactly.
This portion of Talk Python To Me is brought to you by Sentry. How would you like to remove a little
stress from your life? Do you worry that users may be encountering errors, slowdowns, or crashes with
your app right now? Would you even know it until they sent you that support email? How much better
would it be to have the error or performance details immediately sent to you, including the call stack
and values of local variables and the active user recorded in the report? With Sentry, this is not only
possible. It's simple. In fact, we use Sentry on all the Talk Python web properties. We've actually fixed a bug
triggered by a user and had the upgrade ready to roll out as we got the support email. That was a great email
to write back. Hey, we already saw your error and have already rolled out the fix. Imagine their surprise.
Surprise and delight your users. Create your Sentry account at talkpython.fm/sentry. And if you sign up with
the code talkpython, all one word, it's good for two free months of Sentry's business plan, which will give
you up to 20 times as many monthly events as well as other features. Create better software, delight your
users, and support the podcast. Visit talkpython.fm/sentry and use the coupon code talkpython.
We talked about contributions and how people appreciate getting credit for participating.
You know, like I'm sure there are people who have closed a small issue or found and fixed a small bug
in coverage.py or added a small feature and feel really proud of that, right? But yeah, they would
feel more proud if you acknowledged that they did it, right? I accept your PR, right? Of course.
So tell us about this all contributors place here. This is a GitHub bot that on an issue,
you can say, you know, add all contributors, add Michael Kennedy to the bug fix sections of the
contributors because he did it right here in this issue that we're talking about. And that's really
cool because I don't use this tool. Like I said, I tend to be very low tech. I do acknowledge my
contributors. I'll mention them in the changelog. And I have a contributors.txt file that lists everyone
who's contributed in some way. And I will hand edit that. And it can be, you know, I have to remember
to put it over there and put it over there. I don't get so many contributions to coverage.py that it's
a burden. And I kind of actually like that little sort of moment of zen of, you know, finishing the
paperwork and crossing the T and dotting the I's. But if you're on a big project where you are getting
a lot of contributions, I could see how doing this with a bot would be, you know, save you that little
bit of work that that could become a big amount of work. And you don't want to skip it, right?
Because like we said, it's seems like a small thing to us and maybe like, I don't want to have
to bother. But it's a huge thing to the contributor to have their name mentioned.
Yes. Yeah.
And maybe not just pride. Maybe they get a job because of it. Right. They could say,
I'm getting hired to work on Flask. Look here. I'm listed as a contributor on Flask.
That puts me above 99% of the other people applying.
That's right.
At least in that regard.
The internet is the kind of place where you don't, when you're, you get a little connection
like that, you never know what it's going to lead to.
Yes.
There's all sorts of things that pop up because of the strangest little mentions.
So true.
You might get invited to be on a podcast just because someone mentioned one of your dopey
little tools on Mastodon.
Or you might even start a podcast.
You might even start a podcast. Yeah. Watch out.
That's right.
There's danger ahead.
And then you're really in for it. So the way that this allcontributors.org bot seems to work,
I don't use it personally because I don't have projects that are big enough to really
justify this in terms of open source projects. But in the comment on an issue or on a PR or
one of those types of things, you can just say at all contributors, please, please add at
GitHub name of contributor. And then it says for design or for bug fixes or for documentation.
And then the dot, the dot, the bot says added them as contributor. That's, that's really cool.
Yeah. So I, like I said, I have a text file. One of the, one of the unusual things I do with my text
file is that when I build for coverage.py, when I build the release, if you go and look at who,
who the author of coverage.py is, it says Ned Batchelder and 137 other people. And that number,
137 is counting the number of lines in the contributors.txt. Cause I want it to be clear
that, yeah, it's not just me. There's lots of people helping with this and you can help too.
Yeah. Especially over 18 years.
Well, yeah.
All right. Getting to the part of expanding beyond just readme.md, but the broader
experience of things that maybe gets, gets their way pulled back into the readme is a changelog.
Yes.
Are you familiar with keepachangelog.com? Have you seen this?
I am very familiar with keepachangelog.com.
All right. Tell people about this.
So keepachangelog is basically an advocacy site that says you should really have a changelog. And
here's what we mean by that. And why should you do it? And I absolutely agree with the idea
of keeping a changelog, which is a running history of what has changed in your project.
And that's because people that your users want to know what's changed. I mean, it sounds really
simple, really basic, but I think people can approach it in really simple ways that aren't
as valuable. And if you put a little bit more work into it, you'll find it's really, really valuable.
And you need to know as a consumer of a library, is there an immediacy to this new version that I
need to pay attention to? Is there a risk to this new version that I should be aware of?
Or do I don't care? And I just leave my thing pinned the way it was before, right? If it says
there is a CVE where if we send the dollar sign, it takes over your server, like you should get in
there straight away.
Yes, exactly.
Exactly.
But if it says we deprecated this thing that you were depending upon, like, well, don't just push it.
We're going to need to think about this.
Right. And I think the way you just described that is really good, which is that the user of the tool,
the library, the application, they want to understand, you know, what's in it for me?
Like from my perspective, what has gone on with this library? And I think that's one of the things
that's difficult for people is for maintainers is to put themselves in their user's shoes and think,
what's changed about this that matters?
Yeah.
There are some auto-generated changelogs that, for instance, just put all the git commit messages
in the changelog. And those drive me nuts because they're telling me all sorts of things that I don't
care about. I don't care that you restyled, changed all the spaces to tabs in some file.
That doesn't matter to me. That's just noise. You're hiding, you're burying the lead by telling
me stuff that doesn't matter. So keep a changelog is a good, like I said, advocacy site. They have
their guiding principles. Change logs are for humans, not machines, things like that. And they
advocate for marking your commits with, or marking your changelogs, putting them into sections of what's
been added, what's been changed, what's been deprecated so that, you know, people can zero in on what
matters, right? Deprecated means I can't use the thing anymore and I need to make a change. And security
means I really better get on this or I might be in trouble. So it's good to highlight those things and
put it into the user's perspective. But I like the guiding principles here about it's
for humans. Every version should have one. The release date should be specified. It's easy to
just say, well, version 2.1 had these changes. Like, well, wait a minute. We're on three. Like,
was that last week or five years ago? I need to know how relevant.
Date things. I mentioned my son doing art. I always told him when he was a kid, put the date on the
picture. So I'll know how old you were when you made the picture and you never wanted to do it.
But change logs, you can put dates on things. Like you said, you don't know how long ago something
was. Yeah. Don't have to go back and diff the thing to figure out when it was committed. Right. All
right. And we've got one chat from a viewer talking about creating change logs, like as a good job for
AI. And these days, I don't know, 2022, not only is, you know, Twitter versus Mastodon, but chat GP,
what's it called? The AI thing? GP3, I think. Yeah. Something like that. Seems to be amazing.
And I can probably retire soon because it's going to do my job, I think. Yeah. And just yell commands,
just yell stuff at the computer from like the couch. Computer, go write the website. Just make it
better. Scale the website, computer. Exactly. Oh yeah. That's a good point. Mario out there says it's
called Skynet. There are some amazing tools, like a bit of a diversion, but there's like this thing
called Jasper that a friend just told me about. And what you do is you write, it's like Google
Copilot for writing content. And there's just, there's a bunch of crazy, crazy things out there.
Yeah. It is. We've seen a complete change in the progression of things and it's astounding.
It is. All right. Well, let's get to one of the first tools that got you recommended. The reason
I invited you is because I asked people for general recommendations and they kept recommending your
tools. I'm like, all right, well, I should just have Ned come on the show to talk about this.
I'll just come in and talk about all of it. Sure. All right. So we, we saw the, keep a change log
ideas, but that's in theory, not in practice, right? Right. To keep a change log just says,
look, you should write this stuff and here's how you should write it. It's not a tool.
It's just encouraging people to do a good job. I looked around at tools when I wanted to get
people to make better change logs. And there was one called town crier from the twisted project.
And they solved the problem that a lot of change logs have. So if you just have a change log file
and everyone who makes a change to the code is supposed to put an entry into the change log file,
then that file becomes a merge conflict every time, right? Because I added a feature. I put my thing at
the top. You added a feature. You put a thing at the top and it's a merge conflict. Years ago at work,
what I tried to do is have a change log file. And I told developers, put your change near the top of
the file in the hopes that they wouldn't merge conflict. And developers would come to me and say,
what do you mean by near the top of the file? Because they're engineers, they need precise directions,
right? So, okay, that wasn't going to work. So the idea that town crier uses, and also the cpython
source code has a thing called blurb that does the same idea, which is when you make a change to the code,
you also write one small file, which has just the entry for the change log in it. And you check that
in. There's a special directory that just has those little fragments in it. And so when you make your
code change, you also add a fragment to that directory. And then later, when it's time to actually
put everything, you know, make a release, all those fragments can be concatenated together to become
the change log. And the good thing about that is that you don't have merge conflicts because everyone
creates their own fragment. They have, you know, unique names based on some principle. And then at
publication time, you know, when the release is made, they can get concatenated together. And like
I said, town crier did this and blurb also did this. I looked at them and they were both a bit more
opinionated than I wanted. I knew that if I was going to get a lot of people to use this thing, that it
needed to be very, very flexible. And I actually took an approach when I was building Scriv of what's the
least opinionated I can be. How many different ways can I let you decide how you want it to work?
At the time, black was rising in its popularity and it was famously opinionated. And so I sort of took
the opposite approach. Nice. Scriv's, the idea is that it's got a few commands. You say Scriv create
to make a fragment, Scriv collect to collect them all together. Those are the two main ones.
Scriv looks like, it looks like a great tool. And it looks like one of these things you could pipx
install because you're not going to, it's unlikely you'll depend upon it for your code to run.
You just need that command around to manage a project.
Right. Or you can put it into your development requirements.txt or however it is you manage
your project tooling. But sure, pipx would work too. And it's actually grown one other command
for making GitHub releases. So it will actually parse your changelog file. Even if your changelog
file wasn't made by Scriv, it will parse your changelog file and then create a GitHub release
from your changelog file, which gets at a philosophical opinionated point of mine, which is that
the information should live in just one place. And that place should be a file that you check
into Git. It should be a file that people can clone when they clone your repo. If they want
to just look at the changelog in Emacs or whatever locally, they should be able to do that. And since
you don't want to duplicate information, but people do seem to like having GitHub releases
make, you know, publish a GitHub release based on the information from the changelog file,
rather than having the release be the source of truth where it can't be cloned. It can't be
edited. It can't be, you know, there's no commits that you can track to see who put that text there,
those sorts of things.
Okay. And that makes a lot of sense. Let's see. Out in the audience, we got in a question.
Last changelog I read was for Python 3.11. Did you read that? Have you read? It's a bit of a novel.
The CPython developers have taken to heart the idea. And I make it sound like this is a recent
development. They've always done this. You know, there's a Python 3.11 has a what's new in 3.11.
And they tend to be very, very detailed about putting stuff in the what's new document. And like
I said, they've got their own custom tool called Blurb, which is how CPython core developers,
they write what are called news entries, which get created as small files in a custom,
in a dedicated directory. And then those get aggregated into the what's new document.
In that changelog, there's 180,000 words. Typical novel is like 80,000. So that's a proper changelog
right there.
There's more information there than any one person needs, but everything that's there,
someone does need.
That's right.
Right.
And each one of those links to like a GitHub issue or a PEP or something like that.
Yeah.
And there's a lot of those. I just noticed, I think it was today that they got GitHub
issued number 100,000 in the CPython.
Wow. Okay. That's major.
Yeah.
It's been chugging along for a while. All right. So this looks like a great idea. What do we
got up next? Oh, I just also wanted to just give credit, speaking of giving credit from
Colin Sullivan, who sent this in amongst some other things as well over on Mastodon. So thanks
for sharing that. This is another one. I'm going to go quick because it's not a Python
tool and it's actually in a technology I've never heard of. Maybe you've heard of it, Ned.
So I hadn't heard of this. So this is called Changelog Manager from Masukomi. And it's
interesting that he, Masukomi, is one of those bloggers from 15 or 20 years ago that I'd lost
track of and suddenly got reconnected to on Mastodon. And when I asked about, I got a little
petulant on Mastodon about a changelog that I found completely useless. And he chimed in
with a long thread about how aggravated he is by changelogs and how hard it is to get people
to do them well and pointed me at this tool that he had written about.
It looks like a cool tool. People can check it out if it works well. It's written in a language
called or technology called Crystal. I feel.
Yeah. I don't know what that is.
Makes me feel old all of a sudden not even know that that's a language. I don't know. But wait,
hey, look, it's Colin's out in the audience. Oh, hey, Colin. Yeah.
Thanks for the recommendation. You got me on here.
Yeah, absolutely. So this is a cool project here and people can check it out. And yeah,
it's got a lot of the philosophy of how you should do it, how you shouldn't just have
commit messages. I remember hearing about tools that would look for swearing and other kinds of
frustration in commit messages and not allow those particular messages to get into the changelog.
But I don't think that, as you pointed out already, that individual commits are generally
the right granularity.
Right. Commits definitely are not. Some of these tools will aggregate your pull requests
to be the changelogs. And that's a little bit better because they're larger grained. But even so,
I think there's real value in hand curating your changelog. Start with a list of pull requests,
but then take a look at it, reorder them so they make some sense and tell the story.
Right. Put the important stuff on top.
Put the important stuff on top. If you have three pull requests, which just by coincidence all changed
how you handle file matching, then make an entry that says, we changed a bunch of things about file
matching and then have sub bullets about the file matching changes. You want to explain things to
people and you're going to be able to do a better job of it than your pull requests or your commit
messages. Absolutely. All right. Well, thanks for that, Colin.
Executable books. The executable books folks are interesting. They've got a lot of tools that will
take Jupyter Notebooks and other things using the MIS plugin for markdown and generate books in
different ways. And so they've got this project called GitHub Activity, which generates a simple
markdown changelog based on that. Let's see. I think this is on issues and PRs, not commits.
Yeah. I think this is one of the ones that goes for the larger chunked bits of information,
which like I said, is good. Commits are too small. The issue is still that when you write a pull
request, what you're writing about mostly is something that your reviewer needs to read.
Right. So you're really addressing your collaborators rather than your users. I mean,
ideally your pull request would include all of the user consequences as well, but it's also going to
talk about what your collaborators need to know. So different audiences, different information at the,
at the very least, it's going to need an editing pass in order to figure out how to actually explain
this to people the right way.
Sure. Well, that's an interesting idea. Maybe the tools don't have to be perfect. Maybe they could say,
well, here are the 10 things in terms of PRs and issues that have changed. Now just rewrite that for
humans with a different audience. That still could be valuable.
Yeah. Collecting up all the information. That's great. I just think it needs, it needs a human
touch.
Yes.
That's controversial in these days of AI, but I think humans can do a good job writing stuff.
Indeed. As we say, get up co-pilot, write me a, no. So the next one we come to is Dinghi?
Dinghy.
Dinghy. Okay. Dinghy. Got it. Just like the little boat thing.
The little boat. That's right.
Okay.
Yeah. So this is a tool that I wrote and it was interesting because when Colin mentioned this
as a tool for changelogs, it didn't, that's not why I wrote Dinghy. Dinghy is designed to give you a
daily digest of GitHub activity, which by the way is why it's called Dinghy because the D-I
stands for digest and there's a G-H in it, which stands for GitHub. And I looked through words that
had those pairs in them and Dinghy popped out.
Nice. And it's got a Y, which is like half a Python for pies.
And it's got, yeah. And then you can, you can backfill the marketing slogan of, you know,
your lifeboat on a sea of information or something like that.
There you go.
Dinghy just gives you a digest of your GitHub activity. I was finding at work that I had to
track lots of issues and pull requests and there were lots of repos where I wanted to know what
was going on. And so I found it useful to just summarize the activity on issues and pull requests
across repos.
This is nice.
Yeah. In the morning, take a look what happened on the last day. Oh, I should, you know, I should dive
deeper into that one. I can click into it and go read the real issue, but you just can get a,
get a quick overview, but I can see how, so I use it sort of on a daily basis, but I could see how
you could take this and get a digest of the last three months and then use that as at least a guide
to where to get the information for a change log. If not, you know, pulling information right off.
It seems real helpful if you work on a team, especially if you're the team lead or kind of a
manager type and you're like, all right, just need to see what's happened on these three projects
this week. Exactly. Just hit it.
That's what it's for. And it's, it's satisfying to hear people think of other uses for it. That's
the sign of having built a useful tool is that I meant it for one thing, but then someone else
sees, oh, I could use it for that too. And that's very gratifying.
I can see it at the end of a sprint, like the sort of post-mortem burn down type of thing.
Yep.
Yeah. Okay. Cool. Cool.
You mentioned blurb. I'll just put a link to, to the blurb project tool as well. This is the
CPython prolific writer. This idea of building the change log from small fragments is something
that's happened a number of times. And I think it's a great idea. I think it's the right way to,
to do this kind of work. Agreed. One that comes, I, is this GitHub itself that does this? No,
there's not. There's a thing called release drafter and it drafts your next release notes
as PRs are merged into a master. Okay. So I haven't used this.
This is another case of things going into GitHub actions. And I'm fascinated by this whole thing,
you know, as a project maintainer, I feel like there's sort of three large buckets of work.
There's the building, the product itself. I don't mean product to sell, but like coverage.py is a
product. There's maintaining the test suite for it, which is if you've got a large test suite is a
whole endeavor all to itself. There's all this project automation, you know, that we've been
talking about here today. You know, how do I get the releases made? I've got a make file,
what this command, how do I, what's, how do I bump the version up? Like all of that kind of,
and it feels like micro automation. You're doing it like one shell command at a time or a 10 little
Python, 10 line Python file or something. And the fact that there are all these tools around
that help with it and put it in GitHub actions. And you just, you make a GitHub,
a Git tag and suddenly it goes to PyPI and publishes the GitHub release and all that.
That's fascinating to me how far you can automate those processes.
They kind of build up like a snowball going downhill pretty quick because you're like,
well, if I could automate this thing and that thing, they're like, wait a minute. Now we just,
they click together and then it's, we're almost there.
I'm a late adopter of technology. I won't automate a thing until I know that it's exactly the way I
want it. And I've gotten completely sick of doing it by hand. But the good news is by then I do know
exactly what I want it to do. And so I can build the automation and I don't have to come back and
fiddle with it too much. Another big benefit I would say to that approach is every time it runs,
it could just warm your heart with a joy. Like I, you know what, I hold another two hours. I didn't do
that thing. That's right. The downside is when it does the wrong thing. So this weekend,
I actually had a big weekend this weekend. I released 1.0 of both Scriv and Dingy and the
first beta of coverage 7.0. And it turns out that the links to PyPI on the readme, no, the links to
my documentation from the PyPI readme are broken because they don't work if it's a beta release.
And I didn't know that until the release was published and betas happen so infrequently,
it'll change again before I make another one. And it'll probably be broken too, because it's hard to
test this kind of automation. Like the good thing about building the product and building your test
suite for the product is that that is automation. You can run the crank on and you know if it's
working or not. Releasing projects, if you build automation for that, how do you test that if release
happened correctly other than actually making a release and then getting bug reports from people
about the 404s on your PyPI page, which is how I found out about this. It's a little frustrating.
For as much fantastic testing software and automation, sometimes you just got to hold your breath and
push the button. And you're not going to write a unit test that says, let's push this thing to
test.pypi.org and see if all the links on the readme are right. That's, I mean, maybe, I guess you could,
but if anyone's done that, please get in touch because I messed that up this weekend.
At some point you got to go, okay, we've tested enough. It's got to go. And even if you write a
unit test, you know, it's not necessarily exactly the same. It's not the same and you'll fiddle with
it and break it. And which is what happened to me. And yeah, absolutely. There'll be another release.
It's fine. There'll be another release. We'll get it fixed. All right. You mentioned Town Crier
already. I think maybe we can just carry on, but people can check that out as well. You know,
I guess give them a quick shout out as well while we're here. This comes from the Twisted project,
you said? Yeah. And Twisted is another of these projects that's been going for a very long time.
So this is a mature tool. It's just a little bit quirky in the way that they wanted to do things.
I think at least when I first looked at it, it was something like the fixes went into a .fix file
and the features went into a .feature file, things like that, which just, and it didn't do markdown.
And I knew that I was going to have people who needed markdown, even though I prefer
restructured text. So I built Scriv to kind of along the same ideas, but in a more flexible way.
Right. Okay. Cool. One of the things you may have in your readme or other parts of your documentation,
your markdown files or restructured text, I suppose, would be example code. Like I talked about that.
It would be nice to know some level of correctness to that, right?
Yes.
We have MKTestDocs. Tell us about this.
This is one of these things that's the interesting thing to me is that you've got docs, you've got tests,
you've got doc strings, and there's all these tools that do all the different pairings of stuff,
right? So you can run tests against the code in your doc strings. This runs pytest against markdown
files that have code in them. So it's running the code in the markdown files. And it's fascinating,
again, to see how all of this automation, this project level automation comes together to try to
close all those little gaps. Like I mentioned the problem of a broken URL on my readme. You could
also have code that you had typed into a markdown file, and it turns out it doesn't work for whatever
reason. Maybe it worked once, something changed. This will run the code in your markdown files so that
you know that it still works, which is great. I'm all for more testing.
Yeah. Well, even if you're not actually trying to execute it, and like I'm asserting that my example
returns seven, because maybe it says connect to a database and do other crazy stuff, it could at least
be syntactically valid.
Yes.
Right. It could look at it and go, I loaded that up and I parsed that function and it didn't die.
That's a start.
Exactly. There's levels of testing. And like you said, it can get very complicated to do full testing of
some kinds of code.
So how do you test your markdown, your readme.md? Well, see, I fire up a series of a cluster of Docker
containers using Docker Compose, and then we can run the one example and then it's good.
If there's a tool out there that launches missiles, I don't want to know how you're testing the code
in your readme.
Yeah. There's another one that is a little bit tough to test. One of the things that's interesting,
by the way, this tool comes from Vincent WormerDem, that it deals with multiple code blocks. So if you
do the language specifier in markdown, so the triple dot back tick, and then you just say the word
Python or JavaScript or C# or whatever, that'll tell the formatters, format it like,
this, right? It's this type of syntax you should see. So if you do the Python one,
it will run those. And it'll also do bash as well, I believe. But what's interesting is you could have
a, like, and here's how you set it up, and then here's how you call it type of series of code blocks.
And it will run all the code blocks, or you can actually say, you know, remember what you saw
before, because that was the first half of what you need to do the second half.
Right. Because you're trying to tell a story. This is like a Jupyter notebook where you're
interspersing code with commentary and then more code, and you need the multiple blocks of code to
all be executed together, or, you know, one after the other. You need the first one's results in the
second one.
I certainly appreciate a don't completely repeat yourself every time in your code example,
right? It would say you get started by importing this, and then you would create a class like this
that it arrives from. You wouldn't want to have to have import, import, import over and over,
right? So yeah, this is cool. I don't use this one either, but it definitely looks like something I
could see adopting. Now here's something called shed, which is not exactly what I want to talk about,
but it's for formatting code. So it runs autoflake, it runs pyupgrade. You mentioned that before,
I believe, for upgrade. You can specify a version, pyupgrade me to Python 3.8, but not further,
please.
Pyupgrade is good.
Yeah. Yeah. It runs black. But what I do want to talk about is it runs black in docs.
Which formats the code in the doc strings and in your docs. Which again, is one of those pairings of,
let's put this tool into that thing and have it do just a little bit.
This is super hard to get just right because you want to format code. And, you know, one of my
markdown editors, if I highlight some code and I hit shift tab to unindent, it'll put everything just to
the left. I'm like, no, no, no, no, this is Python code. It has to have the space. You can't just put
it all the left, like undo one level, right? The things like that, where it's just like, oh, this,
this is not quite formatted, right? Just running this maybe even as a pre commit hook would be
glorious. Just like all of my code in my examples and my triple back tick Python becomes black,
blackened.
Yep. And if you're using black, then you really want it everywhere, right? You've given up control
of the formatting of your code willingly. You see the value of it and you just want it everywhere.
And this is great for getting it into your docs too.
Exactly. Like there's, there's gaps. Maybe your Jupyter notebooks don't have black formatter,
like get it in there, get it into the docs, get it everywhere.
Yeah. Getting to read me. Cool. Okay. let's see this one. Another person gave a shout out to
your next project here. This is Cy Gallimardi said, Hey, we should check out cog.
Yeah. Cog is one of those tools that I wrote very long time ago to do one particular thing.
And it ended up being useful in lots of other ways. Basically cog is a way that you can make a text file
like a readme.md and put little bits of Python in the middle of it. Not because you're trying to
display that code to people, but because you want the results of that code to be part of your document.
A little bit like a, a Jinja, right? A template maybe.
Exactly. But it's a little bit backwards because Jinja starts with the idea. I mean,
Jinja is, well, it is like Jinja actually. I should, I shouldn't say that. It's just like Jinja.
But instead of being HTML, you want it to be text or something, right?
Right. It can be anything you want. Jinja is particular to HTML in some ways,
but cog is completely agnostic. The bigger difference from Jinja with cog is that the output of your code
can go into the document so that you process, you run the document, the output of your code
becomes part of the document. So sort of the input file and the output file are the same file so that
you get sort of an item potent kind of processing of the file. So you can have a readme.md. You run cog
on it. You still just have a readme.md, but now you've got the results of the computation in the file.
So for instance, I use this in the coverage.py docs. There's a database schema for the SQLite data
file that coverage.py writes. That schema is in a string in a Python file someplace, but I also want
it to be in my docs. So I use cog in the restructured text file to go and get the string from the Python
code and splat it into the restructured text file so that I know that the two are the same because
there's one source of truth and an automated process to bring it into the restructured text file.
You know how they say there's like two hard problems in computer science, naming things,
caching validation and off by one errors. Yes. I feel like maybe a fourth one should be
identifying and controlling and keeping the one source of truth.
One source of truth is a big thing with me and all of these kinds of processes where
you want to make it convenient to write information, but you also want to make it convenient to read
information. And so you might want to publish information in more than one place. For instance,
I mentioned that my changelog is in a .rst file, but it also goes into GitHub releases because people
want to read it in GitHub releases. So I get the information out of the changelog and automatically
publish it into GitHub releases. Yeah.
Cog has found a lot of use. Simon Willison has been very positive about Cog. He uses it in a number
of places to keep his documentation up to date. I've used Cog to an extreme extent in my GitHub profile
to, for instance, grab information from PyPI where I mentioned what my projects are and things like
that. Yeah. Yeah. Cog is one of those things that started small and it's just has chugged along for a
long time. And I continue to find more uses for it. Yeah. That's great. Colin says using Cog to document
CLI tools is Chef's Kiss. Yeah. So very nice. Very nice. We're getting to the end here. We're almost out of time, but luckily we're also almost out of things to talk about. Well, we're not out of them. We're stopping.
There's a lot. There's a lot. This is a small sampling. But here's one by Haidang that's awesome tools for the readme profile. So this is a lot of, let's do the test. Click on their profile and see how it looks. You know what I mean?
Yep.
Got to get a little more in there. So this is more of a collection, but we have readme's for projects, but also readme's for humans, right? You know, if you go to my account, you see a particular thing. Some people have really fancied that up with lots of things. And this project here talks about, well, what kind of cool stuff can you put on there that people might see?
I haven't looked at yours recently. What's your profile look like?
So it's not as visual as this. It has a few badges, but I used Cog to, for instance, pull in the six most recent blog posts onto my page. I wanted to do recent tweets, but that was going to be hard because Twitter API wanted me to authenticate. And half the time I turn away when I'm asked to authenticate against the thing, because that's the hardest part of the whole thing. And it takes away all the fun.
The main thing I used Cog for, I used Cog on my readme. And one of the things I did with it was to write Python code to generate that markdown syntax for badges and to put together shields.io badge URLs. So both of those things are complicated, right? Shields.io is amazingly powerful, but how you actually put all the bits of information into the URL is hard to get right. And it's fiddly. There's like ampersands and you have to quote them in the markdown or something.
It's a regular expression, yeah.
Yeah, I mean, it's just too intense. So I wrote Python functions to put together shields.io URLs. And then I called those Python functions from the Cog code in my readme.md. And there's a GitHub action that runs the Cog on it.
Whenever I publish a blog post, my blog publishing triggers the GitHub action that recalcs my GitHub readme. So the latest blog post is on the top of the GitHub readme. Like I said, you can take this a long way. I may have gone too far with this.
Oh, I love it.
But yeah, it's cool to see how the tools can come together and you can automate all of these processes. Again, to go back to one source of truth, my blog is the one source of truth about what are my blog posts. But the information is also on my GitHub readme because I thought that would be a useful thing for people to see when they look for me on GitHub.
Yeah, that's fantastic. All right. So this project here is like a whole host of things like that that you could do. And I love the use of Cog and the GitHub actions just to chain it together.
Awesome tool for readme profile. It's sort of like a blank catalog. Like you might want to put this on your profile or put that on your profile.
If it was 1994 and you wanted a blink tag, here's a whole bunch of or a little animated diggy GIF you could figure out.
So you get these graphs of like what were your last year contributions over time or when are you most likely to?
Yep.
Some more badges. Like here's the latest blog posts, which is a thing that people can pull in if they don't want to do more of it themselves.
Yep.
How much time you spent coding in various languages per month or per week, weekly here. That's pretty wild.
Yeah. He's got a lot of things here, like what you're listening to on Spotify.
Yeah. Do they have emails, one of your coding activities? Cause I spend a lot of time in email and I wish.
Are you typing code in your email? You might be doing it wrong.
I'm just spending a lot of time in email. I wish I didn't.
Okay. So it's got a, what time of the day? Are you a morning person? Are you a,
it has a snake game that goes around and races like a centipede.
You know, you're right. This is very reminiscent of the early, like geo cities kind of internet where
everything flashed and blinked and looked cool and had contrasting colors and stuff like that.
Yeah. So people, I mean, we're only like a third of the way through this game. People can,
they can give themselves trophies. They can give themselves, I think this is stack overflow. Yeah.
Stack overflow reputation.
There's just a ton of different stuff you can put together. And I think it all comes back to,
you know, besides like maybe overdoing with digging animated GIFs and blink tags. I think it comes back
to your GitHub profile is a little bit like your resume and how much can you say more than just,
Oh, I forked Django.
Right. And you want, I mean, the point of the profile is to let people know about you and
hopefully they'll be interested in you in whatever way you want them to be interested. So all of these
things that attract attention and let you can choose something here that sort of has your vibe
in whatever way. For instance, my page is very text heavy, but that's my vibe. That's the way I am.
And if that's not for you, then you should look for someone else's profile. But if you want to know
what I'm listening to on Spotify, then that's a thing to put on a profile page. So it's great. I
mean, self-expression is a wonderful thing. And the fact that GitHub lets you build your own profile
and that there are all these tools to do whatever you want with it. It's amazing.
It is amazing. All right. I think this is probably going to be it for our final thing to cover and
read me and friends. Let's close this out just really quickly with a, give us the, the 7.0 story on
coverage. Oh, coverage on 5.7.0. Yeah. That's a big deal. All right. I mean, if you're going to
make that big of a number, it might not be a big deal. This is a tricky thing. So really what happened
was I was looking through the bugs that people were reporting and a lot of them had to do with,
it couldn't find my source file where I said it should put the source file. And I was answering with,
well, you have to do these tricky things in your configuration file. And I thought maybe that should
be simpler. So really the reason it's a 7.0 is because I made things better, but I also think you
might have to change your settings in order for them to still work the way they used to work.
So when you look at the change log for coverage.py 7.0, there's no like amazing big thing. The biggest
feature change is that when you get a text report out, now it can be in markdown format instead of
in plain text format. And that's cool, but that's not like a 7.0 level feature. The real change is,
I think it's going to be better, but a few of you might have to update your settings. And I wanted to
make it clear to people that that was going to happen. So I bumped the number to 7.0.
That seems totally reasonable and still going strong. It's a beta one right now. When do you foresee
this becoming the pip install coverage sort of version?
That's a great question. I have to admit, to be perfectly honest with you, that I have been
disappointed in the past at how few people try out betas. So I'm putting this out there in a
disciplined way and I'm trying to talk about it, like go and try the beta, but eventually I'm going
to get tired of waiting for people and I'm just going to publish it. And if the bug reports come
in then, then we'll deal with them then because there's only so much you can do to get people's
attention on a beta.
Absolutely. I can totally understand that. All right. Final two questions before you get out of here.
If you're going to write some Python code, what editor are you using these days?
Vim.
Vim. Right on.
And I do not have any code completion plugins.
Okay.
I've said this before. I'm very low tech.
Perfect. And then notable PyPI package. I kind of feel like we've covered a bunch,
but if there anything you want to give a shout out.
We did cover a bunch. You know, I've been very enamored of Rich, I have to say. It's very cool.
I'm looking forward to hearing more about what Textual is going to be for building
terminal UI interfaces for applications. But Rich is astoundingly competent at what it tries to do.
Yeah. And what they're doing on the terminal is just nuts.
It is.
Nuts in a good way.
I only discovered just the other day, maybe people don't know this, that you can,
one of the Rich styles, and this is a feature that terminals support and Rich is just tapping
into it, but it gave a convenient way to do it. You can output text, you know, that's red or that's
bold. You can output text that's a link where the word in the terminal is just, you know, click here
and behind it is the URL you told to have it. And then you can click the link in the terminal
and go and visit things. Astounding.
I'm familiar with terminals detecting links, but not having a different link text than the actual link,
right?
Yes. That's what I'm talking about. I didn't know it could do that.
Yeah. That's nuts.
Yeah. Cool. Well, that's definitely a good one. All right. Final call to action. People are thinking
about their projects. I want to get started with some of these ideas. What do you tell them?
Think about your users. Think about who you're writing for. And it's different people at different
times and write, write words. I actually want to say one more thing. We talk about change logs as being
really good for the users of your library. I find when I sit down to edit my change logs that I
understand my own product better and that I think about the features I've built in a new way and
sometimes actually go back and change them because in the process of trying to describe what happened,
I learned something. Yeah.
Writing for readers is great. Writing, you will learn things when you write. Write more. It'll be good.
I can definitely see that. You're like, I want to say, but it doesn't quite do this unless I change
this other thing in code and then it'll be true to what I tried, wanted to say here. So yeah. Yeah.
Perfect. Yes. All right, Ned. Thanks for coming back on the show. Great to have you here.
It's always fun. Yeah. See ya.
This has been another episode of Talk Python to Me. Thank you to our sponsors. Be sure to check
out what they're offering. It really helps support the show. Listen to the Local Maximum podcast.
Learn about topics as diverse as the philosophy of probability and Elon Musk's next move.
Just search for Local Maximum in your favorite podcast player.
Take some stress out of your life. Get notified immediately about errors and performance issues
in your web or mobile applications with Sentry. Just visit talkpython.fm/sentry and get started
for free. And be sure to use the promo code talkpython, all one word. Want to level up your Python?
We have one of the largest catalogs of Python video courses over at Talk Python.
Our content ranges from true beginners to deeply advanced topics like memory and async. And best
of all, there's not a subscription in sight. Check it out for yourself at training.talkpython.fm.
Be sure to subscribe to the show. Open your favorite podcast app and search for Python. We should be
right at the top. You can also find the iTunes feed at /itunes, the Google Play feed at /play,
and the direct RSS feed at /rss on talkpython.fm. We're live streaming most of our recordings these
days. If you want to be part of the show and have your comments featured on the air, be sure to subscribe
to our YouTube channel at talkpython.fm/youtube. This is your host, Michael Kennedy. Thanks
so much for listening. I really appreciate it. Now get out there and write some Python code.
izepotletcwnc.com