Python Core Sprint 2024: Day 5

Datetime and Hypothesis

I reviewed some issues that came to the CPython repo. There were a few interesting tickets related to the datetime module. These issues were discovered by Hypothesis, a property-based testing tool for Python. I’ve been hearing a lot about Hypothesis, but never really used it in production or at work. I watched a talk about it at PyCon US many years ago, and I even had ice cream selfie with Zac who maintains Hypothesis. Anyway, I’ve just been interested in learning more about Hypothesis and how it could solve issues not caught by other testing methods, and I think this is one of the perks of contributing to open source: getting exposed to things you don’t normally use at work, and I think it’s a great way to learn new things.

These were the three issues I looked at during the last day of the sprint:

It seemed like this issue is related to the locale, and the operating system. The ticket says it is affecting Linux, so I tried it on my machine (macOS) and couldn’t replicate the issue. So hopefully, by sharing that it works on MacOS and not on Linux, it could help others to better diagnose it and to come up with a fix.

If you pass in \x00 (null-termination) to strftime, the parser treats it as “end of string”.

>>> from datetime import dateteime
>>> datetime(2024, 9, 25).strftime("\x00%Y-%m-%d")
""

In the above example, it simply prints an empty string and the rest of the format specifiers like %Y, %m, and %d were ignored.

