There are many reasons to be concerned about LLMs: job displacement, intellectual property issues, moral hazards. The one I hear the most is the environmental impact.

TL;DR: I think the environmental impact of LLMs is primarily a climate change problem, that the impact of individual LLM use on this problem is relatively small, and that climate change is best addressed through collective action (ideally taxes, subsidies, and regulations). But since systemic solutions aren’t coming soon, understanding the relative impact of specific activities (including LLM use) does matter.

Energy use of individual LLM prompts

When thinking about the energy use of LLMs, I tend to agree with the framing that Hannah Ritchie takes: this is something to be concerned about, but many headlines are misleading.

Hannah Ritchie is a data scientist, deputy editor at Our World in Data, and co-host of the podcast Solving for Climate. In Hannah’s post about the overall energy demand from AI data centers, she notes that data centers in general make up a small fraction of the world’s global electricity demand and that they are estimated to be a fairly small portion of the growth in global electricity use until 2030.

That doesn’t mean that the energy demand from data centers isn’t a problem. But, as she notes, due to the very uneven distribution of data centers around the globe, this is a very localized problem:

What’s crucial here is that the energy demands for AI are very localised. This means there can be severe strain on the grid at a highly localised level, even if the impact on total energy demand is small.

Hannah also has a follow up post on individual LLM use where she suggests that individual users should “stop stressing about the energy and carbon footprint” of LLMs.

In all of these posts, she attempts to put numbers into perspective:

The reason we often think that ChatGPT is an energy guzzler is because of the initial statement: it uses 10 times more energy than a Google search. Even if this is accurate, what’s missing is the context that a Google search uses a really tiny amount of energy. Even 10 times a really tiny number is still tiny.

Hannah also published a follow up to her follow up post where she seriously questions the 3 Wh figure (10 times higher than a Google search) that’s often used when discussing the energy use of LLM queries. She considers whether the median LLM query may use closer to 0.3 Wh of energy.

I lean heavily on Ritchie’s analysis throughout this post because I think her data-oriented framing of this issue is helpful. That said, detailed energy data from AI companies is scarce so her estimates are inherently fuzzy.

Energy use of coding agents

Hannah’s posts about individual LLM usage focuses on the “median query” in an LLM… but using a coding agent (Claude Code, Codex, etc.) to navigate through a repository and generate lots of code likely involves quite a bit more usage than a “median query” does.

Simon P. Couch recently wrote a post about the energy use he estimates for his Claude Code usage. He estimates that his Claude Code usage results in approximately 1,300 Wh of energy each day. That’s quite a bit higher than either 0.3 Wh or 3 Wh for a median LLM query.

If heavy coding agent use results in 1,300 Wh of energy, that represents 3.7% of the average American’s daily electricity use (based on an average electricity generation per person of 12,712 kWh in the US). Increasing your energy use by 4% is not nothing… but how bad is it?

Climate impact of coding agents

Increased energy usage isn’t as concerning to me as the negative impacts that the energy usage might have on the climate.

Going with Adam Masley’s assumptions of 0.37 grams of carbon dioxide emissions per watt-hour (Wh) in the US and the assumption that data centers use energy that’s 48% more carbon intensive than the average US power plant, 1,300 Wh per day of coding agent usage could result in 0.5 grams of CO₂ per Wh, for about 715 grams of CO₂ emissions per day from coding agent use.

The annual carbon footprint of the average American is 16,300 kg of CO₂, which is about 44.7 kg of CO₂ per day. So 715 grams of CO₂ from a day of coding agent usage may be about 1.6% of the average American’s daily carbon footprint of 44.7 kg of CO₂.

Again, 1.6% is not nothing. It’s not enormous but it’s certainly measurable.

I think that any discussion about greenhouse gas emissions should be considered in the context of the rest of life and ideally in context of the social cost of those emissions. I haven’t tried quantifying the social cost, but I have looked up other activities and their climate impact.

For the sake of comparison, here are some very rough estimates of carbon dioxide equivalent emissions (CO₂e) for various consumables and activities:

• one hour of Netflix: 50 grams CO₂e
• a banana: 80 grams CO₂e
• one hour of Zoom: 100 grams CO₂e
• half cup tofu: 300 grams CO₂e
• half cup (dairy) greek yogurt: 400 grams CO₂e
• driving 5 miles in an EV: 500 grams CO₂e
• 5 minute shower: 700 grams CO₂e
• 1 day of using a coding agent: 700 grams CO₂e (based on one user’s estimate)
• driving 5 miles in a gas car: 1,500 grams CO₂e
• beef burger: 5,000 grams CO₂e
• flying SAN to ORD (one-way): 400,000 grams CO₂e

Treat those numbers as “likely correct within an order of magnitude”. Most of those numbers have pretty large error bars, as the industries that have solid data on these figures rarely publish them and even when they do, the actual emissions can vary greatly due to the number of variables involved.

If you’re curious about any specific measurement, compute them based on sources you trust. I recommend Our World in Data: food, streaming video, transportation.

Note that I am not saying “using LLMs is not bad because people eat beef”, which would be whataboutism. But I don’t think that we should discuss the carbon emissions of any given activity in a vacuum.

Water use

I’m going to mostly skip over the water use of LLMs because I find it far less concerning than the energy use. Based on Andy Masley’s numbers (from his provocatively-titled post The AI water issue is fake), a median LLM query uses around 2ml of water including offsite power generation (0.3mL of water if we don’t count power generation). That means that a full day of coding agent use would consume about 6.5 liters of water (0.6 liters for everything but the power generation).

The average American’s daily water footprint is 1,600 liters. So 6.5 liters of water (largely from offsite power generation) represents roughly 0.4% of the average American’s daily water footprint. 90% of that water comes from the water required for power generation because generating electricity from natural gas, coal, and nuclear all requires water.

Like energy use, water use is a very localized issue. Unlike energy use, water use doesn’t also contribute to climate change. Water use is worth discussing, but I find the climate impact of coding agents much more concerning. I’m also not sure how much the local impact of water use should be a concern, since it matters what type of water is used, how much of that water is returned to the source, and what else that water would be used for. Hank Green recently released an interesting video on water use.

Climate change requires collective action

The biggest environmental concern of LLMs is how much they contribute to climate change.

Climate change is a collective action problem. We need to greatly limit greenhouse gas emissions. And in a world of goods with variable market-based prices, a negative externality like greenhouse gas emissions warrants a tax. A carbon tax or a cap and trade program could go very far in accomplishing that, but I’m skeptical that we’ll see either of those happen on a massive international scale (and especially not in the US) anytime soon.

Aside: did you know that the US had an Interagency Working Group on the Social Cost of Greenhouse Gases which published official estimates on the cost of carbon emissions? It was established under Obama, disbanded under Trump, reestablished under Biden, and then disbanded again under Trump. I really wish the US would implement a carbon tax so that we can stop focusing on specific carbon-emitting activities and instead properly price carbon emissions in aggregate.

So why talk about LLMs specifically?

If climate change is best addressed by big picture solutions, like a tax on all greenhouse gas emissions, then why even look into the climate impact of specific activities, like LLM use?

Because we don’t have a carbon tax. And we’re probably not getting one anytime soon.

In the absence of systemic solutions, general sentiment about what’s a big problem and what’s a small problem shapes how we respond… as individuals, in communities, as consumers and workers within companies, and as citizens pressuring various levels of government.

We can’t expect individuals to weigh the climate impact of every action they take (thinking of The Good Place’s S03E11: The Book of Dougs). And hoping that corporations will grow a conscience is wishful thinking. But having a shared understanding of the relative impacts of various climate concerns does have some effect on what gets attention, what gets research, and what gets regulated.

So I think it’s worth understanding the relative impact of different activities, including LLM use. Putting numbers in context helps us have better conversations and direct our collective energy more effectively.

Global and local, individual and collective

There are two angles I see this problem from:

1. The global problem of climate change from greenhouse gas emissions
2. The local impacts caused by data centers

For climate change overall, I think we should:

• Pressure the companies that make LLMs to publish detailed information about carbon emissions
• Pressure our politicians to tax greenhouse gas emissions… or at least to tax activities that result in greenhouse gas emissions in a way that would mimic the outcome of a carbon tax
• Pressure our politicians to subsidize activities that lower greenhouse gas emissions, like increasing solar and battery technology use on the electrical grid
• Talk about climate change and encourage our colleagues and loved ones to talk about it

When it comes to AI data centers, I think focusing on their impacts to local grids makes more sense than focusing on their global impacts. The uneven distribution of data centers makes their local impacts disproportionately large in comparison to their global impacts. I see this as similar to the problem of pig farms. Eastern North Carolina has waste lagoons from pig farms that cause serious issues for nearby communities. Both data centers and pig farms are very unevenly distributed and both cause big problems for their neighboring communities.

On an individual level, I would rather see people eat less meat and dairy products than worry about the climate impact of using LLM coding agents. But more so than either of those, I would rather that we have hard and honest conversations with colleagues and loved ones and pressure our elected representatives in government to take action on this problem.

Americans have a habit of thinking about systemic problems through the lens of individual action. As I noted in my lightning talk at PyCon last year, system-level problems require system-level solutions. If the climate impact of LLMs concerns you, I’d encourage you to direct that energy toward the people and institutions that can change these systems.

If you enjoy audobooks, I recommend switching from Audible to Libro.fm (that’s a referral link). Audible has some pretty slimy business practices (noted in my 2024 audiobooks post).

Books about World Betterment

These 7 books are on immigration, economics, sociology, and welfare overall. They’re all on the topic of making the world a better place for all of us.

“The Upswing” by Robert D. Putnam with Shaylyn Romney Garrett

The Upswing is probably the most important book I read in 2025. This book is about moving society away from individualism to and back toward communitarianism: moving from “me” to “we”.

I watched the Join Or Die documentary (it’s on Netflix) before reading this book. The two are different and I would recommend both.

“Mind if I Order the Cheeseburger?: And Other Questions People Ask Vegans” by Sherry F. Colb

From the title Mind if I Order the Cheeseburger, I assumed this would be a snarky book written for vegans. It is not snarky and it’s not primarily for vegans.

This book is for non-vegans who have questions about veganism. It’s fairly plainly written and easy to understand.

I found myself taking issue with some of the arguments in this book but I also found myself admiring some of the arguments and analogies. There were more than a few issues I had never even considered before.

If you’re curious about veganism but hoping to avoid descriptions of the specifics of animal suffering, this is a pretty good book to start with. The author kindly lays out her reasoning without delving too deep into the specifics of factory farming.

“Streets of Gold: America’s Untold Story of Immigrant Success” by Ran Abramitzky and Leah Boustan

Streets of Gold is a book on immigration written by economists in a way that is fairly easy for non-economists to understand. I’m somewhat surprised that such a book exists.

I wish all immigration skeptics read this book and considered the data referenced and the arguments made.

“The Case for Open Borders” by John Washington

I assumed The Case for Open Borders might be focused on the economic case for open borders. It partly focused on that, but it didn’t primarily take an economic angle. I found this interesting and thought-provoking.

If you are skeptical of the idea of radically increasing US immigration, this is the first book I would probably recommend reading.

“Under The Influence” by Robert H. Frank

Under The Influence feels like an economist applying economics to sociology. I found it really interesting. I really enjoyed Robert H. Frank’s Success and Luck. This book is quite different from that one.

I enjoyed the many comparisons of regulation versus taxes, but I especially enjoyed the discussions about what is socially feasible. An idea in theory doesn’t do much good if it won’t work in practice.

“In This Economy?: How Money & Markets Really Work” by Kyla Scanlon

In This Economy? may be my new go-to recommendation for a book on the importance of economics and economic thinking for the average person (folks not already into economics).

Unfortunately, it doesn’t drive too deep into economic thinking but it does discuss the current state of money and markets in the US in a relatable way.

I am still on the lookout for a great “here’s why economics is so important” explainer book.

“On Tyranny” by Timothy Snyder

On Tyranny was quite short. I really enjoy a good short read.

Here are some quotes I wrote down from the chapter on “being kind to our language”:

Think up your own way of speaking, even if only to convey that thing you think everyone is saying.

Politicians in our times feed their cliches to television, where even those who wish to disagree repeat them. Television purports to challenge political language by conveying images, but the succession from one frame to another can hinder a sense of resolution. Everything happens fast but nothing actually happens. Each story on televised news is breaking, until it is displaced by the next one, so we are hit with wave upon wave, but never see the ocean. The effort to define the shape and significance of events require words and concepts that allude us when we are entranced by visual stimuli. Watching televised news is sometimes little more than looking at someone who is also looking at a picture. We take this collective trance to be normal. We have slowly fallen into it.

Staring at screens is perhaps unavoidable, but the 2 dimensional world makes little sense unless we can draw upon a mental armory that we have developed somewhere else. When we repeat the same words and phrases that appear in the daily media, we accept the absence of a larger framework. To have such a framework requires more concepts and having more concepts requires more reading.

Books about Self Betterment

The line between world betterment and self betterment isn’t always clear but to me, all 3 of these books felt a bit more focused on how the reader could better their own life.

“You’re Not Listening” by Kate Murphy

