[ python-Bugs-1343671 ] Broken docs for os.removedirs

[SourceForge.net]

Bugs item #1343671, was opened at 2005-10-31 12:30
Message generated for change (Comment added) made by birkenfeld
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1343671&group_id=5470

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: None
Group: None
>Status: Closed
>Resolution: Fixed
Priority: 3
Submitted By: David Kågedal (d_kagedal)
Assigned to: Nobody/Anonymous (nobody)
Summary: Broken docs for os.removedirs

Initial Comment:
The documentation for the os.removedirs function is
seriously broken.  This is from the library reference:

"removedirs(path)
    Removes directories recursively. Works like rmdir()
except that, if the leaf directory is successfully
removed, directories corresponding to rightmost path
segments will be pruned way until either the whole path
is consumed or an error is raised (which is ignored,
because it generally means that a parent directory is
not empty). Throws an error exception if the leaf
directory could not be successfully removed. New in
version 1.5.2."

The first sentence is the only part that makes any
sense. This shorter version contains as much
information and less misinformation"

"removedirs(path)
   Removes a directory and everything in it
recursively. If a file couldn't be removed, the removal
is aborted and you might get an exception if you're lucky."

The doc string you get when you type
"help(os.removedirs)" is different from the one in the
library reference, but equally broken.

----------------------------------------------------------------------

>Comment By: Reinhold Birkenfeld (birkenfeld)
Date: 2005-12-17 18:31

Message:
Logged In: YES 
user_id=1188172

Fixed the docs in rev. 41734/41735.

----------------------------------------------------------------------

Comment By: David Kågedal (d_kagedal)
Date: 2005-11-13 22:11

Message:
Logged In: YES 
user_id=1260741

> Are you sure you understand how the function works?

No I'm not.  But that's the whole point of this bug report.
 Reading the documentation didn't help.

Saying "Removes directories recursively" means something
different to me than what you describe, so I think it's easy
to mislead already there.

When it sans that "rightmost path segments will be pruned
away", that doesn't tell me that anything will be removed
from the file system, does it?

My suggestion for new doc string wasn't meant to be
accepted, but more to describe what information the original
contained.

How about this then:

  Removes the given directory, just like rmdir().  In
addition, if the removal was successful, the parent
directories mentioned in the 'path' argument are removed if
they are now empty.  This is done by removing the last path
segment from the given path and trying to remove the
directory given by the remaining path, until there is
nothing left of the original path string.  No exception will
be raised while trying to remove parent directories.

----------------------------------------------------------------------

Comment By: Fredrik Lundh (effbot)
Date: 2005-11-12 16:54

Message:
Logged In: YES 
user_id=38376

(I've changed the docstring from "remove a leaf directory and
empty all intermediate ones" to "remove a leaf directory and
all empty intermediate ones".  both the docstring and the docs
could need some clarification, but the text you propose is not
really an improvement...)

----------------------------------------------------------------------

Comment By: Fredrik Lundh (effbot)
Date: 2005-11-12 16:49

Message:
Logged In: YES 
user_id=38376

Are you sure you understand how the function works?

Given "spam/egg/bacon", it first attempts to do an rmdir on
spam/egg/bacon.  If that fails, the function raises an
exception.  Otherwise, it proceeds to rmdir spam/egg and
spam. Errors during the latter stage are ignored.

If you want to remove directories whether they're empty or
not, use shutil.rmtree.

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1343671&group_id=5470