Re: [Python-Dev] Pydoc Improvements / Rewrite
At 12:16 AM 1/6/2007 -0500, Barry Warsaw wrote: >If you've already explained it, that's fine, but if not, could you >outline what you have against epydoc? The last I tried to work with it, it had even more hardcoded typechecking than pydoc does, spread out over more of the code base. Also, over at OSAF, I've been repeatedly called upon to sort out some peculiarity in how it discovers things or how it handles types it doesn't recognize. My net impression has been that it's very brittle, even more so than pydoc. On the plus side, there are some very good ideas and a *lot* of good execution in there, but its extensibility has historically struck me as non-existent. To be fair, the last time I had to deal with any problems with it at OSAF was almost a year ago, if memory serves. I don't know if anything has improved in it since then. The last time I seriously analyzed its internal architecture was several years ago (maybe 5?) when I was investigating it as an alternative to HappyDoc for doing PEAK's API documentation. I could never get it to work on anything but a small subset of PEAK without crashing in any of several ways, including segfaulting its GUI! It had built into it a variety of restrictive assumptions about how programs are structured that were not compatible with what I was doing. pydoc at least only crashed when dealing with metaclass instances, but I believe that was fixed in 2.3 or a late 2.2.x release. Anyway, I like the *idea* of epydoc and a lot of its execution, but IMO it needs just as much work as pydoc, if not more. ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Pydoc Improvements / Rewrite
Phillip J. Eby wrote:
> At 12:16 AM 1/6/2007 -0500, Barry Warsaw wrote:
>> If you've already explained it, that's fine, but if not, could you
>> outline what you have against epydoc?
>
> The last I tried to work with it, it had even more hardcoded typechecking
> than pydoc does, spread out over more of the code base. Also, over at
> OSAF, I've been repeatedly called upon to sort out some peculiarity in how
> it discovers things or how it handles types it doesn't recognize.
>
> My net impression has been that it's very brittle, even more so than pydoc.
>
> On the plus side, there are some very good ideas and a *lot* of good
> execution in there, but its extensibility has historically struck me as
> non-existent.
>
> To be fair, the last time I had to deal with any problems with it at OSAF
> was almost a year ago, if memory serves. I don't know if anything has
> improved in it since then.
FWIW, a 3.0a3 was released in August 2006, and according to the History,
"Significant portions of epydoc were written for version 3.0." It seems a lot of
that was to add parsing as a complementary means to extract documentation. I'm
not particularly familiar with the introspection code of either 2.1 or 3.0a3,
but a cursory examination shows that 3.0a3 has an introspecter registry that 2.1
doesn't:
# In epydoc.docintrospecter:
def register_introspecter(applicability_test, introspecter, priority=10):
"""
Register an introspecter function. Introspecter functions take
two arguments, a python value and a C{ValueDoc} object, and should
add information about the given value to the the C{ValueDoc}.
Usually, the first line of an inspecter function will specialize
it to a sublass of C{ValueDoc}, using L{ValueDoc.specialize_to()}:
>>> def typical_introspecter(value, value_doc):
... value_doc.specialize_to(SomeSubclassOfValueDoc)
...
@param priority: The priority of this introspecter, which determines
the order in which introspecters are tried -- introspecters with lower
numbers are tried first. The standard introspecters have priorities
ranging from 20 to 30. The default priority (10) will place new
introspecters before standard introspecters.
"""
--
Robert Kern
"I have come to believe that the whole world is an enigma, a harmless enigma
that is made terrible by our own mad attempt to interpret it as though it had
an underlying truth."
-- Umberto Eco
___
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] features i'd like [Python 3000] ... #3: fix super()
On 4 Dec 2006, at 3:13, Nick Coghlan wrote: > Ben Wing wrote: >> i don't like the current super() at all. having to type super(Foo, >> self).__init__(...) is messy, hard to remember, and error-prone. > > Yup. > >> it >> also introduces an unfortunate dependency in that the name of the >> class >> (Foo) has to be hard-coded in the call, and if you change the >> class name >> you also have to go and change all super() calls -- more chances for >> errors. as a result, i imagine there's a strong urge to just >> hardcode >> the name of the parent -- a bad idea, and the reason why super() was >> introduced in the first place. > > Also yup. > > The fact that these drawbacks are fairly obvious, yet nothing has > been done > about them should suggest something to you about the difficulty of > actually > solving this problem in a reliable fashion ;) > > The Python Cookbook has a few interesting approaches to making > cooperative > super calls easier to write, but they all tend to have some kind of > drawback > that makes them inappropriate for making part of the language core. > >> instead, `super' should work like in other languages. a couple of >> ideas: >> >> -- super.meth(args) calls the superclass method `meth', in the >> same way >> that super(Foo, self).meth(args) currently works. (this is the same >> syntax as in java. this probably requires making `super' be a >> keyword, >> although it might be possible to hack this by examining the >> current call >> stack.) > > It's the implementation that's the real sticking point here, so > without code > this idea isn't likely to go anywhere. I was bitten by the urge to play with this today, and modified my previous "self" hack to handle "super" also, so that the following code works: class D (C): @method def sum(n): return super.sum(n * 2) - self.base Posted as "evil2.py" here: http://www.lag.net/robey/code/surf/ Because hacking "super" requires having the class object handy, this one needs a metaclass to do its magic, which is a shame. I guess if it was implemented inside the cpython compiler, it would be less of a problem. robey ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] features i'd like [Python 3000] ... #3: fix super()
> I was bitten by the urge to play with this today, and modified my > previous "self" hack to handle "super" also, so that the following > code works: > > class D (C): > @method > def sum(n): > return super.sum(n * 2) - self.base > > Posted as "evil2.py" here: > > http://www.lag.net/robey/code/surf/ > > Because hacking "super" requires having the class object handy, this > one needs a metaclass to do its magic, which is a shame. I guess if > it was implemented inside the cpython compiler, it would be less of a > problem. BTW, a "super-only" version of this decortor (that I think could be called "implement") has some more chances in Python. But think belongs more to Python-Ideas list, ok? -- EduardoOPadoan (eopadoan->altavix::com) Bookmarks: http://del.icio.us/edcrypt Blog: http://edcrypt.blogspot.com Jabber: edcrypt at jabber dot org ICQ: 161480283 GTalk: eduardo dot padoan at gmail dot com MSN: eopadoan at altavix dot com ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Pydoc Improvements / Rewrite
Laurent Gautier wrote: > 2007/1/6, Ron Adam <[EMAIL PROTECTED]>: >> Laurent Gautier wrote: > [...] > 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). There really isn't as many html specific formatting functions as you might think since I used a very consistent format of css tagged definition lists. In the case of cgitb, it's probably better to copy those functions to it and just get rid of the dependency. If someone does put together a library of useful html functions and class's then pydoc, cgitb and other programs can use it. BTW, all the html specific functions and formatting have already been collected in the gethtml.py file. I've also added more comments to both gettext.py and gethtml.py last night, so it should be easier to see how it works. First look though gettext.py to get a general idea of how the info is collected and formatted in text, then look at gethtml.py. http://ronadam.com/dl/_pydoc.zip > 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. Yes, that would be good and may be needed, but it's still a ways off. Lets get it to work first, then if it gets approved for inclusion, then how to move it into the python distribution (with any needed changes needed for that) can be worked out. First things first, if you know what I mean. > [...] >> > 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. I'd like to know more about using the sandbox, I know it would be easy for people to read the source there, but who all can have write access to it without having write access to other python areas? I would not mind giving that a try if someone who already knows how could point me to the correct how-to documentation with some advice on what not to do. I'm actually more concerned about the what not to do stuff. I really would not like to clobber someone else's work or create problems because of my inexperience with CVS. >[...] >> 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 don't see this as taking a long time if we keep it to cleaning up with some API and user interface improvements. I know there are some here who want a smart parsing engine, which probably would take a long term commitment to maintain and fix bugs, etc. But lets look at the actual use's that pydoc serves first. Use's for pydoc in order of importance and frequency of use: 1. Console (builtin) help. ie.. the help() function. 2. HTML browsing and quick reference. 3. Document generation in text. 4. Document generation in html. 5. Document generation in other formats. (not currently possible) I'm concentrating on 1 and 2. Use cases 3 and 4 are just an easy to do byproduct of doing 1 and 2. I think the cleaning up may make doing 5 possible. Lets turn the question around. How well would other document generators supply pydoc with the equivalent text of the help() function, interactive help session output, and the equivalent html needed for dynamic html browsing? Also keep in mind