You’re Not Listening was more interesting than immediately actionable, but I can’t complain. This was a fascinating meandering through the world of communication as studied by researchers and as put into practice by hostage negotiators, salespeople, focus group facilitators, etc.

This book was a fairly quick and easy read and I feel it was well-thought and well-edited.

Two takeaways I wrote down:

1. Carl Rogers (who coined “active listening”) says “listening to opposing viewpoints is the only way to grow”
2. Good listener know understanding is not binary: your understanding can always be improved.

I didn’t really take notes, but I wish I had.

“Hope for Cynics” by Jamil Zaki

Hope for Cynics is all about an idea I think is greatly needed today: how to turn cynicism into hope and productive action toward making a better world.

Most people, myself included, at some point despair to the point of complacency with politics, the climate, etc. This book is meant to inspire action instead.

I really liked the idea of hopefully skepticism as a level-headed replacement for cynicism. I was glad that Robert Putnam’s The Upswing was also discussed toward the end.

“Vegan for Life” by Jack Norris and Virginia Messina

The nutrition advice in Vegan for Life is similar to Harvard Medical School’s Eat, Drink, and Be Healthy but it’s targeted specifically to those eating vegan. If you’re concerned about your health as you switch away from animal-based products, read this.

Fiction Books

I didn’t read a lot of fiction this year. Of the bit of fiction I did read, Hank Green’s An Absolutely Remarkable Thing is the book I’d most recommend. I’d also recommend the sequel. They both made me think and made me have big feelings.

“An Absolutely Remarkable” Thing by Hank Green

An Absolutely Remarkable Thing was a really fun book. I read the sequel immediately after I finished this.

I think I enjoy Hank Green’s fiction more than John Green’s.

I don’t want to spoil the book, so I’ll just say that if you think you’d like thoughtful fiction where a big thing happens that changes the world, I’d recommend this book and its sequel.

“The Pioneer” by Bridget Tyler

The Pioneer is a young adult sci-fi novel which I found to be a pretty easy read. There is some “what is personhood”-style grappling (to counter the typical alien xenophobia) that’s slightly reminiscent of Octavia Butler’s Dawn (which I love).

I did find myself slightly frustrated that in this book humanity ends up with faster-than-light travel and yet we still harm creatures that feel pain for very little benefit to ourselves. I don’t regret reading this and ended up reading the sequel as well.

“Children of Ruin” by Adrian Tchaikovsky

“We’re going on an adventure.” (you’ll get this quote stuck in your head)

There’s even more going on in Children of Ruin than the first one (Children of Time). There were definitely moments where I thought “wait who is this person, what species are they, and where are they in the universe”. I think if it hadn’t been a couple years since I read the first book, I would have had an easier time following the plot. Overall, I really enjoyed this sequel.

Recommendations From Past Years

To read my audiobook recommendations from past years see:

• top 9 of 2024 & 30 of 2017-2023
• top 12 of 2016
• top 15 of 2015
• top 6 of 2014

I’ve listened to over 300 audiobooks over the past decade and I’m always looking for new books to listen to. If you have recommendations for me, please comment below, message me on social media, or email me.

The Libro, YNAB, SavvyCal, and GLM links below are referral links. You can find more of my referral links here. I’d love a free audiobook if you end up switching from Audible to Libro.fm (you should seriously consider it, as I noted at the end of this audiobook review post). 💗

• 📝 Notes: Obsidian + NeoVim
• ✅ To-Do: Obsidian
• ✍ Writing: Obsidian + NeoVim
• 🧑‍💻 Code Editor: NeoVim
• ⏲ Focus Mode: Focus Friend & Brain Focus
• 🔍 Search: Kagi (and sometimes the free Perplexity)
• 🤖 LLM chat in-browser: Claude mostly, but sometimes Chat GPT, Z.ai’s GLM, or Typing Mind with API keys
• 🤖 LLM coding agent: Claude Code mostly, sometimes with a Claude subscription and sometimes with my Z.ai GLM subscription
• 🌐 Browser: Vivaldi
• 🔖 Bookmarks: Raindrop.io
• 📚 Audiobooks: Libby (💖), Spotify (meh), Libro (💖), Audible (yuck)
• 🎤 Podcasts: Podcast Republic (switched from Pocket Casts this year)
• 🎵 Music: Spotify
• 📼 Screencasting: OBS + Kdenlive + Whisper API + Custom Python scripts
• 📁 Cloud File Storage: a mix of Git, Dropbox, Google Drive, and Obsidian Sync
• 📜 Word Processing: Google Drive
• 📈 Spreadsheets: Google Drive, Airtable, occasionally LibreOffice
• 💰 Budgeting and Personal Finance: YNAB
• 💬 Chat: Signal, Discord, Slack
• 📆 Scheduling + Booking: SavvyCal
• 📆 Calendar: Google Calendar
• 📹 Video Calls: Google Meet + Discord + Zoom
• 🔐 Password Management: Bitwarden
• 🔏 Multi-Factor Auth: Aegis (Android) + Authenticator (laptop)
• 🐚 Terminal: Gnome Terminal + Tmux + Tmuxstart + Starship + Direnv
• 🐍 Python Installation Manager: uv
• 🐍 Python script runner: uvrs (hopefully to be replaced by uv eventually)
• 🗃️ Version Control: Git
• 🖥️ DNS: Cloudflare
• 📮 Email: Gmail
• 🎒 Backups: Manual Calendar Event + Git
• 🏠 Smart Home Hub: Google Home (maybe I’ll use Home Assistant eventually?)
• 🏃 Fitness Tracker: Fitbit

Also see: - My direnv, starship, and uv setup for Python - My custom Python shell configuration tool - my dotfiles for my customized Python shell configuration, how I manage my project directories, and more.

Biggest changes from 2024

I switched from Pocket Casts to Podcast Republic. I’m not entirely satisfied with either. I wish there was a podcast app that allowed me to easily maintain multiple queues/coming up-style playlists at once but wasn’t so complex.

My LLM use changed this year, first with the discovery of Typing Mind (thanks to my friend Kevin Markham) and later thanks to command-line LLM agents becoming a thing.

I also started using Hank Green’s Focus Friend app. Or maybe playing it, since it’s a bit of a game plus pomodoro-style app in one.

I continue to really appreciate Kagi and have been getting more use out of both Raindrop and Obsidian this year (which were both new to me last year).

I’ve also been really enjoying using uv a bit more seriously than I was last year. I didn’t mention it above, but I’ve finally listened to Jeff’s repeated recommendations to use justfiles and I’m loving those too.

Python-related sales

It’s not even Black Friday yet, but most of these Python-related Black Friday sales are already live:

• Python Morsels: I’m offering lifetime access for the second time ever (more details below)
• Data School: a new subscription to access all of Kevin’s 7 courses plus all upcoming courses
• Talk Python: AI Python bundle, the Everything Bundle, and Michael’s Talk Python in Production
• Reuven Lerner: get 20% off your first year of the LernerPython+data tier (code BF2025)
• Brian Okken: get 50% off his pytest books and courses (code SAVE50)
• Rodrigo: get 50% off all his books including his all books bundle (code BF202550)
• Mike Driscoll: get 50% off all his Python books and courses (code BLACKISBACK)
• The Python Coding Place: get 50% the all course bundle of 12 courses
• Sundeep Agarwal: ~55% off Sundeep’s all books bundle with code FestiveOffer
• Nodeledge: get 20% off your first payment (code BF2025)
• O'Reilly Media: 40% off the first year with code CYBERWEEK25 ($299 instead of $499)
• Manning is offering 50% off from Nov 25 to Dec 1
• Wizard Zines: 50% all of Julia Evan’s great zines on various tech topics that I personally find both fun and useful (not Python-related, but one of my favorite annual sales)… this is a one-day Black Friday exclusive sale

I will be keeping an idea on other potential sales and updating this post as I find them. If you’ve seen a sale that I haven’t, please contact me or comment below.

Django-related sales

Adam Johnson has also published a list of Django-related deals for Black Friday (which he’s been doing for a few years now). I’ve included links below to the different sections in Adam’s post…

Courses and books:

• Adam’s books: his books and bundles on Django, Git, and GitHub DX and Django test performance are all 50% off
• LearnDjango.com course bundle: Will Vincent is offering 50% off his 3 courses
• Django 5 By Example: 30% off this book by Antonio Melé
• Django in Action: 50% off this book by Christopher Trudeau
• Async Patterns in Django: 50% off this book by Paul Bailey

Packages related to Django:

• Aidas Bendoraitis: has 3 Django packages available at a 20% discount
• Appliku: 30% of annual plans for this Django deployment tool
• Saas Pegasus: 50% off the unlimited license for this configurable Django project template

Adam also gives a shout out to sponsoring Django itself.

More on my sale: Python Morsels Lifetime Access

Python Morsels is a hands-on, exercise-driven Python skill-building platform designed to help developers write cleaner, more idiomatic Python through real-world practice. This growing library of exercises, videos, and courses is aimed primarily at intermediate and professional developers. If you haven’t used Python Morsels, you can read about it in my sale announcement post.

This Black Friday / Cyber Monday, I’m offering lifetime access: all current and future content for in a single payment. If you’d like to build confidence in your everyday Python skills, consider this sale. It’s about 50% cheaper than paying annually for five years.

Get lifetime access to Python Morsels

You hit a wall, or something breaks. Then you search around, spend some hours on Stack Overflow, and eventually, you figure it out.

But this kind of learning is unstructured. It’s reactive, instead of intentional.

You fix the problem at hand, but the underlying gaps in your knowledge remain unaddressed.

A more structured way to improve your Python skills

Python Morsels gives you a structured, hands-on way to improve your Python skills through weekly practice:

• Notice significant progress with as little as 30 minutes a week
• Learn to naturally think more Pythonically
• Explore new approaches to problem-solving
• Challenge yourself to get outside your comfort zone regularly

Python Morsels is a subscription service because I’m adding new learning resources almost every week.

But through December 1st, you can get lifetime access for a one-time payment.

How it works

When you sign up for Python Morsels, you’ll choose your current Python skill level, from novice to advanced.

Based on your skill level, each Monday I’ll send you a personalized routine with:

• a short screencast to watch (or read)
• a multi-part exercise to move you outside your comfort zone
• a mini exercise that you can accomplish in just 10 minutes
• links to dive deeper into subsequent screencasts and exercises

Think of Python Morsels as a gym for your Python skills: you come in for quick training sessions, put in the reps, and make a little more progress each time.

All these resources are accessible to you forever, and with lifetime access you’ll never pay another subscription fee.

What Python Morsels includes

Python Morsels has grown a lot over the past 8 years. Currently, Python Morsels has:

• 235+ Video Lessons (or screencasts, as I call them)
• 262+ Hands-On Exercises (with solution walkthroughs)
• 500+ Optional Bonuses (to challenge every skill level)
• 303+ Articles Organized Topic-Wise (if you prefer reading)

I’ll be sending you personalized recommendations every week, but you can use these resources however they fit your routine: as learning guides, hands-on practice sessions, quick cheatsheets, long-term reference material, or quick Python workouts.

In addition to this, Python Morsels also gives you access to:

• Python Jumpstart - a structured course for beginners
• Additional Deep-Dive Courses - structured tracks to master a concept
• Exercise Paths - topic-based exercises to strengthen a specific skill

Because Python Morsels runs as an active subscription service, I’m always adding new screencasts, new exercises, and updated material on a weekly or monthly cycle. I also keep everything up-to-date with each new Python release, incorporating newly added features and retiring end-of-life’d Python versions.

Lock in lifetime access

Python Morsels usually costs $240/year but you can get lifetime access through December 1st for a one-time payment. I’ve only offered lifetime access once before in 8 years.

If you’ve been on the fence about subscribing to Python Morsels or want to invest in building a daily learning habit, this is a good time to do it.

Get lifetime access to Python Morsels

If you have questions about the sale, please comment below or email me.

I open up the REPL to play with an idea, to use Python as a calculator or quick and dirty text parsing tool, to record a screencast, to come up with a code example for an article, and (most importantly for me) to teach Python. My Python courses and workshops are based largely around writing code together to guess how something works, try it out, and repeat.

As I’ve written about before, you can add custom keyboard shortcuts to the new Python REPL (since 3.13) and customize the REPL syntax highlighting (since 3.14). If you spend time in the Python REPL and wish it behaved a little more like your favorite editor, these tricks can come in handy.

I have added custom keyboard shortcuts to my REPL and other modifications to help me more quickly write and edit code in my REPL. I’d like to share some of the modifications that I’ve found helpful in my own Python REPL.

Creating a PYTHONSTARTUP file

If you want to run Python code every time an interactive prompt (a REPL) starts, you can make a PYTHONSTARTUP file.

When Python launches an interactive prompt, it checks for a PYTHONSTARTUP environment variable. If it finds one, it treats it as a filename that contains Python code and it runs all the code in that file, as if you had copy-pasted the code into the REPL.

So all of the modifications I have made to my Python REPL rely on this PYTHONSTARTUP variable in my ~/.zshenv file:

1

export PYTHONSTARTUP=$HOME/.startup.py

If you use bash, you’ll put that in your ~/.bashrc file. If you’re on Windows you’ll need to set an environment variable the Windows way.

