Today I came across a doc issue about os.walk, cpython#111321, which I think would be best addressed by adding a new example to the docs with some narrative explanation.
That led to me thinking
I don’t want to embed such a long segment in os docs; it doesn’t belong with reference information
There are a lot of modules with similar scopes of action over the filesystem (minimally, os, shutil, glob, pathlib, and tempfile) for new pythonistas to learn
There are probably existing doc examples, across the stdlib, which would be better in separate narrative docs
What would the process for adding such a guide be? It can’t start with just one example.
I’m thinking that the right addition is something akin to the Logging Cookbook. I don’t think the FAQs are a good fit because they are intentionally sans-narrative and bite-sized. My idea is a little more ambitious.
Does this kind of “interacting with the filesystem” guide seem like a good idea? How would I bootstrap it with buy-in?
I think that would be a very valuable addition as this topic can pose a hurdle to newcomers evolving from limited hello-world samples to actually useful scripts
As the filesys modules partially overlap in functionality (no single obvious way to accomplish things), the page would need to show multiple equivalent how-to’s next to each other. Unless of course you want to guide people to the ‘best’ (open for debate) solution
for linking from the File and Directory library index if we add this!
I wouldn’t want to set either as the overall purpose of the doc because it depends on what kind of information we’re trying to communicate.
An example which explains os.fwalk vs os.walk shouldn’t compare the two to glob because it’s not topical. But a set of examples of “ways of traversing a directory tree” could show how os.walk and glob.glob differ.
The scope I have in mind is “patterns for using various modules to access the filesystem”, which is intentionally quite broad. Maybe too broad? I’d be open to feedback about what the appropriate focus would be for a “filesystem cookbook”.
Add it into the tutorial? Even if it starts as something of a cookbook, it can grow there to also carry intent and guidance.
We do have a range of modules for this and it’s likely not obvious to beginners which one they should use (spoiler: pathlib), or how to discover that the implications (and indeed, the intention) of __fspath__ is that you can use Path objects anywhere you might’ve used a string[1] and so it’s 100% okay to do with open(path_obj) as f: and not always use the methods.
I don’t even have to reach into the more complex cases of naming, long paths, sep vs pathsep, consistent wildcard handling for command line args[2], devices, WASI, etc. etc. to have enough content that it could be a very useful and beneficial tutorial section.
It just takes someone to get things started, and then other people will come in and fix things up So I’d say go ahead and make a tutorial page, leave some comments describing the kind of stuff that would be neat to include, put an “under development, contribute at : …” message in the doc itself, and put in the bits that you want.
Except sys.path… which happened to bite me yesterday. ↩︎
Since most Windows-based shells don’t expand * themselves, so the app has to do it. ↩︎
for linking from the File and Directory library index if we add this!
So I’d say go ahead and make a tutorial page, leave some comments describing the kind of stuff that would be neat to include, put an “under development, contribute at : …” message in the doc itself, and put in the bits that you want.