[Doc-SIG] Undocumented modules
Guido van Rossum
Wed, 24 Feb 1999 12:31:23 -0500
> cmp DEPRECATE (seems to be duplicate of cmpcache)
> cmpcache DOCUMENT
No, cmpcache uses statcache.stat() while cmp uses os.stat(). But both
are borderline -- I wrote them when writing a visual diff for stdwin 7
or 8 years ago and haven't touched or used them since...
> codeop DOCUMENT
> colorsys DEPRECATE (very incomplete and possible
> inacurate, use PIL)
Hm... This incorporates quite a bit of arcane knowledge that was hard
to come by when we wrote it. I'm not sure where it is incomplete or
> fpformat DOCUMENT
Deprecate it; you can now do this using the % operator on strings.
> linecache DOCUMENT (potentially useful with
(Also used intensely by anything printing tracebacks.)
> mhlib DOCUMENT (has anyone tested this?)
Yes, I use it a lot, and just today I received some patches from a
mostly happy user in the newsgroup.
> mutex DOCUMENT
Hmm, this is very shady and seems to predate threads!
> pty DEPRECATE (VERY VERY platform specific)
But also very useful when it works. I'd like to keep it.
> rlcompleter INTERNAL (don't document)
Document it; it's actually useful. One needs to know to import this
in $PYTHONSTASRTUP, and one could subclass it to use different
> sched DOCUMENT
Like mutex -- not clear how useful this is.
> threading_api WHAT IS THIS?! (looks like docs for
Exactly. Should be deleted now that this is in the library manual.
> tty DEPRECATE (move to termios?)
Document -- it's a higher-level thing that could be useful.
> tzparse DOCUMENT
And someone should finish it!
> wave DEPRECATE (not sure honestly! :-)
Document! It reads/writes .wav sound files.
> ihooks - should this be in with the new module, it seems to be of the
> same class of "shoot yourself in the foot" modules :-) Perhaps we
> should have a "WARNING" label for modules that are especially dangerous
> to use?
Although less so -- "new" can easily cause core dumps, ihooks can just
screw cause tracebacks...
> caching things - has anyone actually tested these for performance? A
> quick check on my FreeBSD 3.0 box says they're slower than not caching
> because of (I assume) file system caching effeciency... Maybe that was
> a fluke, at least with statcache ;-)
Exactly how did you test it? This is needed especially when using
NFS, since stat over NFS is slow and synchronous.
> ERRNO DOCUMENT (I'd just reference the errno.h file)
Deprecate; we now have this and more in errno.
> As you've no doubt noticed, not much I don't say to document, BUT... I'm
> worried about all this HYPER specific IRIX stuff... perhaps it should
> be moved into it's own seperate documentation area, or even a seperate
> distribution of sorts (a'la Mac)... there's a ton of junk that just
> isn't useful for 99% of the users.
Agreed. There is already an SGI specific chapter that could easily be
lifeted out. Some of it is also very old and of questionable utility
in modern SGI systems (even if SGI survives :-).
--Guido van Rossum (home page: http://www.python.org/~guido/)