With that variable set, I can now create a ~/.startup.py file that has Python code in it. That code will automatically run every time I launch a new Python REPL, whether within a virtual environment or outside of one.

My REPL keyboard shortcuts

The quick summary of my current modifications are:

• Pressing Home moves to the first character in the code block
• Pressing End moves to the last character in the code block
• Pressing Alt+M moves to the first character on the current line
• Pressing Shift+Tab removes common indentation from the code block
• Pressing Alt+Up swaps the current line with the line above it
• Pressing Alt+Down swaps the current line with the line below it
• Pressing Ctrl+N inserts a specific list of numbers
• Pressing Ctrl+F inserts a specific list of strings

If you’ve read my Python REPL shortcuts article, you know that we can use Ctrl+A to move to the beginning of the line and Ctrl+E to move to the end of the line. I already use those instead of the Home and End keys, so I decided to rebind Home and End to do something different.

The Alt+M key combination is essentially the same as Alt+M in Emacs or ^ in Vim. I usually prefer to move to the beginning of the non-whitespace in a line rather than to the beginning of the entire line.

The Shift+Tab functionality is basically a fancy wrapper around using textwrap.dedent: it dedents the current code block while keeping the cursor over the same character it was at before.

The Ctrl+N and Ctrl+F shortcuts make it easier for me to grab an example data structure to work with when teaching.

In addition to the above changes, I also modify my color scheme to work nicely with my Solarized Light color scheme in Vim.

I created a pyrepl-hacks library for this

My PYTHONSTARTUP file became so messy that I ended up creating a pyrepl-hacks library to help me with these modifications.

My PYTHONSTARTUP file now looks pretty much like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

import pathlib as _pathlib, sys as _sys
_sys.path.append(str(_pathlib.Path.home() / ".pyhacks"))

try:
    import pyrepl_hacks as _repl
except ImportError:
    _repl = None  # We're on Python 3.12 or below
else:
    _repl.bind("Home", "home")
    _repl.bind("End", "end")
    _repl.bind("Alt+M", "move-to-indentation")
    _repl.bind("Shift+Tab", "dedent")
    _repl.bind("Alt+Down", "move-line-down")
    _repl.bind("Alt+Up", "move-line-up")
    _repl.bind_to_insert("Ctrl+N", "[2, 1, 3, 4, 7, 11, 18, 29]")
    _repl.bind_to_insert(
        "Ctrl+F",
        '["apples", "oranges", "bananas", "strawberries", "pears"]',
    )

    try:
        # Solarized Light theme to match vim
        _repl.update_theme(
            keyword="green",
            builtin="blue",
            comment="intense blue",
            string="cyan",
            number="cyan",
            definition="blue",
            soft_keyword="bold green",
            op="intense green",
            reset="reset, intense green",
        )
    except ImportError:
        pass  # We're on Python 3.13 or below

del _repl, _pathlib, _sys  # Avoid global REPL namespace pollution

That’s pretty short!

But wait… won’t this fail unless pyrepl-hacks is installed in every virtual environment and installed globally for every Python version on my machine?

That’s where that sys.path.append trick comes in handy…

Wait… let’s acknowledge the dragons 🐲

At this point I’d like to pause to note that all of this relies on using an implementation detail of Python that is deliberately undocumented because it is not designed to be used by end users.

The above code all relies on the _pyrepl module that was added in Python 3.13 (and optionally the _colorize module that was added in Python 3.14).

When I run a new future version of Python (for example Python 3.15) this solution may break. I’m willing to take that risk, as I know that I can always unset my shell’s PYTHONSTARTUP variable or clear out my startup file.

So, just be aware… here be (private undocumented implementation detail) dragons.

Monkey patching sys.path to allow importing pyrepl_hacks

I didn’t install pyrepl-hacks the usual way. Instead, I installed it in a very specific location.

I created a ~/.pyhacks directory and then installed pyrepl-hacks into that directory:

1
2

$ mkdir -p ~/.pyhacks
$ python -m pip install pyrepl-hacks --target ~/.pyhacks

In order for the pyrepl_hacks Python package to work, it needs to available within every Python REPL I might launch. Normally that would mean that it needs to be installed in every virtual environment that Python runs within. This trick avoids that constraint.

When Python tries to import a module, it iterates through the sys.path directory list. Any Python packages found within any of the sys.path directories may be imported.

So monkey patching sys.path within my PYTHONSTARTUP file allows pyrepl_hacks to be imported in every Python interpreter I launch:

1
2
3

from pathlib import Path
import sys
sys.path.append(str(Path.home() / ".pyhacks"))

With those 3 lines (or something like them) placed in my PYTHONSTARTUP file, all interactive Python interpreters I launch will be able to import modules that are located in my ~/.pyhacks directory.

Creating your own custom REPL commands

That’s pretty neat. But what if you want to invent your own REPL commands?

Well, the bind utility I’ve created in the pyrepl_hacks module can be used as a decorator for that.

This will make Ctrl+X followed by Ctrl+R insert import subprocess followed by subprocess.run("", shell=True) with the cursor positioned in between the double quotes after it’s all inserted:

1
2
3
4
5
6
7
8
9
10

import pyrepl_hacks as _repl

@_repl.bind(r"Ctrl+X Ctrl+R", with_event=True)
def subprocess_run(reader, event_name, event):
    """Ctrl+X followed by Ctrl+R will insert a subprocess.run command."""
    reader.insert("import subprocess\n")
    code = 'subprocess.run("", shell=True)'
    reader.insert(code)
    for _ in range(len(code) - code.index('""') - 1):
        _repl.commands.left(reader, event_name, event)

You can read more about the ins and outs of the pyrepl-hacks package in the readme file.

pyrepl-hacks is just a fancy wrapper

The pyrepl-hacks package is really just a fancy wrapper around Python’s _pyrepl and _colorize modules.

Why did I make a whole package and then modify my sys.path to use it, when I could have just used _pyrepl directly?

Three reasons:

1. To make creating new commands a bit easier (functions can be used instead of classes)
2. To make the key bindings look a bit nicer (I prefer "Ctrl+M" over r"\C-M")
3. To hide my hairy hacks behind a shiny API ✨

Before I made pyrepl-hacks, I implemented these commands directly within my PYTHONSTARTUP file by reaching into the internals of _pyrepl directly.

My PYTHONSTARTUP file before pyrepl-hacks was over 100 lines longer.

Try pyrepl-hacks and leave feedback

My hope is that the pyrepl-hacks library will be obsolete one day. Eventually the _pyrepl module might be renamed to pyrepl (or maybe just repl?) and it will have a well-documented friendly-ish public interface.

In the meantime, I plan to maintain pyrepl-hacks. As Python 3.15 is developed, I’ll make sure it continues to work. And I may add more useful commands if I think of any.

If you hack your own REPL, I’d love to hear what modifications you come up with. And if you have thoughts on how to improve pyrepl-hacks, please open an issue or get in touch.

Also, if you use Windows, please help me confirm whether certain keys work on Windows. Thanks!

Contributions and ideas welcome!

Python 3.14 is due to be officially released in about a month. I recommended tweaking your Python setup now so you’ll have your ideal color scheme on release day.

But… what if the default syntax colors don’t match the colors that your text editor uses?

Well, fortunately you can customize your color scheme!

Warning: I am recommending using an undocumented private module (it has an _-prefixed name) which may change in future Python versions. Do not use this module in production code.

Installing Python 3.14

Don’t have Python 3.14 installed yet?

If you have uv installed, you can run this command to launch Python 3.14:

1

$ uv run --python 3.14 python

That will automatically install 3.14 (if you don’t have it yet) and run it.

Setting a theme

I have my terminal colors set to the Solarized Light color palette and I have Vim use a Solarized Light color scheme as well.

The REPL doesn’t quite match my text editor by default:

The numbers, comments, strings, and keywords are all different colors than my text editor.

This code makes the Python REPL use nearly the same syntax highlighting as my text editor:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

from _colorize import set_theme, default_theme, Syntax, ANSIColors

set_theme(default_theme.copy_with(
    syntax=Syntax(
        keyword=ANSIColors.GREEN,
        builtin=ANSIColors.BLUE,
        comment=ANSIColors.INTENSE_BLUE,
        string=ANSIColors.CYAN,
        number=ANSIColors.CYAN,
        definition=ANSIColors.BLUE,
        soft_keyword=ANSIColors.BOLD_GREEN,
        op=ANSIColors.INTENSE_GREEN,
        reset=ANSIColors.RESET + ANSIColors.INTENSE_GREEN,
    ),
))

Check it out:

Neat, right?

But… I want this to be enabled by default!

Using a PYTHONSTARTUP file

You can use a PYTHONSTARTUP file to run code every time a new Python process starts.

If Python sees a PYTHONSTARTUP environment variable when it starts up, it will open that file and evaluate the code within it.

I have this in my ~/.zshrc file to set the PYTHONSTARTUP environment variable to ~/.startup.py:

1
2

# Setup python-launcher to use startup file
export PYTHONSTARTUP=$HOME/.startup.py

In my ~/.startup.py file, I have this code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

def _main():
    """Everything's in a function to avoid polluting the global scope."""
    try:
        from _colorize import set_theme, default_theme, Syntax, ANSIColors
    except ImportError:
        pass  # Python 3.13 and below
    else:
        # Define Solarized Light colors
        solarized_light_theme = default_theme.copy_with(
            syntax=Syntax(
                keyword=ANSIColors.GREEN,
                builtin=ANSIColors.BLUE,
                comment=ANSIColors.INTENSE_BLUE,
                string=ANSIColors.CYAN,
                number=ANSIColors.CYAN,
                definition=ANSIColors.BLUE,
                soft_keyword=ANSIColors.BOLD_GREEN,
                op=ANSIColors.INTENSE_GREEN,
                reset=ANSIColors.RESET + ANSIColors.INTENSE_GREEN,
            ),
        )
        set_theme(solarized_light_theme)

_main()  # _main avoids name collision, in case python -i is used
del _main  # Delete _main from global scope

Note that:

1. I put all relevant code within a _main function so that the variables I set don’t remain in the global scope of the Python REPL (they will by default)
2. I call the _main function and then delete the function afterward, again so the _main variable doesn’t stay floating around in my REPL
3. I use try-except-else to ensure errors don’t occur on Python 3.13 and below

Also note that the syntax highlighting in the new REPL is not as fine-grained as many other syntax highlighting tools. I suspect that it may become a bit more granular over time, which may break the above code.

The _colorize module is currently an internal implementation detail and is deliberately undocumented. Its API may change at any time, so the above code may break in Python 3.15. If that happens, I’ll just update my PYTHONSTARTUP file at that point.

Packaging themes

I’ve stuck all of the above code in a ~/.startup.py file and I set the PYTHONSTARTUP environment variable on my system to point to this file.

Instead of manually updating a startup file, is there any way to make these themes installable?

Well, if a .pth file is included in Python’s site-packages directory, that file (which must be a single line) will be run whenever Python starts up. In theory, a package could use such a file to import a module and then call a function that would set the color scheme for the REPL. My dramatic package uses (cough abuses cough) .pth files in this way.

This sounds like a somewhat bad idea, but maybe not a horrible idea.

If you do this, let me know.

What’s your theme?

Have you played with setting a theme in your own Python REPL?

What theme are you using?

I started writing this post shortly after PyCon, got side-tracked, and now I’m finally publishing it.

My very quick recap: I spent a ton of time at PyCon chatting with folks and I really enjoyed it. As Ned wrote, it’s like summer camp.

My pre-conference (Monday and Tuesday)

I flew in a couple days early (Monday May 12) because Breeze airlines had a non-stop flight from San Diego to Pittsburgh that only ran on Monday or Friday. I listened to The Upswing as I flew in and wondered how we can make our community less individualistic.

On Tuesday, I went on a walking tour of downtown Pittsburgh. Then I ate Indian food for lunch at Sree’s, which I chose because I saw they had great vegan lunch options and weren’t open for dinner. I was eating vegan during PyCon US (as I mostly do at home) and I remembered to do some research on vegan dinner restaurants in the area this year.

On Tuesday night, as CPython core devs started showing up in the Westin lobby, I went on a walk with Anthony Shaw. Anthony asked whether I was up for “an adventure” and I said yes without asking questions. We walked across the river to Randyland (a.k.a. “the mattress factory”). It was fun, interesting, and quite odd. We were the only ones there and had plenty of time to look around at all the interesting items and art pieces that Randy had collected.

Anthony and I did dinner at Condado’s and ran into more conference friends at the bar (Kattni, Rose, and Kojo).

My tutorial on decorators (Wednesday)

Wednesday was my tutorial day.

Attendees used sticky notes during the exercise sections to note when they needed help. I wrote about this system in my blog post of tips for giving a good PyCon tutorial.

The tutorial went well and the attendees seemed to enjoy it.

The newcomer’s orientation & education summit (Thursday)

Just before the opening reception on Thursday evening, Kojo, Sumana, and I ran the newcomer’s orientation. Figuring out what exactly we want to say to help orient folks to PyCon is always a bit challenging. A first-time PyCon attendee gave me some ideas for how we could do it even better next year. I’ve taken notes and will revisit them later.

