A more compact pathlib summary#127911
A more compact pathlib summary #127911
Uh oh!
There was an error while loading. Please reload this page.
Conversation
bedevere-appbot added docs 
nedbatforce-pushed the nedbat/pathlib-summary branch from 72669dd to dc2c6aeCompare
- Removed class names and parameters from the summary - Used parentheses uniformly to indicate methods - Shortened some of the summary descriptions - Move "exceptions" to the end
nedbatforce-pushed the nedbat/pathlib-summary branch from dc2c6ae to ab7fc3aCompare
| -------------------------------------------------------------------------------------------------------------------------- | ||
| :meth:`copy() <Path.copy>` Copy this file or directory tree to the given *target* | ||
| :meth:`copy_into() <Path.copy_into>` Copy this file or directory tree into the given *target_dir* | ||
| :meth:`rename() <Path.rename>` Rename this file or directory to the given *target* |
There was a problem hiding this comment.
| :meth:`rename() <Path.rename>` Rename this file or directory to the given *target* | |
| :meth:`rename() <Path.rename>` Rename this file or directory to the given *target*. Raises an exception if the *target* already exists. |
I think is clarification would be good.
There was a problem hiding this comment.
We don't need to add this second sentence. This table is meant to help people find what they need, and then go read the full description. There are many reasons why a method could raise an exception. This doesn't need to be mentioned in the summary.
There was a problem hiding this comment.
Should we not differentiate between rename/replace as they share the first sentence which may be confusing?
There was a problem hiding this comment.
Sorry, now I see what you mean. Reading the full descriptions, it's even more subtle, and OS-specific. I would go with:
rename: Rename this path to the given target if possible. replace: Rename this path to the given target unconditionally. There was a problem hiding this comment.
I don't mind which one you go with both mine and yours get the point across.
Uh oh!
There was an error while loading. Please reload this page.
Nodd commented Mar 19, 2025
Thanks @nedbat for improving my work.
I can agree on the class names to reduce redundancy, even if I think that it can be less explicit and annoying when you're viewing the middle of a table and don't remember which class you're looking at. On the other hand I think that removing the parameters removes valuable information and is detrimental to understand the purpose of a function at a glance, and I'm not convinced that it's an improvement.
+1 for adding the missing parentheses.
+1
+1 |
4 participants
This is a reduced summary table, to help with smaller screens and to make the content more scannable.
Compared to #126342, I've:
📚 Documentation preview 📚: https://cpython-previews--127911.org.readthedocs.build/
Link to the pathlib preview: https://cpython-previews--127911.org.readthedocs.build/en/127911/library/pathlib.html#summary