[Python-Dev] Pydoc Improvements / Rewrite

Laurent Gautier lgautier at gmail.com
Sat Jan 6 03:21:41 CET 2007


2007/1/6, Ron Adam <rrr at ronadam.com>:
> Laurent Gautier wrote:
[cut]
>  >> I think any API issues could be worked out.  Are there any programs
>  >> you know of,
>  >> (yours?), that import pydoc besides the python console?
>  >
>  > What I did barely qualifies as a hack for my own usage -it won't count-.
>
> It could be these changes will give you a way to do the same thing in a less
> haskish way.
>

This precisely why I get myself into the present trouble ;-)

>  > From the top of my head, there might be  "ipython" (the excellent
>  > interactive console) is possibly using pydoc
>  > (in any case, I would say that the authors would be interested in
>  > developments with pydoc)
>
> According to the web site, ipython is based on twisted, and is currently still
> limited to python 2.3 and 2.4.  Also, the output of the help() function will not
> change much so I doubt it would be a problem for them.

Sorry for answering a bit off-the-question. My meaning was that they would be
interested in knowning that "pydoc" is changing (and would surely have ideas).

>  > Otherwise a quick search lead to:
>  > - "cgitb" (!? - it seems that the HTML formatting functions of pydoc
>  > are only in use - wouldn't these functions belong more naturally to
>  > "cgi" ?)
>
> Thanks!, These html formatting functions still exist or are small enough to move
> into cgitb, so it will be just a matter of making sure they can be reached.  I
> don't think they will be a problem.
>

I read your comment about having not too many things changed for 2.6.
(or that will be bumped to 3000).

A suggestion I would have would be to create an html/htmlrender module
in the pydoc-package-to-be and start putting all the html formatting function
(as they are completely independent of pydoc, as far as I can see, over there).
You can then create wrappers to the original functions including a deprecation
warning. You can refer to Michael Chermside's recipe for an example of
implementation with a deprecation decorator -
http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/391367
)
The suggestion above would actually apply to *anything* that is changed
in pydoc, providing the benefit of allowing the necessary changes while having
a temporary API to provide back-compatibility.


>
>  > - "DocXMLRPCServer" (hey ! it looks like kind-of what I was needing !!!).
>
> Thanks again.  This might be better to move into the pydoc package.  Any opinions?
>

We both pretty much agree, but now we've got to find the modules depending
on DocXMLRPCServer (and hope the recursion won't go on for too long). We
would also have to contact the author of DocXMLRPCServer (moving it would
go with potential changes, and he would certainly have suggestions about that).

>  > - "happydoc" (reportedly having problems with python 2.4 - I am not
>  > sure that it is maintained)
>
> Happydoc does not import pydoc as far as I could tell, so this won't effect them
> in any direct way I think.  They've pretty much implemented everything from
> scratch.  At worse they would just need to copy the parts from the older version
> into their distribution.
>
> I think you got a false positive on this because pydoc is a substring of happydoc.
>

Yes this was a false positive.
I kept it in the list thinking there might be interesting ideas there as well
(but I forget to label it as such - sorry for the confusion).

>  > "cgitb" and "DocXMLRPCServer" are both distributed bundled with Python.
>  >
>  > "cgitb" seems to be mostly using HTML formatting helpers (and that would
>  > suggest the need for an HTML-rendering module - may be for a future
>  > improvement,  a first step would be separate the rendering/viewing
>  > from extraction and modeling of documentation data).
>
> Making sure these still work would be a good sub project for someone a little
> later.  (I'll do it if no one else has time or wants to.)  I'm trying not to
> change thing to drastically.  If the changes are too big, ie... introducing and
> altering a lot of other modules.  Then this will need to move back to the
> python-3000 list.
>

I agree that altering a number of other modules would be a little
tricky to manage
for version 2.6, but I would think that the makeover of pydoc would
benefit from being made early (back-compatibility being ensured by the
deprecation decorator
mentioned above, for example).

>  > "DocXMLRPCServer" looks (at first sight), like a viewer that would be
>  > bundled
>  > with pydoc as a sub-module (i.e., module in a package).
>
> Yes, that was my thought too. :-)
>
> But moving it may need to wait until python-3000.  (?)

An other way is to move it, while keeping a dummy module that imports the
module from its new location (and issue deprecation warnings).
What I fear is that the "let's wait for python-3000"  correspond to postponing
changes to "some other time".

[cut]
>  > I do not think it will work as a zip file shuttled around (in my
>  > experience).
>  > A versioning system would be extremely helpful (SVN, or CVS. would
>  > come to my mind).
>  > Well, if you are ok with having the source tree hosted in a
>  > SVN/CVS/alike I am on
>  > (opening an account on sourceforge or savannah -for example- would be
>  > the next step then, as it can take few days for a project to be
>  > approved)
>
> I don't have any experience with SVN, but it could be an opportunity to learn
> something new.  I have a couple of other projects that could benefit by moving
> them to SVN or CVS like system.

I have seen A.M.Kuching's suggestion about python's sandbox,
but I do not know if it would work in the short term. Anyway,
and at least for the long(er) term, it will make sense to favor SVN
over CVS (since this is what the python project is using). That rules
out savannah and leaves us with sourceforge.

> What I intended was to get enough feed back that I could get it to a point where
> it's 90% done and then upload it as a patch where it could be further polished
> up.  To do that, I first need to verify my design goals are the correct
> approach. (see my reply to Ka-Ping.)  If they are, then it's more a matter of
> cleaning up what I've already started.  If not, then it's a bit (or bunch) more
> work and would benefit from having others work on it in a more formal way.

No matter the number of developpers, it would give people interested in
following the developpements a convenient way to do it.

> If someone who has more experience with group projects would like to manage it,
> that would be good too.  That may speed things up considerably.

I have some experience in it (in companies, and in an open source project)
I can always file a application for a sourceforge project,
and can help you with managing it until you feel like taking it on your own
(or it is merged with the python trunk)
I am willing to contribute to the implementation (I suspect that
things like unit tests be needed).


>
>  > I will have a look then.
>
> Great.  :-)
>

I should have the time during the week-end. I will get back to you off-list.


Cheers,



L.


> Cheers,
>    Ron
>


More information about the Python-Dev mailing list