I also attended a few talks during education summit earlier in the day. Reuven Lerner gave a talk on how he recommends his students use LLMs and I was pleased to hear many suggestions that are closely aligned with what I recommend as well as a few insights I hadn’t heard before.

My lightning talk (Friday)

I gave a lightning talk on Friday evening (the first talk day). I called it Systems, gates, and rage. It seemed to go over well. Folks occasionally told me throughout the conference that they enjoyed it. I won’t spoil the topic of my lightning talk (you’ll need to watch it) but it’s a topic that I’d been thinking about for a few months.

Rodrigo gave a meta lightning talk as the first talk of the first day. I gave a meta lightning talk last year in the same slot. I hope this becomes a tradition, where the first lightning talk is a talk about someone explaining how to give a lightning talk.

The keynotes

I really enjoyed the keynotes this year.

Cory Doctorow’s opening keynote was really thought-provoking and Lynn Root’s keynote was on the importance of “play”, which is a topic I’ve written about before to my mailing list.

The Marshall project keynote and The Carpentries keynote were also great, though I missed portions of each (beginning of one and end of another) and ended up watching the full videos online after the conference.

The hallway track

The “hallway track” is the way many PyCon attendees describe the discussions that happen organically in the hallway.

These discussions can happen at any time, including breaks, breakfast, lunch, and even during talks. I missed at least 3 talks this year because I was having a great discussion in the hallway and time got away from me.

PyCon’s venue in Pittsburgh included a great rooftop so the rooftop track / garden track was a lovely spin in the hallway track this year.

The open spaces

The open spaces are a very important part of PyCon for me.

Like the hallway track, the open spaces are mostly (usually) about having a conversation. Unlike the hallway track, the open spaces have a set topic.

I attended open spaces (and ran my own):

• Education and Outreach Working Group Open Space: I’m part of this newly revived work group and we held this to hear topics that community members are interested in seeing the PSF focus on more deliberately
• t-strings: Let’s build powerful templating together: I am interested in the new t-string feature in Python 3.14 and wanted to listen to this conversation (I contributed a little bit too)
• Computer Assisted Reporting and Investigative journalism: I was curious to hear this conversation, which included journalists, government employees who respond to information requests, and many others
• Python Skill-Building: I ran this open space on the roof during lunch time to chat about different Python skill-building services, including my own (Python Morsels)
• Ask a Friendly Meat-Loving Vegan: I also ran this open space, inspired by a conversation I had the night before in a hotel lobby about animal farming, veganism, nutrition, and other related topics I’ve thought/read a lot about

I enjoyed meeting folks with similar interests and having fun and productive conversations (or at least listening to interesting conversations) in those open spaces.

Dinners, games, and hotel lobby conversations

I ate at Bae Bae’s, Rosewater Grill, and APTEKA during the conference. I also ate at Condado’s at least 3 nights.

APTEKA was a fun trek for vegan PierogiCon with mostly non-vegan folks. I’m sure the pierogis weren’t authentic, but we all loved the food.

After dinner every night I went to the Westin lobby and either played the Cabo card game or chatted with folks (1, 2, 3).

On missing talks

The keynotes and lightning talks are usually my favorite parts of PyCon. I tried to watch as many live keynotes and lightning talk sessions as I could this year. The morning lightning talks were hard to make it to because I kept sleeping in late enough that I missed most of them.

Ultimately, I watched very few live talks. I missed talks due to sleeping in, attending open spaces, visiting booths in the exhibit hall, getting lost in conversations in the hallway, and mid-day taking naps (in my hotel room, not during talks!).

Hynek has written about the downside of the hallway track and the importance of attending talks. I sympathize with Hynek’s argument that the hallway track is a trade off and there are downsides to missing talks, for both attendees and speakers. I am grateful that folks give talks and I want to support folks who do give talks, and yet, I often find myself attending few talks.

Ironically, the one talk I ended up taking a nap through (again, in my hotel room, not in the talk) was Hynek’s. My brain was fried by the time of his talk and I’m glad I was able to watch it online the week after PyCon. He apparently had a completely packed room as it was!

I did make sure to show up to a talk by a conference friend who I wanted to support (Michael Dahlberg’s talk on honeybee swarms). I have also binge-watched a dozen or so talks online that I had planned to attend but missed during PyCon.

You can watch all talks online now (at least I think they’re all up now?).

Attend a Python event

I’m looking forward to PyCon coming to Long Beach next year. I’m in San Diego and it will be nice to not fly to a PyCon for once!

I highly recommend attending local Python meetups, attending regional Python conferences, and/or attending PyCon US. Most in-person Python community events are pretty lovely. The Python community generally goes out of its way to be more welcoming than most tech events.

See you in Long Beach!

Dialysis is should be a stop gap measure. Ideally, dialysis is just an interim solution until a kidney donor is found. Folks with kidney failure really need a new kidney, but most will never receive one. So regular dialysis is a life-long state for many.

More than 100,000 patients in the United States are on the kidney transplant list, but fewer than 20,000 kidneys are transplanted from deceased donors each year and fewer than 10,000 kidneys are transplanted from living donors. About 40,000 people die in the US each year from kidney failure.

The beauty of non-directed kidney donations

Most kidney donations are directed.

With directed kidney donations, a prospective donor states either:

• “I’m signing up to give a kidney to this friend/family member”
• Or “I’m signing up to eventually give a kidney to anyone as long as this friend/family member finds a matching donor in exchange for my donation”

A small minority of kidney donations are non-directed kidney donations. Non-directed donors have discovered that they have 2 kidneys but only need one and that donating a kidney is relatively safe and it saves lives (lives, plural, due to kidney chains). A sizable minority of prospective non-directed kidney donors don’t make the cut, often due to medical concerns.

When a non-directed kidney donor does successfully donate a kidney, that pretty much always unlocks a kidney donation chain, which usually saves 3 or more lives!

Many people have altruistically donated one of their kidneys. Ned Brooks, Allyssa Bates, Dan Drew, and Rochel Smoller all gave TED talks about their experience donating a kidney. But most kidney donations are directed, meaning the donor has agreed to donate a kidney only if a loved one receives a kidney donation as a result. That’s the reason non-directed donations are able to unlock donation chains.

Kidney donations are priceless (literally)

Non-directed kidney donations save lives. Thanks to the math behind kidney donation chains, non-directed donations often save many lives!

But kidney donations also mean less dialysis and dialysis costs money from all of us. Remember, nearly 1% of the federal budget is spent on dialysis.

Interestingly, non-directed kidney donors don’t receive any money for their donation. The doctors, nurse, and all medical staff involved in a kidney transplant receive compensation for their work, but the donor, who is literally donating an organ, receives no compensation at all.

The End Kidney Deaths Act

What if we could save tens of thousands of lives every year, reduce the cost of dialysis to US taxpayers, and incentivize more non-directed kidney donations?

The End Kidney Deaths Act, which is currently going through Congress, is meant to do just that.

If the End Kidney Deaths Act passes, non-directed kidney donations would provide $50,000 of tax credits to the donor, broken up into $10,000 per year over 5 years.

I might donate a kidney for $50,000

I first heard someone argue that donating a kidney was a sensible act in 2020.

The argument goes like this:

1. Donating a kidney saves multiple lives
2. The short-term downside of donating a kidney is largely lost work time
3. The long-term health risks involved with donating a kidney are minimal
4. Therefore you should donate a kidney

I’m somewhat convinced by this argument. And yet I have not donated a kidney.

Why have I not donated a kidney?

Well, I run my own business and I don’t think I would want to lose 2 weeks of work. Also I don’t really want to go through the process. Plus, I can always donate a kidney next year, right?

I’m choosing not to save someone’s life because it’s a large inconvenience for me. That may sound selfish, but you’re in the same situation that I am.

For $50,000 of tax credits, I would much more seriously consider donating a kidney.

Let’s think through the “ick” factor

We’re generally uncomfortable with the idea of paying another human for their body parts. There are good reasons and bad reasons for this, but I don’t believe the good reasons apply in this case… at least not enough to outweigh the lives that this bill would save.

Around 70% of the world’s donated plasma comes from the US, largely due to the fact that plasma donors in the US are compensated for their donation. There are ethical considerations around plasma donation and this industry should be better regulated. Kathleen McLaughlin wrote a book about this: interview and book review. And yet, regulation aside, I think it’s worth compensating plasma donors to reduce the world plasma shortage (Planet Money episode).

Another thing to note when comparing kidney donations to plasma donations: the End Kidney Deaths Act would compensate kidney donors via tax credits, not through private markets. Each approach has pros and cons, but the “this is exploitative” argument is often applied to markets but rarely applied to tax credits.

You may be experiencing a “this might not be a good idea” reaction when thinking about paying non-directed kidney donors, even through tax credits. It’s worth thinking through why that is. What is your brain telling you? Which of the underlying arguments against this are worth considering? And how do those arguments look when put within the bigger picture?

Let’s compensate altruistic kidney donors

Non-directed kidney donations are extremely valuable. I think we should incentivize these donations. I hope Congress passes the End Kidney Deaths Act.

What do you think?

Is this something you would write your representative about?

Please join this effort

The podcast episode with Elaine Perlman is what inspired me to spend a couple hours researching and writing this post.

Since originally publishing this post, I clicked the “join the team” button at EndKidneyDeathsAct.org. The form took only a minute to fill out, I’ve received a few emails since then, including an email thread with a few others in my congressional district, and I’m now considering writing an op-ed in a newspaper about this.

If, like me, you feel that this is a very sensible idea, so much so that you would spend a few minutes or a few hours of time to try to make this happen, please get involved a bit more deeply. You can click the “contact your leaders” button at EndKidneyDeathsAct.org or, like me, you could click “join the team”.

I’m glad to now be a small part of this very important effort. I think you will be glad to be part of this too.

I have never written a book, an academic paper, or a journal article. And yet I do write.

I write emails, I write blog posts, I write screencast scripts, I journal, I write talks, and I write curriculum for my Python trainings.

When I write, I need a place to put text that may not make the cut in a final draft. I call this place the “cutting room floor”.

How I write: draft, research, edit

Before sharing what I mean by a “cutting room floor”, I need to explain how I write.

I tend to write in 2-3 stages:

1. Draft: writing more words, ideally without deleting or modifying
2. Research: discovering facts playing with possible examples
3. Edit: deleting, rearranging, and modifying words

When drafting, I try to barf out words quickly and, ideally, without any editing at all. I often do this by setting a 25 - 60 minute timer and then writing thoughts as they pour out of my head.

When researching, I’m looking things up online, trying out code in a text editor, and sometimes playing with ideas in an abstract way. This phase sometimes looks like traditional “research” and sometimes includes a mix of research and brainstorming.

When editing, I’m re-reading my words and attempting to turn them into something good. The first draft is sometimes pretty close to what I ultimately end up with, but sometimes it’s very different from what I eventually publish.

Sometimes I draft and then edit without any research. Sometimes I research first. And often I bounce back and forth between these different tasks.

I try to keep my drafting time distinct from my research and editing time. When drafting, my thoughts aren’t always sensible, but they’re something. It’s often easier to edit a bunch of something into something sensible than it is to write something sensible in the first place.

It’s very tempting to start researching or editing while I’m drafting. I try to counter that temptation by writing TODO insert blah here whenever I feel that something is needed but that thing needs further research before I can write a certain paragraph or so about it.

The “cutting room floor” is about editing

When I’m editing my writing, I frequently find it challenging to remove certain sections. I often feel like I wrote something important, even while acknowledging that it may not fit well within the larger piece I’m writing. I often don’t realize that an idea or a bit of writing doesn’t fit until I’m far into editing.

The cutting room floor is a way to save a specific bit of writing while also acknowledging that I may never use it.

When using a “cutting room floor”, I select a paragraph or a whole section of text and I “cut” it out of my writing and then “paste” it at the bottom of the document under a “Cutting room floor” section. Or sometimes I’ll paste it in a separate file, called something like cutting-room-floor.md.

I do usually delete that file or that section from my text, but not until the end. Even when my text is all version-controlled, it feels much less final and scary to move some text into a (possibly temporary) “cutting room floor” than it feels to delete the text entirely.

Kill your darlings… or set them aside?

The noun “cutting room floor” relates to the verb “kill your darlings”.

While “kill your darlings” may sound like a violent phrase, it essentially means “don’t be afraid to remove things you like”.

In my PyOhio keynote in 2024, I originally had a whole section on cognitive dissonance. This section involved my own personal experience with cognitive dissonance and I spent a lot of time trying to make this section coherent, thoughtful, and impactful. That was originally my favorite section of the talk, but I eventually deleted that entire section from the talk.

As I iterated versions of the talk, that “darling” section made less and less sense within the context of the whole talk. At some point I realized that the section was only in the talk because it was a darling for me.

That section meant something special to me, but it just didn’t fit. Reluctantly, I moved it to the cutting room floor. I kept iterating and the eventual talk was better because I cut that “darling” section out.

My cutting room floor allowed me to kill a darling by setting it to the side. I could always add it back in later, but ultimately, I never did. Once it was removed, I knew the talk made more sense.

Allow yourself to delete everything

Having a “cutting room floor” gives me permission to delete any section of any talk, screencast, or article I write.