As Paul said in the issue, I too would have expected it to print "\x002024-09-25", i.e. it should not have tried to parse other characters that are not datetime format specifiers. A PR for this has just been opened by Serhiy. (PR #124531)

Currently, if you try to pass datetime format like %Y%y (both are for representing “year”), only the last format specifier gets applied. For example:

>>> from datetime import datetime
>>> datetime.strptime("200099", "%Y%y")
datetime.datetime(1999, 1, 1, 0, 0)

In the above example, the passed-in string contains two year-formats: 2000 and 99. However, only the resulting datetime object is 1999.

I think this is a user error, they shouldn’t try to pass in two different year on the same datetime object. However, currently Python lets people do this without any warning. So in the ticket, Paul asked what we should do.

In my mind, at the very least we should document that only the last year format gets applied. But this also seems like inappropriate use of the function, so I think we should let user know when they’re trying to do something like this. So I’d recommend that we raise some kind of warning. What do you think? I’ve opened a PR to document it.

Modernizing Python Docs

I mentioned in my earlier blog post about unpopular Python Docs idea. I asked if anyone wanted to hear it out.

It’s something that I mentioned briefly during my “Changelong” keynote at PyOhio 2024, that the Python Docs haven’t evolved much in the last 20 years. We’ve been using the same infrastructure and tooling for a long time. And I just think it’s time for a change, though at that time, I don’t quite know what is this “change” would even look like.

So here’s my idea:

Python docs are built using Sphinx and reStructuredText. Both tools are Python-centric tools. They work great. There really are things that Sphinx and reStructuredText can do that other tools can’t. But there are also things that other tools are great at, that the current tooling can’t do.

If I were to simply say, “let’s update Python docs”, we’d probably be constrained to thinking about ideas and improvements based on what Sphinx/reStructuredText can do now. So I wanted to be thinking in a broader sense, and not be constrained by the current tooling. I wanted for us to think about what our documentation would look like, if we were to start from scratch today.

I really like the docs from Astro (a documentation framework). I learned about Astro from Cristián Maureira-Fredes, who mentioned it during one of PyLadiesCon planning meetings. And, the night before, when chatting with Dave Peck and Jim Baker, I shared this idea with them, and Dave actually said that he also uses Astro for his own blog, and he highly recommends it.

I just love Astro docs look like, and I really like the components like quiz and checklists in their tutorial to track the progress of the learner. That sort of interactivity is really cool.

So during the meeting at the sprint, with Hugo, Jelle, Petr, and Russell, I started by saying that I want Python docs to look more like what Astro docs look like, along with the interactive components, like quizzes and checklists. What can we do to go from what we have now, to there? I know it’s going to be a big change that takes time. I know it’s going to be a long-term project. So how can we make it one step closer to reality?

The group shared really good suggestions and insights.

  1. If not Sphinx, then which tool do we use?

Jumping from .rst to .md might be a bearable change, especially nowadays there are more documentation tool that support both Sphinx and Markdown, and there have been more third-party Python library that uses markdown for their docs.

But jumping from Python-based tool to JavaScript-based tool? You try saying this to 100+ Python core devs 😅 So what I need is a really strong case to show about what other tools can provide. And this is where I’m at.

Some things were mentioned:

  • Do some research to find the right tool. Is it Astro, or something else? What other tool can be used?
  • Whatever tool we use, it better be something that we can use for a long time, i.e. not an obscure tool that might be abandoned in a few years.
  1. Maybe just the tutorials could be hosted separately and be made with these interactive elements, instead of re-doing the entire Python docs.

I really like this idea! So maybe we should have something like official tutorials.python.org, an authoritative tutorials for Python.

At first, there was suggestion to just start such content as a third party, like on my personal repo, and if it gets traction, at that time I could propose to move it to the Python org.

I don’t think it is a good idea. There are already many Python tutorials written out there. You can even take Python tutorials from Udemy, Coursera, freecodecamp, etc. I don’t want to be creating another one of those. Meanwhile, Python itself has a tutorial section in the docs already. This is the tutorial that really needs improvement. If the tutorials are to be written for Python, then it should belong in the Python repo from the get-go.

Also, I can’t be writing good tutorials myself, I don’t have the skills for that. The community would need to help and participate and contribute. I can’t do an outreach effort asking people to contribute when the repo is on my personal repo.

I also want for anyone who contributes to this to be recognized as “core contributor” to Python, and not as a “community” contribution. So I’d like to see this effort to be an officially recognized activity by the core Python project, and therefore it should be hosted on the Python GitHub org.

I will be discussing this idea further with the Python Docs WG and the Python Docs Editorial board after the sprint.

Python Deprecation Workflow

After Brett brought up about Python deprecation policy the day prior, I realized that I never really know the full story or workflow for deprecating Python features. The only thing I was aware of was that we need to keep the DeprecationWarning for 2 releases, but how does it really work? How do we remember to remove the feature two releases from now? What docs do we need to write? How do we tell users about the deprecation? How will users become aware of the deprecation?

Adding new features are easy and fun, but removing and deprecating things are hard. When I read changelogs, I read the deprecation section first before the new features. So I just wanted to learn more of how this works in Python.

I was also reviewing a ticket for deprecating argparse.FileType type converter. As part of reviewing the PR, I figured that I should make sure that the proper deprecation process is being followed, but first I must learn about what the ‘proper’ process is.

I asked on Discord to get some answers. Turns out, all we have right now is the “deprecation policy” in PEP 387: Backwards Compatibility Policy, which is just an overall policy documentation, but not really a “how-to” guide for deprecation.

Based on answers from Discord, I’ve opened a devguide ticket to document the Deprecation Workflow.

Core.py podcast recording

The core.py podcast is one year old (it started after the last Python core sprint in Brno) and Meta prepared a birthday cake to celebrate.

We all got interviewed by Pablo and Łukasz for core.py podcast to share what we did at the sprint. The episode is already out. Listen to it to learn about what others at the sprint have been doing.

(My part starts at around 33:00)

Python conference t-shirts

Python conference/Python-themed t-shirts worn by Python core devs today:

  • PyCascades (Mariatta and Guido)
  • PyCon US 2022 (Greg)
  • PyCon US 2021 (Thomas)

Dinner

My family drove over to stay overnight on Friday. When they arrived, it was already 8:30 PM. We went to Kura Sushi, which features a revolving sushi bar. It was a very fun and unique experience!

Bonus Day 6: Family Outing in Seattle

We had brunch at Dough Zone, then we went to Pike Place Marketplace in Seattle. Spent 30 minutes charging the EV to 80% (28 USD) before we drove back home in the evening.

Thank you

Thank you Itamar Oren for organizing and coordinating the sprint. It was a great experience, and everything is very well organized. I really appreciate the effort you put into this.

Thank you Meta for hosting us! My first ever Python core sprint in 2017 was also at Meta in the Bay Area, but the room was much smaller (they called it the “War Room”) for 20 people. The sprint venue this time is much more spacious and comfortable. I really love it. Meta not only provided the venue, but also served us breakfast and lunch daily, as well as a fancy dinner on Thursday at Anthony’s HomePort Kirkland.

Thank you to other Meta employees who also supported us during the sprint: Dino Viehland, Jason Fried, Matt Page, Parul Gupta, and Thomas Wouters.

Thank you The PSF for covering the cost of my trip! The PSF paid for my hotel stay during the sprint (6 nights, I think it was about $1500 USD). We also received per diem meal allowances each day, and I was also reimbursed for mileage because my family drove over to pick me up (approx 450 kms roundtrip).

Thank you to all the core team members and triagers who participated in the sprint! It’s nice being able to just chat in real life and getting to know more about each other. I appreciate all the work you do for Python.

Thank you to folks who wore Python-themed shirts during the sprint! Buying and wearing Python conference t-shirts are great ways to show your support to the community. At the sprint, we’ve seen t-shirts from: PyCon US, PyCascades, PyCon Charlas, EuroPython, PyBay, PyCon CZ, PyLadies, PyLadies CZ, PyJogja, Python Pizza, and Black. If you want to t-shirt-twin with any of us, you know what to do. Go attend a regional Python conference near you, and buy their t-shirt. Pro-tip: Guido owns at least 5 PyCascades t-shirt. If you want to know when are the regional Python conferences happening, go check out the Python conferences GitHub repo.

Thank you to my GitHub sponsors As a self-employed independent consultant, I can’t bill my client for time away at the sprint. Having GitHub sponsors helps me afford taking the take time off to do things like this. I really appreciate your continued support. If you’re not yet a sponsor, why not start now?

The sprint has always been a great experience for me. I came thinking that I’d just be working on some docs, but I left with learning a lot more, and feeling inspired with ideas of how to improve Python. I really wish I could have more time to do these things for the community.

Anyway, I’m back home now and catching up on work and things before traveling again for another Python conference in a few weeks.

Thank you for reading!

Check out other great posts about the sprint: