gh-126055: Add omitted command (in docs [os.walk]) for code to fulfill shutil.rmtree algorithm

[vwheeler63]

In ./Doc/library/os.rst, the section documenting os.walk() gives a code example at the bottom that says it is "a simple implementation of shutil.rmtree()". However it is incomplete. Reason: shutil.rmtree() also removes the passed directory whereas the code shown will not. This PR adds the last missing command to complete the algorithm and make the statement correct.

Resolves #126055

• Issue: os.walk() example of an implementation of shutil.rmtree() is incomplete #126055

---

📚 Documentation preview 📚: https://cpython-previews--126067.org.readthedocs.build/

[ghost]

All commit authors signed the Contributor License Agreement.

[picnixz]

Thanks for the clean PR!

This is one of the possible patches. Another possibility is to just mention that we are walking bottom-up but only mention that this is what shutil.rmtree needs to do.

The example is already dangerous as it is so I don't think it's an issue to also add the os.rmdir(top) in the example (I mean... you'd either end up with an empty directory or... no directory at all which, if you made a mistake, doesn't matter at that point).

cc @ncoghlan @barneygale as docs and pathlib experts (I don't have commit privileges so I cannot merge this PR).

[vwheeler63]

Thanks for the clean PR!

I'm honored:

1. to be talking with YOU (the maintainer of sphinx-doc!!), and
2. to be able to contribute to these docs (and maybe more later).

It happens that before I saw that section in the documentation, I had been playing with os.walk() myself before I ran into shutil.rmtree() -- in fact, I was in the process of refactoring some Python code in the docs-build for https://github.com/lvgl/lvgl/ (which builds with a fairly elaborate Doxygen => Sphinx+breathe combination), and built a test with os.walk() indeed to do a clean-up step at the end of the docs build. And found that I needed to explicitly remove the top directory after the loop. I didn't even know yet that similar code was in the https://docs.python.org/3.12/library/os.html page, so when I read the section on os.walk(), it jumped out at me since I had just been doing almost exactly the same thing in a test environment.

That said -- HELLO! I'm honored to be in touch with you. :-)

[vwheeler63]

@picnixz FYI, I just recently helped to untangle the first half of the LVGL library documentation, and am now in a big proofreading sequence to make it more friendly (I don't mind calling it Queen's English) to native-English C programmers.

By the way, I just saw the "This branch is out-of-date with the base branch" message come up. Do I need to rebase it on top of master?

[picnixz]

By the way, I just saw the "This branch is out-of-date with the base branch" message come up. Do I need to rebase it on top of master?

No need for that. We only rebase it if 1) there are conflicts that need to be fixed 2) to make the CI green if a fix has been pushed on main. (In general, docs PRs rarely need to be updated except for merge conflicts since they only trigger simple doc tests and not the entire test suite).

FYI, I just recently helped to untangle the first half of the

If you find any typos in Python documentation or if there are sentences that need to be improved, you're always welcome to make a PR out of it! or you can have a look at https://discuss.python.org/c/documentation/26 where the docs community discuss (maybe you can help them out there).

[vwheeler63]

No need for that.

Okay! I'm glad I asked. I had the impression that message indicating the merge was being blocked, but I am glad it isn't.

... you're always welcome to make a PR out of it!

I'm honored! Thank you!

I did find some real usability issues, but I believe it is really part of the design of the navigation-panel generation of the python-docs-theme. I see it has a "home" on GitHub as well!

Also: thank you for the link to the Python docs group! I'm checking it out now.

I haven't yet dived into how Sphinx themes work, but... I'm a 32-year veteran software developer (been working mostly in automotive firmware, close to the CPU [and supporting software] for the last 13 years), I'm a C master [+C#, VB.NET, optimization], heavily O-O trained (design & coding, by Bertrand Meyer himself [directly and indirectly]), and have been really enjoying learning Python lately. I'm also looking for paid work, in case you're aware of any opportunities that might be a good match for my skill set.

That said, with all that behind me, Sphinx themes should be a blast! 😄

[willingc]

Thanks @vwheeler63 for the PR. And congrats for the first commit!

Nice work @picnixz coaching on the PR and its review.

[vwheeler63]

Thanks @vwheeler63 for the PR. And congrats for the first commit!

I'm honored, Carol! **...and envious of your sphere of responsibility!** 😈 😃 👋

[miss-islington-app]

Thanks @vwheeler63 for the PR, and @willingc for merging it 🌮🎉.. I'm working now to backport this PR to: 3.12, 3.13.
🐍🍒⛏🤖

[bedevere-app]

GH-126199 is a backport of this pull request to the 3.13 branch.

[bedevere-app]

GH-126200 is a backport of this pull request to the 3.12 branch.

[vwheeler63]

Thanks @vwheeler63 for the PR, and @willingc for merging it 🌮🎉.. I'm working now to backport this PR to: 3.12, 3.13. 🐍🍒⛏🤖

I love the Monty Python references by the bot-apps.... 😃