A “cut” section isn’t gone. It’s just been moved to the cutting room floor… possibly just temporarily! I can always add the section back in later if I want.

The cutting room floor could be thought of as a sort of graveyard, but it can also be a place of inspiration. I rarely add sections back into my talk after I cut them, but I do often spend time re-drafting a new section that replaces a section that I had cut. Sometimes I’ll even look at the text in my cutting room floor, borrowing the words I like as I write replacement text.

Instead of saying an emphatic “NO” by deleting permanently, I can say “not right now” by moving text to the cutting room floor. For me, “not right now” is often a lot easier for me to say than “no”.

So during your editing session, give yourself permission to cut by making a cutting room floor.

In this post I’ll be sharing my thoughts on giving a great PyCon tutorial.

Screen readability 👓

Be sure to consider readability when teaching a tutorial. Talks usually involve slides and the default font size in presentation software is often pretty readable on a projector. That’s not usually the case for code editors, web browsers, and terminals.

Consider the size of the text you’ll be displaying. I tend to zoom in until my screen can just barely fit about 80 characters of text.

Also consider your color scheme. When reading from a projector, black text on a white background is usually easier to read than white text on a black background. So I recommend using a light mode color scheme even if you usually prefer dark mode. And be sure to use a high contract color scheme!

Also consider how you’ll share URLs. Shortened URLs are easier to type. QR codes can also help, but be sure to share the actual URL as some may not be able to scan QR codes.

Engage attendees in attempted information retrieval 🧠

Have you ever heard the phrase “in one ear and the other”? That’s how lectures usually work. Lectures tend to focus on putting information into our heads. Unfortunately, our brain isn’t designed to remember information that’s presented to it.

We don’t learn by putting information into our heads; we learn by trying to retrieve information from our heads. Information retrieval attempts, even somewhat unsuccessful ones, are very important for helping our brain retain information.

So, how will your tutorial engage attendees in the act of attempted information retrieval?

You could:

• Group quiz: “what do you think might happen if…?”
• Silently quiz: present a quiz question every few minutes to work on individually
• Take 10 minute exercise breaks every 20 minutes so attendees can write code to apply what they’ve just seen

Give attendees a way to know whether they “did it right” as well. But also keep in mind that the focus of any sort of quizzing should be on taking a guess, not on getting a grade.

We don’t learn by watching, but by doing, so I recommend planning your tutorial around a lot of recall.

Prepare for the unprepared 😦

Since your tutorial is going to be hands-on (see the previous section), you’ll probably need your attendees to set things up on their machines.

You could set aside the first 30 minutes of your 3 hour tutorial for setup steps, but I wouldn’t recommend that. Setup will take some attendees 5 minutes and others 25 minutes. Expecting folks who are quick to idle for many minutes isn’t ideal.

If possible, I would recommend writing up prerequisite setup instructions and asking attendees to perform necessary setup steps before PyCon. A week or two before PyCon, email those installation and/or setup instructions. Then email those instructions a couple more times. Yes, that may seem redundant, but redundant reminders can be very helpful.

Some attendees will register after you send out your first instructions email, some will ignore or skip over emails, and some may even register for your tutorial on the day of your tutorial.

It’s helpful to give any unprepared attendees some escape hatches to get caught up.

For example, you could let attendees know that:

1. You would like them to work through setup instructions by X date
2. You be available for asynchronous email-based assistance and they should email you if they get stuck
3. You will be in your tutorial room early and you can help anyone who also shows up 15 minutes early get setup

Inevitably, somewhere around 10% of your attendees will not work through the setup instructions in full before the start of your tutorial.

Please do provide help to these unprepared attendees, but don’t punish the prepared ones, at least not too much. For example, if you have a 15 minute exercise section near the beginning of your tutorial, float around the room during that time and make sure everyone has their machines setup.

Expect the unexpected 🚨

What happens if an attendee’s work laptop doesn’t allow them to install or run certain programs? What if an attendee brings a Chromebook and your installation instructions assume Linux, Mac, or Windows? What if an attendee didn’t bring a laptop?

What’s your backup plan?

Can attendees use an online interface instead of working locally? Do you have a spare laptop with a guest account they could use? Could another attendee volunteer to have someone pair up with them?

And what happens if the Internet drops out? Internet issues have plagued many a tutorial presenter in the past, especially for tutorials that involve dozens of attendees all downloading many megabytes at the same time. Consider bringing a pre-loaded USB thumb drive or two as a backup plan.

Have helpers, if you can 🧷

Having an exercise “break” early on allows those in need of extra setup help to catch up.

I also like to encouraging attendees to try helping each other out. This can set a sort of “we’re all in this together” atmosphere. When an attendee helps a neighbor understand the instructions for an exercise, that may also help them solidify their understanding as well.

If you can find a volunteer teaching assistant (TA) or two who can familiarize themselves with your material even just a little bit, that can be very handy. The primary role of a TA is to simply to act as another set of eyes and ears for attendees who need a bit of extra help. This is especially helpful during the first exercise section or two, when everyone is getting setup and wading into the material.

During exercise breaks in my recorded PyCon tutorials (e.g. here or here or here) you may notice me and my TAs wondering around the room helping folks who have stickies up (more on that below) and generally checking in on folks who have confused expressions on their faces.

For both you and your helpers, consider what it means to be a helpful helper. You may want to watch my Meaningful Mentoring Moments talk or review some of the materials I link to in that talk.

Seek advice from others 🧑‍🏫

In each of my tutorials I give every attendee a sticky note. I either put a sticky note at each chair before we begin, have a TA give a sticky notes to each person as they walk in, or I walk around the room and say hi to each person while giving them a sticky note.

After everyone has a sticky note, I explain their purpose: to flag down me (or a TA) during exercises when help is needed. It’s difficult to type on your keyboard while keeping a hand raised in the air for many many minutes. Sticky notes allow attendees to signal that they need help and they allow me to quickly scan the room and see how many folks need help.

You probably wouldn’t have thought of sticky notes. I wouldn’t have either! I saw them used in an Open Hatch workshop many years ago and thought “that’s genius”.

Ask for advice from others who have taught live tutorials, workshops, and classes. You may not find every bit of advice helpful, but most of us who have taught before are happy to share what works for us.

Envision the moment 💭

If we learn solely from experience, then the first time we do something we’d expect to fail miserably. But that’s (obviously) not what we want to happen. We want our first tutorial to be a reasonably successful experience.

Fortunately, our brains are half decent reality simulators. Let’s use our brain’s ability to simulate future possibilities to our advantage.

Imagine the world from the perspective of your attendees. Where might they get stuck or frustrated? If they don’t feel comfortable speaking up, will you know about their frustrations? Will you be deliberately polling the room to see how they’re feeling? When? How often? What will trigger you to poll the room?

Imagine when pulse checks might be helpful to see how your audience members are feeling.

Also, imagine how much of your curriculum you’ll get through. How might you meet your attendees' expectations if it takes twice the time to get through curriculum? Is there anything that can be skipped?

What happens if you get to the end and you have 30 minutes left? Could you add extra material that’s expected to be skipped, but could be worked through if there’s additional time?

What will the call-to-action be at the end of your tutorial? Are there future projects attendees could work through? Are there specific actions you would recommend attendees take next?

Use checklists ✅

One time I forgot to pack sticky notes and found myself frantically looking for a nearby office supplies store the morning of my tutorial. And then I did that 2 more times. 😬

You can’t keep everything in your head. Use a checklist to keep yourself on track during your tutorial and leading up to your tutorial.

Here’s a checklist with much of the advice in this post:

1. Use a large font and a highly readable color scheme
2. Be sure your curriculum facilitates active recall
3. Nudge attendees to work through setup instructions before your tutorial
4. Be prepared to help a portion of the room with setup instructions during the tutorial
5. Try to find teaching assistants if you can
6. Wander around the room to help during exercise sections
7. Consider using sticky notes so attendees can flag down help during exercise sections
8. Ask other tutorial presenters and teachers for advice
9. Mentally walk through the day and consider what might go differently than planned

Have compassion 💖

Doing hard things is hard. Explaining hard things is even harder.

Learning isn’t easy either.

Be kind to your attendees and be kind to yourself. Mistakes will happen. Try to keep moving forward and do your best to make good use of the time you have.

My guess was correct. During PyCon US 2024, Mastodon overtook Twitter for the most posts on the #PyConUS hashtag.

In the fall of 2024, Bluesky really took off. It currently seems like Bluesky is now a bit more popular than Mastodon for Python posts in general… but that doesn’t necessarily mean it will be the most popular social media network during the conference.

This year I’m guessing that Mastodon will still be the most popular network for #PyConUS posts, though I wouldn’t be very surprised if Bluesky took the lead instead.

What do the social networks think?

I decided to pose this question to the various social networks via a poll. I made sure to share these polls using both the #Python and #PyConUS hashtags for visibility’s sake.

The results?

• LinkedIn poll: LinkedIn isn’t sure whether Twitter is the new Twitter
• Twitter poll Twitter (mostly) knows that Bluesky is the new Twitter
• Bluesky poll Bluesky knows the really nerdy tech folks hang out on Mastodon
• Mastodon poll Mastodon loves itself above all else

In other words, LinkedIn leans more toward Bluesky being the leader than Mastodon, Twitter leans toward Bluesky, but Bluesky and Mastodon both lean toward Mastodon being the leader during PyCon.

I didn’t mention Threads or other platforms because they didn’t seem like real contenders given where the most active PyCon-attending Python-posting folks seem to hang out in 2025.

The actual results

Here are the actual results of the polls.

LinkedIn

Twitter

Bluesky

Mastodon

We’re still fragmented

Unfortunately, regardless of which network is the leader this year during PyCon US, we’re still going to be much more fragmented than we used to be. Twitter was the clear leader years ago and it very clearly isn’t anymore… at least not for PyCon US conference chatter.

I’ll be checking Mastodon and Bluesky and will post on at least Mastodon and possibly also Bluesky. I hope that other folks will also use one of these 2 social networks to organize dinners and gatherings! 🤞

Feel free to follow me on Mastodon and Bluesky during the conference.

Also let me know if you’d like to join my PyCon US starter pack on Bluesky. Lists on Mastodon require following and I prefer not to follow everyone I meet at PyCon so, unfortunately, I probably won’t have a Mastodon equivalent of this. 😢

I recommend checking the #PyConUS hashtag on both networks as well. Note that you can subscribe to hashtags on Mastodon which is pretty neat!

See you at PyCon!

If this will be your first PyCon US, I recommend signing up for both Mastodon and Bluesky and checking the #PyConUS hashtag during the conference.

Also, be sure to see my post on having a great first PyCon and see this additional tips.

I have.

Unfortunately, Django’s {% include %} tag doesn’t accept blocks of text.

Let’s look at a few possible solutions to this problem.

The Problem: Hack Include Workarounds

Let’s say we have HTML and CSS that make up a modal that is powered by Alpine.js and HTMX and we want to include this base modal template into many different templates for many different actions.

The problem is that the main content of our modal changes for different use cases.

We could try to fix this problem by breaking up our “include” into two parts (a top and a bottom).

Here’s the top include (_modal_top.html):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

<div
  x-data="{}"
  id="base-modal"
  ="$dispatch('close-modal')"
  x-on:keydown.escape.prevent.stop="$dispatch('close-modal')"
  x-on:close-modal.stop="$el.remove()"
  role="dialog"
  aria-modal="true"
  x-id="['modal-title']"
  :aria-labelledby="$id('modal-title')"
  class="tw-fixed tw-inset-0 tw-z-10 tw-overflow-y-auto"
  style="z-index: 2000;"
>
  <!-- Overlay -->
  <div x-transition.opacity class="tw-fixed tw-inset-0 tw-bg-black tw-bg-opacity-50"></div>

  <!-- Panel -->
  <form
    id="modal-panel"
    hx-=""
    hx-select="#modal-panel"
    hx-swap="outerHTML"
    x-transition
    x-on:click="$dispatch('close-modal')"
    class="tw-relative tw-flex tw-min-h-screen tw-items-center tw-justify-center tw-p-4"
  >
    <div
        x-on:click.stop
        x-trap.noscroll.inert="true"
        class="tw-relative tw-w-full tw-max-w-lg tw-overflow-y-auto tw-rounded-xl tw-bg-white tw-p-6 tw-shadow-lg"
    >
      <!-- Title -->
      <h5 h:id="$id('modal-title')"></h5>

And here’s the bottom include (_modal_bottom.html):

1
2
3

</div>
  </form>
</div>

This is how we might use these modals:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{% url "api:delete" object.pk as delete_url %}
{% include "_modal_top.html" title="Delete Object" close_event="@solution-deleted.window" htmx_method="delete" htmx_action=delete_url %}

<div class="tw-mt-7 tw-text-gray-600">
  <p>Are you sure you want to delete <strong>{{ object }}</strong>?</p>
</div>

<div class="tw-mt-9 tw-flex tw-justify-end tw-space-x-2">
  <button class="btn btn-danger" type="submit">Delete</button>
  <button class="btn btn-secondary" type="reset" x-on:click.prevent="$dispatch('close-modal')" data-dismiss="modal">Cancel</button>
</div>

{% include "_modal_bottom.html" %}

