Skip to content

Doc: Improve grammar in os.walk example #138466

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wjandrea wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Doc: Improve grammar in os.walk example #138466

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
69ff788
DOC: Typo in os.rst
wjandrea Sep 3, 2025
a1fdd53
Merge branch 'main' into patch-1
wjandrea Sep 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Doc/library/os.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3703,7 +3703,7 @@ features:
dirs.remove('__pycache__') # don't visit __pycache__ directories

In the next example (simple implementation of :func:`shutil.rmtree`),
walking the tree bottom-up is essential, :func:`rmdir` doesn't allow
walking the tree bottom-up is essential: :func:`rmdir` doesn't allow
Copy link
Copy Markdown
Member

@AA-Turner AA-Turner Sep 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

?

Suggested change
walking the tree bottom-up is essential: :func:`rmdir` doesn't allow
walking the tree bottom-up is essential, because :func:`rmdir` doesn't allow

Copy link
Copy Markdown
Contributor Author

@wjandrea wjandrea Sep 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, that's also a good suggestion, but fwalk already uses a colon:

cpython/Doc/library/os.rst

Lines 3767 to 3768 in 424e2ab

In the next example, walking the tree bottom-up is essential:
:func:`rmdir` doesn't allow deleting a directory before the directory is

So I used the same for consistency. No need to edit two spots when one will do, but if you think it would be clearer to add "because", by all means.

Another option is:

walking the tree bottom-up is essential since :func:`rmdir` doesn't allow

Copy link
Copy Markdown
Member

@ZeroIntensity ZeroIntensity Sep 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could also use a semicolon, but I like this more.

Copy link
Copy Markdown
Contributor Author

@wjandrea wjandrea Sep 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ZeroIntensity Yeah, a semicolon would fix the grammar, but using a colon does the same and implies "because".

Copy link
Copy Markdown
Member

@AA-Turner AA-Turner Sep 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Excess brevity is not called for here, I think 'because' is fine. Given it's immediately before a role that also starts with :, having the colon could be a little confusing.

Copy link
Copy Markdown
Member

@ZeroIntensity ZeroIntensity Sep 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No need to edit two spots when one will do, but if you think it would be clearer to add "because", by all means.

It's fine to have inconsistent styles -- English doesn't follow PEP 8 :)

deleting a directory before the directory is empty::

# Delete everything reachable from the directory named in "top",
Expand Down
Loading