[Doc-SIG] Undocumented modules

[Guido van Rossum]

>             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
inaccurate.

>             fpformat		DOCUMENT

Deprecate it; you can now do this using the % operator on strings.

>             linecache		DOCUMENT (potentially useful with
> 	    			fileinput)

(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
completion rules.

>             sched		DOCUMENT

Like mutex -- not clear how useful this is.

>             threading_api	WHAT IS THIS?! (looks like docs for
> 	    			threading.py)

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/)