This is pretty awful.

What other solutions are there?

One Solution: Just Copy-Paste

Instead of messy with includes, we could just copy-paste the HTML we need every time we need it:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

<div
  x-data="{}"
  id="base-modal"
  @solution-deleted.window="$dispatch('close-modal')"
  x-on:keydown.escape.prevent.stop="$dispatch('close-modal')"
  x-on:close-modal.stop="$el.remove()"
  role="dialog"
  aria-modal="true"
  x-id="['modal-title']"
  :aria-labelledby="$id('modal-title')"
  class="tw-fixed tw-inset-0 tw-z-10 tw-overflow-y-auto"
  style="z-index: 2000;"
>
  <!-- Overlay -->
  <div x-transition.opacity class="tw-fixed tw-inset-0 tw-bg-black tw-bg-opacity-50"></div>

  <!-- Panel -->
  <form
    id="modal-panel"
    hx-delete="{% url "api:delete" object.pk %}"
    hx-select="#modal-panel"
    hx-swap="outerHTML"
    x-transition
    x-on:click="$dispatch('close-modal')"
    class="tw-relative tw-flex tw-min-h-screen tw-items-center tw-justify-center tw-p-4"
  >
    <div
        x-on:click.stop
        x-trap.noscroll.inert="true"
        class="tw-relative tw-w-full tw-max-w-lg tw-overflow-y-auto tw-rounded-xl tw-bg-white tw-p-6 tw-shadow-lg"
    >
      <!-- Title -->
      <h5 h:id="$id('modal-title')">Delete Object</h5>

      <!-- Content -->
      <div class="tw-mt-7 tw-text-gray-600">
        <p>Are you sure you want to delete <strong>{{ object }}</strong>?</p>
      </div>

      <!-- Buttons -->
      <div class="tw-mt-9 tw-flex tw-justify-end tw-space-x-2">
        <button class="btn btn-danger" type="submit">Delete</button>
        <button class="btn btn-secondary" type="reset" x-on:click.prevent="$dispatch('close-modal')" data-dismiss="modal">Cancel</button>
      </div>
    </div>
  </form>
</div>

Honestly, I think this solution isn’t a bad one. Yes it is repetitive, but it’s so much easier to understand and maintain this big block of fairly straightforward HTML.

The biggest downside to this approach is that enhancements made to one of the styling and features of these various copy-pasted modals will likely diverge over time if we’re not careful to update all of them whenever we update one of them.

A Better Solution: Components

If I was using a component-based front-end web framework, I might be tempted to push all this logic into that front-end framework. But I’m not using a component-based front-end front-end web framework and I don’t want to be forced to push any component-ish logic into the front-end.

Fortunately, in 2025, Django has a number of component frameworks.

If we setup django-cotton, we could make a cotton/modal.html file like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

<div
  x-data="{}"
  id="base-modal"
  {{ close_event }}="$dispatch('close-modal')"
  x-on:keydown.escape.prevent.stop="$dispatch('close-modal')"
  x-on:close-modal.stop="$el.remove()"
  role="dialog"
  aria-modal="true"
  x-id="['modal-title']"
  :aria-labelledby="$id('modal-title')"
  class="tw-fixed tw-inset-0 tw-z-10 tw-overflow-y-auto"
  style="z-index: 2000;"
>
  <!-- Overlay -->
  <div x-transition.opacity class="tw-fixed tw-inset-0 tw-bg-black tw-bg-opacity-50"></div>

  <!-- Panel -->
  <form
    id="modal-panel"
    hx-{{ htmx_method }}="{{ htmx_action }}"
    hx-select="#modal-panel"
    hx-swap="outerHTML"
    x-transition
    x-on:click="$dispatch('close-modal')"
    class="tw-relative tw-flex tw-min-h-screen tw-items-center tw-justify-center tw-p-4"
  >
    <div
        x-on:click.stop
        x-trap.noscroll.inert="true"
        class="tw-relative tw-w-full tw-max-w-lg tw-overflow-y-auto tw-rounded-xl tw-bg-white tw-p-6 tw-shadow-lg"
    >
      <!-- Title -->
      <h5 h:id="$id('modal-title')">{{ title }}</h5>

      <!-- Content -->
      <div class="tw-mt-7 tw-text-gray-600">
        {{ slot }}
      </div>

      <!-- Buttons -->
      <div class="tw-mt-9 tw-flex tw-justify-end tw-space-x-2">
        {{ buttons }}
      </div>

    </div>
  </form>
</div>

We can then use our modal component like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<c-modal
  title="Delete Object"
  close_event="@solution-deleted.window"
  htmx_method="delete"
  htmx_action={% url "api:delete" object.pk %}
>
  <div class="tw-mt-7 tw-text-gray-600">
    <p>Are you sure you want to delete <strong>{{ object }}</strong>?</p>
  </div>

  <c-slot name="buttons">
    <button class="btn btn-danger" type="submit">Delete</button>
    <button class="btn btn-secondary" type="reset" x-on:click.prevent="$dispatch('close-modal')" data-dismiss="modal">Cancel</button>
  </c-slot>
</c-modal>

I find this a lot easier to read than the include approach and a lot easier to maintain than the copy-pasted approach.

The Downsides: Too Much Magic

The biggest downside I see to django-cotton is that it’s a bit magical.

If you see <c-some-name> in a template, you need to know that this includes things from cotton/some_name.html.

There are lots of action at a distance issues that come up with Django, which can make it feel a bit magical but which are nonetheless worthwhile tradeoffs. But this one also doesn’t look like a Django template tag, filter, or variable. That feels very magical to me.

I’ve been enjoying trying out django-cotton over the past week and enjoying it.

Here are 2 other Django component libraries I have considered trying:

• django-bird
• slippers
• django-includecontents

I doubt I will try these 3, as they require writing Python code for each new component, which I would rather avoid:

• django-components
• django-web-components
• django-viewcomponent

All Django component libraries (except for django-cotton) disallow line breaks between passed-in attributes due to a limitation of Django’s template tags (see below).

The Future: Multi-line Django Template Tags?

If Django’s template tags could be wrapped over multiple lines, we could create a library that worked like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{% url "api:delete" object.pk as delete_url %}
{% component "_modal.html"
  title="Delete Object"
  close_event="@solution-deleted.window"
  htmx_method="delete"
  htmx_action=delete_ul
%}
  <div class="tw-mt-7 tw-text-gray-600">
    <p>Are you sure you want to delete <strong>{{ object }}</strong>?</p>
  </div>

  {% slot "buttons" %}
    <button class="btn btn-danger" type="submit">Delete</button>
    <button class="btn btn-secondary" type="reset" x-on:click.prevent="$dispatch('close-modal')" data-dismiss="modal">Cancel</button>
  {% endslot %}
{% endcomponent %}

But that first multi-line {% component %} tag is a big problem. This is invalid in Django’s template language because tags cannot have linebreaks within them (see this old ticket, this discussion, and this new ticket):

1
2
3
4
5
6

{% component "_modal.html"
  title="Delete Object"
  close_event="@solution-deleted.window"
  htmx_method="delete"
  htmx_action=delete_ul
%}

Until Django’s template language allows tags to span over multiple lines, we’re stuck with hacks like the ones that django-cotton uses.

Inspired by Jeff’s list.

You can find my referral links here for Libro, YNAB, or SavvyCal. I’d love a free audiobook if you end up switching from Audible to Libro.fm. 💗

• 🌐 Browser: Vivaldi
• 🔍 Search: Kagi (sometimes free Perplexity)
• 🤖 LLM: Claude
• 📝 Notes: Obsidian + Vim
• ✅ To-Do: Obsidian
• ✍ Writing: Obsidian + Vim
• 🧑‍💻 Code Editor: Vim
• 📼 Screencasting: OBS + Kdenlive + Whisper API + Custom Python scripts
• 📚 Audiobooks: Libby (💖), Spotify (meh), Libro (💖), Audible (yuck)
• 🎤 Podcasts: Pocket Casts, though I wish I had a better alternative
• 🎵 Music: Spotify
• 📁 Cloud File Storage: a mix of Git, Dropbox, Google Drive
• 📜 Word Processing: Google Drive
• 📈 Spreadsheets: Google Drive, Airtable
• 💰 Budgeting and Personal Finance: YNAB
• 💬 Chat: Signal, Discord, Slack
• 📆 Scheduling + Booking: SavvyCal
• 📆 Calendar: Google Calendar
• 📹 Video Calls: Google Meet + Zoom
• 🔐 Password Management: Bitwarden
• 🔏 Multi-Factor Auth: Aegis (Android) + Authenticator (laptop)
• 🐚 Terminal: Gnome Terminal + Tmux + Tmuxstart + Starship + Direnv
• 🗃️ Version Control: Git
• 🖥️ DNS: Cloudflare
• 🔖 Bookmarks: Raindrop.io
• 📮 Email: Gmail
• 🎒 Backups: Manual Calendar Event + Git

After a 7 year hiatus, I’m attempting to start this annual habit again, starting with audiobooks I read in 2024. But first, I’ll reflect on some of the books that have stuck with me from 2017 through 2023.

Books that have stuck with me from 2017 to 2023

Of the 206 books I read over the 7 years of 2017 through 2023, about 35 books really stuck with me and I would recommend reading all of them.

Each section in ordered roughly by how much I would generally recommend the book (the first book in each section I usually recommend more than the last). I enjoyed all these books, but I didn’t write a review for all of them. I’ve included links when I did write a review.

Really enjoyable Sci-Fi (and a bit of Fantasy) that’s stuck with me:

• Dawn (and also Adulthood Rites) by Octavia Butler
• The Long Way to a Small, Angry Planet (& A Closed and Common Orbit) by Becky Chambers
• The Fifth Season (and the other 2 books in the series) by N.K. Jemisin
• Hive Minds Give Good Hugs by Natalie Maher
• Parable of the Sower (and Parable of the Talents) by Octavia Butler
• A Song for a New Day by Sarah Pinsker
• The City We Became by N.K. Jemisin

Books on human progress (to extinguish your cynicism):

• Enlightenment Now by Steven Pinker
• Factfulness by Hans Rosling
• The Fabric of Civilization: How Textiles Made the World by Virginia Postrel

The book that has most shaped my charitable giving habits:

• The Life You Can Save by Peter Singer (free here)

My favorite self-improvement books:

• Mind Management, Not Time Management by David Kadavy
• The Scout Mindset by Julia Galef
• Deep Work by Cal Newport
• The Joy of Movement by Kelly McGonigal
• Learn Like a Pro by Barbara Oakley, Olav Schewe
• Atomic Habits by James Clear
• Good Habits, Bad Habits by Wendy Wood

Books on economics, government, and public policy that aren’t about housing and city planning:

• Basic Economics: A Citizen’s Guide to the Economy by Thomas Sowell
• Recoding America by Jennifer Pahlka
• Drug Use for Grown-Ups: Chasing Liberty in the Land of Fear by Carl L. Hart
• How Rights Went Wrong by Jamal Greene

Books on housing and city planning that have shaped my YIMBY-ish views:

• Happy City by Charles Montgomery
• Arbitrary Lines: How Zoning Broke the American City and How to by M. Nolan Gray
• Walkable City: How Downtown Can Save America, One Step at a Time by Jeff Speck
• Paved Paradise: How Parking Explains the World by Henry Grabar

Books on xenophobia and other-ing that have particularly stuck with me:

• Caste by Isabel Wilkerson
• The Sum of Us: What Racism Costs Everyone and How We Can Prosper Together by Heather McGhee

Books that have impacted my very gradual journey toward veganism:

• Why We Love Dogs, Eat Pigs, and Wear Cows by Melanie Joy
• The End of Animal Farming by Jacy Reese Anthis

TV shows I’ve (so far) liked more than the books they’re based on:

• Silo (Apple TV)
• The Power (Amazon Prime)
• The Three-Body Problem (Netflix, though Amazon Prime has a much slower Chinese version)

Note that the above books do not include books I listened to in 2014, 2015, and 2016. See my other audiobook posts here. Of those 3 years of books, the ones that I’d recommend most are Success and Luck by Robert H. Frank (2016), Just Mercy by Bryan Stevenson (2014), Whistling Vivaldi by Claude M. Steele (2015), and Make it Stick by Peter C. Brown, Henry L. Roediger III, Mark A. McDaniel (2016).

Also note that all the links above point to Goodreads, which I don’t recommend despite the fact that I use it. I plan to eventually switch to The Story Graph for recording my reading activity, but I’m awaiting an API so I can update my current reading-tracking system (which is based around a Google Sheet totaling hours read and other stats) to use it instead of Goodreads.

My favorite audiobooks of 2024

I read 41 audiobooks this year.

These are the ones I would most recommend listening to.

• Best self-help book:
  • Eat, Drink, and Be Healthy: The Harvard Medical School Guide to Healthy Eating
• Best page-turners:
  • Says Who? A Kinder, Funner Usage Guide for Everyone Who Cares About Words
  • A Little Devil in America: Notes in Praise of Black Performance
• Most thought-provoking:
  • Land is a Big Deal: Why rent is too high, wages too low, and what we can do about it
  • The Myth of Left and Right: How the Political Spectrum Misleads and Harms America
  • Uncommon Sense Teaching: Practical Insights in Brain Science to Help Students Learn
