Just a quick note based on some of the discussion on the Doc-SIG list:
Some people are getting asked to convert their documentation contributions to
LaTeX themselves, and that *is* a barrier to contribution. I've generally
stated that I'm willing to perform conversion, making plain text / ReST
completely acceptable for documentation contributions. Others have commonly
converted plain text to LaTeX as well.
I'd like to make sure that Python committers know that this is reasonable; if
the only thing holding a contribution back is LaTeXification of
documentation, feel free to assign it to me for conversion. I do not want
LaTeX itself to cause us to lose documentation contributions; the hard part
for documentation really is getting good content. Hard workers shouldn't be
turned away. :-)
Fred L. Drake, Jr. <fdrake at acm.org>
At 10:27 AM 12/22/2005 +0100, Walter Dörwald wrote:
>Phillip J. Eby wrote:
> > [...]
> > If someone has examples of actual "Pythondoc" markup that don't translate
> > to reST, I'd be really interested in seeing them, just for my own
> > education. Of course, I'd also be curious how common such constructs are.
>I'm using XML markup for our packages. Examples can be found at
By "Pythondoc", I mean the LaTeX-based markup system being used for the
official Python documentation, not arbitrary methods of documentation for
>The source is definitely wordier than reST, but adding new markup is
>trivial. Take a look at
>http://www.livinglogic.de/Python/xist/Download.html and at the source at
>http://www.livinglogic.de/Python/xist/Download.htmlxsc. The download
>element automatically determines the size of the package. Source can be
>(search for "class download"). Would something like this be possible
The docutils toolchain converts reST input into a DOM, and allows arbitrary
transformation phases to be added to processing before conversion to
output. This includes processing of "directives", e.g. commands like:
.. include:: filename
And of interpreted text "roles", e.g. `Foobar`:class:.
It is not, however, a general XML transformation toolkit, if that's what
you're asking. However, if you wanted to be able to use XML input as part
of a docutils DOM, you could certainly do that. For that matter, you could
take a reST document and simply transform it to XML for use with the rest
of your toolset.
But this isn't particularly relevant to the discussion about *Python's*
documentation, and I'm not even advocating that Python switch, let alone
arbitrary other projects.
Yesterday, I needed to make a web request in a program (actually a test)
that could block indefinately, so I needed to set a socket timeout.
Unfortunately, AFAICT none of urllib, urllib2, httplib provide options to set
the timeout on the sockets they use. I ended up having to roll my own
code to make the request.
It would be nice if high-level network modules, like the ones mentioned
above, had options to provide a timeout. (For example, urlopen could
grow an optional timout argument.)
If we think this is a good idea, then someone who has time could start chipping
away at it. I'm happy to work on this *if* I can find time. This would make
a nice easy sprint project at PyCon too.
Jim Fulton mailto:email@example.com Python Powered!
CTO (540) 361-1714 http://www.python.org
Zope Corporation http://www.zope.comhttp://www.zope.org
> My own favorite idea is to create a comment-on-the-docs mechanism
> allowing both COMMENTS, and PROPOSED EDITS.
Fred Drake replies:
> I'm unclear on what you buy with having these two labels; are comments things
> that (presumably) get ignored by the documentation editor, or are the
> proposed edits simply more specific?
Things that get ignored by the doc editors.
> (I'm also concerned that the whole thing could end up being misused as a help
> desk, littering the docs with questions about application problems.)
Me too. Specifically, I think if you make it really easy to write notes
on the docs you will get some helpful documentation content. You will
also get lots of things that are too lengthy or exhaustive, to specific
to one person's problem, helpdesk style questions, and probably spam. All
I meant was to allow the contributor to specify which category they think
this particular note belongs to so the doc editors can read only the ones
that people thought ought to be included in the docs.
-- Michael Chermside
I just submitted Patch #1388073, designed to make unittest's TestCase
class easier to subclass, and I'd appreciate a review of/feedback on
the code there.
While recently working on a subclass of unittest.TestCase to support
TODO-tests, I found a large number of __-prefixed attributes in
TestCase. The presence of these attributes meant that I had to copy
several methods over to my new subclass in order for things to work.
The patch I've provided converts these __-prefixed attributes to
_-prefixed attributes, making it much simpler to subclass TestCase.
The patch is against unittest.py from SVN revision 41775.
Included with the patch are "before" and "after" versions of my
subclass showing the impact of the change to unittest.TestCase.
Steve Holden writes:
> Could the PSF help here by offering annual prizes for the best
> contributions to the documentation, or wouldn't that be an adequate
Money is not a very effective motivator for this sort of work. (Well,
in sufficient quantities it is, but the quantities required are
quite large.) Offering *credit* is more effective -- a mention within
a contributors list perhaps. Even more effective is offering the
chance to make a difference: immediate feedback (seeing your edit in
place). Thus, I'm a big fan of amk's suggestion:
> I think the most effective thing would be [...]
> to build a real comment-on-the-docs system.
But I agree strongly with Fred's concerns:
> he was worried about whether
> anyone would garden the comments to remove spam.
and as Michael Hudson put it:
> Writing good documentation is hard.
> And sometimes the problem is that the document isn't really structured
> right, or it has been hastily updated to cover too many changes that
> it's a dogs breakfast, or some other 'global' problem and these
> *really* take time to fix.
My own favorite idea is to create a comment-on-the-docs mechanism
allowing both COMMENTS, and PROPOSED EDITS. The proposed edits would
need to be reviewed by one of a small number of skilled and dedicated
editors (Fred Drake... you're a hero!) before being officially
incorporated. That's not all that different from the current system
(submit a patch to sourceforge), except that the format for entering
the change would be simpler.
Of course, the person who REALLY gets to decide how it works isn't me;
it's whoever decides to spend the time to BUILD this system.
-- Michael Chermside
Josiah Carlson writes:
> New superclasses for all built-in types (except for string and unicode,
> which already subclass from basestring).
> int, float, complex (long) : subclass from basenumber
> tuple, list, set : subclass from basesequence
> dict : subclass from basemapping
> The idea is that each of the above classes define a group in which items
> are comparable.
Nick Coghlan writes:
> Close enough to on-topic to stay here, I think. However, I tend to think of
> the taxonomy as a little less flat:
> basecontainer (anything with __len__)
> - set
> - basemapping (anything with __getitem__)
> - dict
> - basesequence (anything which understands x[0:0])
> - list
> - tuple
> - string
> - unicode
> - basearray (anything which understands x[0:0,])
> - Numeric.array/scipy.array
Hold on a sec folks!
I really don't understand why we are trying to build a taxonomy of
container classes. There are some languages which have rather elaborate
taxonomys of container classes. The STL comes to mind, Smalltalk (I
think), even Java's collection classes are somewhat elaborate. But this
is NOT how things have been done in the Python world. We believe that
flat is better than nested. We believe in one simple-and-obvious way
to do things. For goodness sakes, we don't even have a basic
linked-list type because we figure it's simpler to make people just use
the single well-tuned array-list implementation.
Furthermore, I AGREE with this choice. I realize that in THEORY, a list
is simply a bag with the extra feature of ordering, and that a list you
can iterate backward is just an iterate-only-forwards list with an extra
feature. But I have never found it USEFUL in practice. In languages that
support it, I hardly ever find myself saying "well, I'm planning to pass
a list, but this method really only needs a bag... it doesn't matter
whether it is ordered", then later finding that this made it easy to
re-use the method when I had some other bag implementation. Frankly, I
find this sort of re-use MORE likely in Python simply because of support
for duck typing.
So I have a counter-proposal. Let's NOT create a hierarchy of abstract
base types for the elementary types of Python. (Even basestring feels
like a minor wart to me, although for now it seems like we need it.) If
the core problem is "how do you create a canonical ordering for objects
that survives serialization and deserialization into a different VM?",
then somehow abstract base types doesn't seem like the most obvious
solution. And if that's not the problem we're trying to solve here, then
what IS? Because I don't know of very many ACTUAL (as opposed to
theoretical) use cases for abstract base classes of fundamental types.
-- Michael Chermside
> - could a cronjob that does this be set up on some python.org machine
> (or on some volunteer's machine)
Palma de Mallorca PyPy Sprint: 23rd - 29th January 2006
The next PyPy sprint is scheduled to take place January 2006 in
Palma De Mallorca, Balearic Isles, Spain. We'll give newcomer-friendly
introductions and the focus will mainly be on current JIT work, garbage
collection, alternative threading models, logic programming and on
improving the interface with external functions. To learn more about the
new Python-in-Python implementation look here:
Goals and topics of the sprint
In Gothenburg we have made some first forays into the interesting topics
of Just-in-Time compilation. In Mallorca we will continue that
and have the following ideas:
- Further work/experimentation toward Just-In-Time Compiler generation,
which was initiated with the Abstract Interpreter started in
- Integrating our garbage collection toolkit with the backends and the
- Heading into the direction of adding logic programming to PyPy.
- Optimization work: our threading implementation is still incredibly
slow, we need to work on that. Furthermore there are still quite
some slow places in the interpreter that could be improved.
- getting the socket module to a more complete state (it is
already improved but still far from complete)
- generally improving the way we interface with external functions.
- whatever participants want to do with PyPy (please send
suggestions to the mailing list before to allow us to plan
and give feedback)
Location & Accomodation
The sprint will be held at the Palma University (UIB - Universitat de
les Illes Balears), in their GNU/Linux lab
(http://mnm.uib.es/phpwiki/AulaLinux). We are hosted by the Computer
Science department and Ricardo Galli is our contact person there,
helping with arranging facilities.
The University is located 7 km away from the central Palma. Busses to
the University departs from "Plaza de España" (which is a very central
location in Palma). Take bus 19 to the UIB campus. A ticket for one
urban trip costs 1 euro. You can also buy a card that is valid for 10
trips and costs 7.51 euros. Information about bus timetables and routes
can be found on:
A map over the UIB campus are can be found on:
The actual address is: 3r pis de l'Anselm Turmeda which can be found on
the UIB Campus map.
At "Plaza de España" there is a hostel (Hostal Residencia Terminus)
which has been recommended to us. It's cheap (ca 50 euros/double room
with bathroom). Some more links to accomodations (flats, student homes
If you want to find a given street, you can search here:
To get to Palma De Mallorca almost all low fare airlines and travel
agencies have cheap tickets to get there. Information about Mallorca and
Palma (maps, tourist information, local transports, recommended air
lines, ferries and much more) can be found on:
Comments on the weather: In January it is cold and wet on Mallorca
Average temperature: 8,4 degrees Celsius
Lowest temperature: 2 degrees Celsius
Highest temperature: 14,5 degrees Celsius
Average humidity rate: 77,6 %
So more time for coding and less time for sunbathing and beaches ;-)
The public PyPy sprint is held Monday 23rd - Sunday 29th January 2006.
Hours will be from 10:00 until people have had enough. It's a good idea
to arrive a day before the sprint starts and leave a day later. In the
middle of the sprint there usually is a break day and it's usually ok to
take half-days off if you feel like it.
For this particular break day, Thursday, we are invited to the studio of
Ginés Quiñonero, a local artist and painter. Ginés have also been the
person helping us getting connections to UIB and providing much
appreciated help regarding accommodation and other logistical
For those of you interested - here is his website where there also are
paintings showing his studio:
For those interested in playing collectable card games, this will also
be an opportunity to get aquainted with V:TES which will be demoed by
Ginés and Beatrice and Sten Düring. For more information on this
cardgame - see: http://www.white-wolf.com/vtes/index.php. (The Mallorca
sprint was organized through contacts within the V:TES community).
Network, Food, currency
Currency is Euro.
Food is available in the UIB Campus area as well as cheap restaurants in
You normally need a wireless network card to access the network, but we
can provide a wireless/ethernet bridge.
230V AC plugs are used in Mallorca.
Please subscribe to the `PyPy sprint mailing list`_, introduce yourself
and post a note that you want to come. Feel free to ask any questions
there! There also is a separate `Mallorca people`_ page tracking who is
already thought to come. If you have commit rights on codespeak then
you can modify yourself a checkout of
.. _`PyPy sprint mailing list`:
.. _`Mallorca people`:
Thomas (Heller) and I have been discussing whether the zlib
module should become builtin, atleast on Win32 (i.e. part
of python25.dll). This would simplify py2exe, which then could
bootstrap extraction from the compressed file just with
pythonxy.dll (clearly, zlib.pyd cannot be *in* the compressed
We currently don't do this, because the pythoncore.vcproj would
then not be buildable anymore unless you also have the right
version of zlib on disk.
To solve this, Thomas has proposed that the Python release could
incorporate a copy of zlib, primarily for use on Windows
(with the project files appropriately adjusted). I'm in favour
of such a change: the library is fairly small, and it would
not only simplify py2exe, but also simplify the build process.
Whether or not this copy of zlib would be integrated in the
Unix build process, in case where the system does not provide
a zlib, is a separate question.