• Validated my current world view and I recommend read to challenge themselves:
  • Not the End of the World: How We Can Be the First Generation to Build a Sustainable Planet
  • Determined: A Science of Life without Free Will
  • Eating Animals

Eat, Drink, and Be Healthy: The Harvard Medical School Guide to Healthy Eating

This is the best book I’ve read about nutrition. This book contains no silver bullets; just evidence-backed advice.

If you’re reading this in audiobook-form, note that the last portion of the book contains recipes, read out-loud for many minutes… so I would stop listening once the recipes start. I’m considering buying a hard copy for some of the recipes.

Says Who? A Kinder, Funner Usage Guide for Everyone Who Cares About Words

This book pleased my inner wordy and challenged my inner grammando (those terms are explained in the book).

If you enjoy poking at the English language, I think you’ll find this a fun listen.

A Little Devil in America: Notes in Praise of Black Performance

This is a beautifully written book.

If you enjoy writing that’s thought-provoking, emotional, and engrossing, read/listen to this.

Land is a Big Deal: Why rent is too high, wages too low, and what we can do about it

This book is all about implementing a “land value tax” and it does a good job of explaining what that means and what the consequences might be. A land value tax feels like an extreme marriage of capitalism and socialism, as it would (sort of) abolish private ownership of land while encouraging the market to make the best use of each piece of land. The subject of this book is very wonky so this book was a bit challenging at times, but I found it fairly accessible overall.

For the sake of affordable housing, loosening or removing zoning restrictions (see the book Arbitrary Lines mentioned above) and reducing regulatory requirements around construction seem more important than a land value tax. But as far as taxes go, a land value tax does seem like the most justice-oriented and efficiency-oriented tax.

The Myth of Left and Right: How the Political Spectrum Misleads and Harms America

I prefer a good short book to a good long book and this audiobook very much justifies the time it took to read (4 hours).

If you frequently talk about or think about US politics, I would recommend reading this book. The authors make a solid case that we do a disservice to political discourse when we use the words “left”, “right”, “liberal”, and “conservative”.

Uncommon Sense Teaching: Practical Insights in Brain Science to Help Students Learn

Much of this book was review for me: namely interleaved versus blocked practice, active versus passive learning, elaboration, and spaced repetition. Even the parts that were review were helpful to hear again. I also took notes from this book about “learn it, link it”, dopamine hits, comprehension checks, and pauses to consolidate.

This book included quite a bit more discussion about how the brain actually works than I remember hearing in previous books I’ve read on learning and teaching. It could be that these sections were simply more memorable than previous explanations I’ve heard, as the explanations in this book heavily relied on memorable analogies and stories.

Not the End of the World: How We Can Be the First Generation to Build a Sustainable Planet

This book discusses what we focus on too much and too little when it comes to the problems and the solutions around climate change. Hannah Ritchie calls out falsehoods and misconceptions, but she doesn’t berate believers of these misconceptions.

We all care about solving global warming and sustainability. Knowing more of the facts behind these concepts is the first step to working solutions.

This book definitely falls into the “skepticism over cynicism” category that I very much appreciate, as it inspires action instead of of encouraging inaction.

If you enjoy a Scottish accent, listen to the audiobook (Hannah Ritchie self-narrates).

Determined: A Science of Life without Free Will

Before reading this book, I hadn’t considered that free will comes in shades and that as a society we have been gradually chipping away at the magnitude of free will we collectively believe in.

The first 9 chapters (especially 5 through 9) are a bit of a slog, as each focuses on disputing a different argument for free will. I found the final 5 chapters (which focus on “what do we do if there’s no free will”) the most interesting.

Eating Animals

This book was memorable in a somewhat brutal way. I do not recommend reading this book while eating animal products, but I would recommend reading it.

There’s quite a bit of navel-gazing, but also quite a few interviews with many a number of folks in and around the animal farming industry.

For a more hopeful take on animal welfare, see the book The End of Animal Farming (mentioned above). Also see the book Why We Love Dogs, Eat Pigs, and Wear Cows (also mentioned above)

Where to buy audiobooks (not Audible)

Interested in listening to these in audiobook form?

Don’t buy them from Audible.

Whenever possible, I recommend avoiding Audible because:

1. Audible doesn’t sell audiobooks; they sell the ability to play audiobooks through their app
2. Audible credits expire and also disappear upon cancellation, which is an awful dark pattern

Cory Doctorow has written about his dislike of Audible and has recorded an audiobook against Audible (which is ironically also on Audible).

If you enjoy audiobooks and pro-consumer practices, I recommend trying out Libro.fm (that’s a referral link which will give me one free audiobook if you subscribe).

Unfortunately, a few of my favorite audiobooks noted above are only available on Audible.

You can purchase all of the above books on Libro.fm except for Hive Minds Give Good Hugs, Recoding America, and Walkable City. The book Land is a Big Deal is technically available outside of Audible, but I’ve only found it available for direct purchase from the publisher and it’s much more expensive that way.

For most of my audiobook-listening, I subscribe to Libro.fm, checkout books from my local library with Libby, and I’ve also used Spotify to listen to a few shorter books. For Audible-only books, I sign up for a subscription, buy licenses until my credit balance is 0, and then cancel.

Have a recommendation?

Have a question? Have an audiobook recommendation for me?

Comment below.

It’s so easy to throw together a single-file Python command-line script and throw it in my ~/bin directory!

Well… it’s easy, unless the script requires anything outside of the Python standard library.

Recently I’ve started using uv and my primary for use for it has been fixing Python’s “just manage the dependencies automatically” problem.

I’ll share how I’ve been using uv… first first let’s look at the problem.

A script without dependencies

If I have a Python script that I want to be easily usable from anywhere on my system, I typically follow these steps:

1. Add an appropriate shebang line above the first line in the file (e.g. #!/usr/bin/env python3)
2. Set an executable bit on the file (chmod a+x my_script.py)
3. Place the script in a directory that’s in my shell’s PATH variable (e.g. cp my_script.py ~/bin/my_script)

For example, here’s a script I use to print out 80 zeroes (or a specific number of zeroes) to check whether my terminal’s font size is large enough when I’m teaching:

1
2
3
4
5
6

#!/usr/bin/env python3
import sys

numbers = sys.argv[1:] or [80]
for n in numbers:
    print("0" * int(n))

This file lives at /home/trey/bin/0 so I can run the command 0 from my system prompt to see 80 0 characters printed in my terminal.

This works great! But this script doesn’t have any dependencies.

The problem: a script with dependencies

Here’s a Python script that normalizes the audio of a given video file and writes a new audio-normalized version of the video to a new file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

"""Normalize audio in input video file."""
from argparse import ArgumentParser
from pathlib import Path

from ffmpeg_normalize import FFmpegNormalize


def normalize_audio_for(video_path, audio_normalized_path):
    """Return audio-normalized video file saved in the given directory."""
    ffmpeg_normalize = FFmpegNormalize(audio_codec="aac", audio_bitrate="192k", target_level=-17)
    ffmpeg_normalize.add_media_file(str(video_path), audio_normalized_path)
    ffmpeg_normalize.run_normalization()


def main():
    parser = ArgumentParser()
    parser.add_argument("video_file", type=Path)
    parser.add_argument("output_file", type=Path)
    args = parser.parse_args()
    normalize_audio_for(args.video_file, args.output_file)


if __name__ == "__main__":
    main()

This script depends on the ffmpeg-normalize Python package and the ffmpeg utility. I already have ffmpeg installed, but I prefer not to globally install Python packages. I install all Python packages within virtual environments and I install global Python scripts using pipx.

At this point I could choose to either:

1. Create a virtual environment, install ffmpeg-normalize in it, and put a shebang line referencing that virtual environment’s Python binary at the top of my script file
2. Turn my script into a pip-installable Python package with a pyproject.toml that lists ffmpeg-normalize as a dependency and use pipx to install it

That first solution requires me to keep track of virtual environments that exist for specific scripts to work. That sounds painful.

The second solution involves making a Python package and then upgrading that Python package whenever I need to make a change to this script. That’s definitely going to be painful.

The solution: let uv handle it

A few months ago, my friend Jeff Triplett showed me that uv can work within a shebang line and can read a special comment at the top of a Python file that tells uv which Python version to run a script with and which dependencies it needs.

Here’s a shebang line that would work for the above script:

1
2
3
4
5
6
7

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "ffmpeg-normalize",
# ]
# ///

That tells uv that this script should be run on Python 3.12 and that it depends on the ffmpeg-normalize package.

Neat… but what does that do?

Well, the first time this script is run, uv will create a virtual environment for it, install ffmpeg-normalize into that venv, and then run the script:

1
2
3
4
5

$ normalize
Reading inline script metadata from `/home/trey/bin/normalize`
Installed 4 packages in 5ms
usage: normalize [-h] video_file output_file
normalize: error: the following arguments are required: video_file, output_file

Every time the script is run after that, uv finds and reuses the same virtual environment:

1
2
3
4

$ normalize
Reading inline script metadata from `/home/trey/bin/normalize`
usage: normalize [-h] video_file output_file
normalize: error: the following arguments are required: video_file, output_file

Each time uv runs the script, it quickly checks that all listed dependencies are properly installed with their correct versions.

Another script I use this for is caption, which uses whisper (via the Open AI API) to quickly caption my screencasts just after I record and edit them. The caption quality very rarely need more than a very minor edit or two (for my personal accent of English at least) even for technical like “dunder method” and via the API the captions generate very quickly.

See the inline script metadata page of the Python packaging users guide for more details on that format that uv is using (honestly I always just copy-paste an example myself).

uv everywhere?

I haven’t yet fully embraced uv everywhere.

I don’t manage my Python projects with uv, though I do use it to create new virtual environments (with --seed to ensure the pip command is available) as a virtualenvwrapper replacement, along with direnv.

I have also started using uv tool as a pipx replacement and I’ve considered replacing pyenv with uv.

uv instead of pipx

When I want to install a command-line tool that happens to be Python powered, I used to do this:

1

$ pipx countdown-cli

Now I do this instead:

1

$ uv tool install countdown-cli

Either way, I end up with a countdown script in my PATH that automatically uses its own separate virtual environment for its dependencies:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

$ countdown --help
Usage: countdown [OPTIONS] DURATION

  Countdown from the given duration to 0.

  DURATION should be a number followed by m or s for minutes or seconds.

  Examples of DURATION:

  - 5m (5 minutes)
  - 45s (45 seconds)
  - 2m30s (2 minutes and 30 seconds)

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

uv instead of pyenv

For years, I’ve used pyenv to manage multiple versions of Python on my machine.

1

$ pyenv install 3.13.0

Now I could do this:

1

$ uv python install --preview 3.13.0

Or I could make a ~/.config/uv/uv.toml file containing this:

1

preview = true

And then run the same thing without the --preview flag:

1

$ uv python install 3.13.0

This puts a python3.13 binary in my ~/.local/bin directory, which is on my PATH.

Why “preview”? Well, without it uv doesn’t (yet) place python3.13 in my PATH by default, as this feature is currently in testing/development.

Self-installing Python scripts are the big win

I still prefer pyenv for its ability to install custom Python builds and I don’t have a preference between uv tool and pipx.

The biggest win that I’ve experienced from uv so far is the ability to run an executable script and have any necessary dependencies install automagically.

This doesn’t mean that I never make Python package out of my Python scripts anymore… but I do so much more rarely. I used to create a Python package out of a script as soon as it required third-party dependencies. Now my “do I really need to turn this into a proper package” bar is set much higher.

Learn Python by writing Python code ✍

We do not learn by putting information into the brain. Our brains simply don’t retain knowledge that way.

Learning happens from repeatedly attempting to retrieve information from the brain. When it comes to Python, that means writing Python code.

So unlike most Python courses, Python Jumpstart is not focused on watching videos and rewriting code seen within videos. Instead, this new Python course is based around learning Python by writing Python code.

How Python Jumpstart is structured 🔬

Python Jumpstart includes learning Python by solving 46 short Python exercises.

Before each exercise, you’ll watch a 5 minute video explaining a new Python topic. You’ll then attempt the exercise to put one or more Python topics into practice.

You won’t solve many of the exercises on your first try and that’s okay. These exercises are designed to be revisited a few times over the course of weeks, until you’re satisfied with your solution.

This is not a sprint 📆

This structured path to Python proficiency, includes:

• Carefully crafted exercises that build real understanding
• Short, detailed explanations that won’t waste your time
• A proven teaching approach that focuses on active learning
• Spaced repetition to help concepts stick

This is not a course for impatient or passive learners. Learning takes repetitive effort spaced over many days and this course is structured to embrace that fact.

If you spend 30 minutes on Python Jumpstart each day, I estimate that you’ll complete this course in about 7 weeks. You’ll spend the large majority of that time writing Python code.

This course will take time, but it will be time well-spent.

Launch week special: 50% off until December 2 ⏰

Through Monday December 2, 2024, you can get lifetime access to Python Jumpstart for $99. After this launch week, Python Jumpstart will be $199.

Ready to jumpstart your Python learning journey?

Get Python Jumpstart for $99

This is my seventh annual compilation of Python learning deals.

Lots of Python sales

Here are Python-related sales that are live right now:

• Python Jumpstart with Python Morsels: 50% off my brand new Python course, an introduction to Python that’s very hands-on ($99 instead of $199)
• Talk Python: the annual everything bundle includes all courses for $240
• Data School 40% off all Kevin’s courses or get a bundle with all 5 of his courses
• Matt Harrison: get 25% off with GIVING25 plus every purchase will open a product for a scholarship recipient
• Reuven Lerner: get 20% off Bamboo Weekly or 30% off any of his Weekly Python Exercise courses with code BF2024
• Brian Okken: is offering 20% off his courses with code TURKEYSALE2024
• Rodrigo 50% off Rodrigo’s all books bundle with code BF24
• Mike Driscoll: 35% off Mike’s Python books and courses with code BF24
• Test Driven: get the Flask course bundle for 30% off
• The Python Coding Place: 40% off The Python Coding Book and 40% off a lifetime membership to The Python Coding Place with code black2024
• Sundeep Agarwal: ~50% off Sundeep’s all book and Python bundles with code FestiveOffer
• Benjamin Bennett Alexander: 60% off his Mastering Python Fundamentals book with code BLACK60
• O'Reilly Media: 40% off the first year with code CYBERWEEK24 ($299 instead of $499)
• Matplotlib Journey: a Python dataviz course that has a pre-launch promo right now (69€ instead of 149€)
• Python Done Right: beta sale on this course ($99 instead of the eventual price of $299)
• Pragmatic Bookshelf: 40% off sale with code turkeysale2024
• No Starch: 35% off with code BLACKHATFRIDAY (Crash Course, Automate The Boring Stuff, etc.)
• Manning is offering 50% off if you buy two items

Even more sales

Also see Adam Johnson’s Django-related Deals for Black Friday 2024 for sales on Adam’s books, courses from the folks at Test Driven, Django templates, and various other Django-related deals.

And for non-Python/Django Python deals, see the Awesome Black Friday / Cyber Monday deals GitHub repository and the BlackFridayDeals.dev website.

If you know of another sale (or a likely sale) please comment below or email me.

Read more about Python Jumpstart

Want to read more about my new self-paced Intro to Python course that’s on sale? See this blog post on why I made Python Jumpstart and how it’s structured. Get it by Monday to save $100.

I’d like to share a secret feature within the Python 3.13 REPL which I’ve been finding useful recently: adding custom keyboard shortcuts.

This feature involves a PYTHONSTARTUP file, use of an unsupported Python module, and dynamically evaluating code.

In short, we may be getting ourselves into trouble. But the result is very neat!

Thanks to Łukasz Llanga for inspiring this post via his excellent EuroPython keynote talk.

The goal: keyboard shortcuts in the REPL

First, I’d like to explain the end result.

Let’s say I’m in the Python REPL on my machine and I’ve typed numbers =:

1

>>> numbers =

I can now hit Ctrl-N to enter a list of numbers I often use while teaching (Lucas numbers):

1

numbers = [2, 1, 3, 4, 7, 11, 18, 29]

That saved me some typing!

Getting a prototype working

First, let’s try out an example command.

Copy-paste this into your Python 3.13 REPL:

1
2
3
4
5
6
7
8
9
10
11

from _pyrepl.simple_interact import _get_reader
from _pyrepl.commands import Command

class Lucas(Command):

    def do(self):
        self.reader.insert("[2, 1, 3, 4, 7, 11, 18, 29]")

reader = _get_reader()
reader.commands["lucas"] = Lucas
reader.bind(r"\C-n", "lucas")

Now hit Ctrl-N.

If all worked as planned, you should see that list of numbers entered into the REPL.

Cool! Now let’s generalize this trick and make Python run our code whenever it starts.

But first… a disclaimer.

Here be dragons 🐉

Notice that _ prefix in the _pyrepl module that we’re importing from? That means this module is officially unsupported.

The _pyrepl module is an implementation detail and its implementation may change at any time in future Python versions.

In other words: _pyrepl is designed to be used by Python’s standard library modules and not anyone else. That means that we should assume this code will break in a future Python version.

Will that stop us from playing with this module for the fun of it?

It won’t.

Creating a PYTHONSTARTUP file

So we’ve made one custom key combination for ourselves. How can we setup this command automatically whenever the Python REPL starts?

We need a PYTHONSTARTUP file.

When Python launches, if it sees a PYTHONSTARTUP environment variable it will treat that environment variable as a Python file to run on startup.

I’ve made a /home/trey/.python_startup.py file and I’ve set this environment variable in my shell’s configuration file (~/.zshrc):

1

export PYTHONSTARTUP=$HOME/.python_startup.py

To start, we could put our single custom command in this file:

1
2
3
4
5
6
7
8
9
10
11
12
13

try:
    from _pyrepl.simple_interact import _get_reader
    from _pyrepl.commands import Command
except ImportError:
    pass  # Not in the new pyrepl OR _pyrepl implementation changed
else:
    class Lucas(Command):
        def do(self):
            self.reader.insert("[2, 1, 3, 4, 7, 11, 18, 29]")

    reader = _get_reader()
    reader.commands["lucas"] = Lucas
    reader.bind(r"\C-n", "lucas")

Note that I’ve stuck our code in a try-except block. Our code only runs if those _pyrepl imports succeed.

Note that this might still raise an exception when Python starts if the reader object’s command attribute or bind method change in a way that breaks our code.

Personally, I’d like to see those breaking changes occur print out a traceback the next time I upgrade Python. So I’m going to leave those last few lines without their own catch-all exception handler.

Generalizing the code

Here’s a PYTHONSTARTUP file with a more generalized solution:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

try:
    from _pyrepl.simple_interact import _get_reader
    from _pyrepl.commands import Command
except ImportError:
    pass
else:
    # Hack the new Python 3.13 REPL!
    cmds = {
        r"\C-n": "[2, 1, 3, 4, 7, 11, 18, 29]",
        r"\C-f": '["apples", "oranges", "bananas", "strawberries", "pears"]',
    }
    from textwrap import dedent
    reader = _get_reader()
    for n, (key, text) in enumerate(cmds.items(), start=1):
        name = f"CustomCommand{n}"
        exec(dedent(f"""
            class _cmds:
                class {name}(Command):
                    def do(self):
                        self.reader.insert({text!r})
                reader.commands[{name!r}] = {name}
                reader.bind({key!r}, {name!r})
        """))
    # Clean up all the new variables
    del _get_reader, Command, dedent, reader, cmds, text, key, name, _cmds, n

This version uses a dictionary to map keyboard shortcuts to the text they should insert.

Note that we’re repeatedly building up a string of Command subclasses for each shortcut, using exec to execute the code for that custom Command subclass, and then binding the keyboard shortcut to that new command class.

At the end we then delete all the variables we’ve made so our REPL will start the clean global environment we normally expect it to have:

1
2
3
4

Python 3.13.0 (main, Oct  8 2024, 10:37:56) [GCC 11.4.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> dir()
['__annotations__', '__builtins__', '__cached__', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__spec__']

Is this messy?

Yes.

Is that a needless use of a dictionary that could have been a list of 2-item tuples instead?

Yes.

Does this work?

Yes.

Doing more interesting and risky stuff

Note that there are many keyboard shortcuts that may cause weird behaviors if you bind them.

For example, if you bind Ctrl-i, your binding may trigger every time you try to indent. And if you try to bind Ctrl-m, your binding may be ignored because this is equivalent to hitting the Enter key.

So be sure to test your REPL carefully after each new binding you try to invent.

If you want to do something more interesting, you could poke around in the _pyrepl package to see what existing code you can use/abuse.

For example, here’s a very hacky way of making a binding to Ctrl-x followed by Ctrl-r to make this import subprocess, type in a subprocess.run line, and move your cursor between the empty string within the run call:

1
2
3
4
5
6
7
8
9
10
11
12

class _cmds:
    class Run(Command):
        def do(self):
            from _pyrepl.commands import backward_kill_word, left
            backward_kill_word(self.reader, self.event_name, self.event).do()
            self.reader.insert("import subprocess\n")
            code = 'subprocess.run("", shell=True)'
            self.reader.insert(code)
            for _ in range(len(code) - code.index('""') - 1):
                left(self.reader, self.event_name, self.event).do()
reader.commands["subprocess_run"] = _cmds.Run
reader.bind(r"\C-x\C-r", "subprocess_run")

What keyboard shortcuts are available?

As you play with customizing keyboard shortcuts, you’ll likely notice that many key combinations result in strange and undesirable behavior when overridden.

For example, overriding Ctrl-J will also override the Enter key… at least it does in my terminal.

I’ll list the key combinations that seem unproblematic on my setup with Gnome Terminal in Ubuntu Linux.

Here are Control key shortcuts that seem to be complete unused in the Python REPL:

• Ctrl-N
• Ctrl-O
• Ctrl-P
• Ctrl-Q
• Ctrl-S
• Ctrl-V

Note that overriding Ctrl-H is often an alternative to the backspace key

Here are Alt/Meta key shortcuts that appear unused on my machine:

• Alt-A
• Alt-E
• Alt-G
• Alt-H
• Alt-I
• Alt-J
• Alt-K
• Alt-M
• Alt-N
• Alt-O
• Alt-P
• Alt-Q
• Alt-S
• Alt-V
• Alt-W
• Alt-X
• Alt-Z

You can add an Alt shortcut by using \M (for “meta”). So r"\M-a" would capture Alt-A just as r"\C-a" would capture Ctrl-A.

Here are keyboard shortcuts that can be customized but you might want to consider whether the current default behavior is worth losing:

• Alt-B: backward word (same as Ctrl-Left)
• Alt-C: capitalize word (does nothing on my machine…)
• Alt-D: kill word (delete to end of word)
• Alt-F: forward word (same as Ctrl-Right)
• Alt-L: downcase word (does nothing on my machine…)
• Alt-U: upcase word (does nothing on my machine…)
• Alt-Y: yank pop
• Ctrl-A: beginning of line (like the Home key)
• Ctrl-B: left (like the Left key)
• Ctrl-E: end of line (like the End key)
• Ctrl-F: right (like the Right key)
• Ctrl-G: cancel
• Ctrl-H: backspace (same as the Backspace key)
• Ctrl-K: kill line (delete to end of line)
• Ctrl-T: transpose characters
• Ctrl-U: line discard (delete to beginning of line)
• Ctrl-W: word discard (delete to beginning of word)
• Ctrl-Y: yank
• Alt-R: restore history (within history mode)

What fun have you found in _pyrepl?

Find something fun while playing with the _pyrepl package’s inner-workings?

I’d love to hear about it! Comment below to share what you found.

You’re really looking forward to using the new REPL… but python manage.py shell just shows the same old Python REPL. What gives?

Well, Django’s management shell uses Python’s code module to launch a custom REPL, but the code module doesn’t (yet) use the new Python REPL.

So you’re out of luck… or are you?

How stable do you need your shell command to be?

The new Python REPL’s code lives in a _pyrepl package. Surely there must be some way to launch the new REPL using that _pyrepl package!

First, note the _ before that package name. It’s _pyrepl, not pyrepl.

Any solution that relies on this module may break in future Python releases.

So… should we give up on looking for a solution, if we can’t get a “stable” one?

I don’t think so.

My shell command doesn’t usually need to be stable in more than one version of Python at a time. So I’m fine with a solution that attempts to use the new REPL and then falls back to the old REPL if it fails.

A working solution

So, let’s look at a working solution.

Stick this code in a management/commands/shell.py file within one of your Django apps:

1
2
3
4
5
6
7
8
9
10

"""Python 3.13 REPL support using the unsupported _pyrepl module."""
from django.core.management.commands.shell import Command as BaseShellCommand


class Command(BaseShellCommand):
    shells = ["ipython", "bpython", "pyrepl", "python"]

    def pyrepl(self, options):
        from _pyrepl.main import interactive_console
        interactive_console()

How it works

Django’s shell command has made it very simple to add support for your favorite REPL of choice.

The code for the shell command loops through the shells list and attempts to run a method with that name on its own class. If an ImportError is raised then it attempts the next command, stopping once no exception occurs.

Our new command will try to use IPython and bpython if they’re installed and then it will try the new Python 3.13 REPL followed by the old Python REPL.

If Python 3.14 breaks our import by moving the interactive_console function, then an ImportError will be raised, causing us to fall back to the old REPL after we upgrade to Python 3.14 one day. If instead, the interactive_console function’s usage changes (maybe it will require arguments) then our shell command will completely break and we’ll need to manually fix it when we upgrade to Python 3.14.

What’s so great about the new REPL?

If you’re already using IPython or BPython as your REPL and you’re enjoying them, I would stick with them.

Third-party libraries move faster than Python itself and they’re often more feature-rich. IPython has about 20 years worth of feature development and it has features that the built-in Python REPL will likely never have.

If you’re using the default Python REPL though, this new REPL is a huge upgrade. I’ve been using it as my default REPL since May and I love it. See my screencast on Python 3.13 for my favorite features in the new REPL.

P.S. for Python Morsels users: if you want to try using that code module, check out the (fairly advanced) replr or (even more advanced) replsync exercises.