[Twisted-Python] Woven example for article, Part II
On Thu, 29 May 2003, david mertz <ibook@gnosis.cx> wrote:
To Andrew, and generally: I have installed a local copy of 1.0.5, and that at least makes the PicturePile example work (there are a few minor errors in the samples, but straightforward to fix)
Moshe Zadka wrote: |There is a reason the documentation comes with the package: |it is relevant to the version it comes with. In particular, the |documentation on tm.com is only relevant to "latest stable". This is |just like Python: if you read documentation from |http://www.python.org/doc/current/, don't count on it working with |Python 2.1. This is very unhelpful, Moshe. The documentation on the Twisted website (as mentioned in my earlier note), unlike most Python standard documentation, does not indicate in which versions the examples work (PicturePile, specifically). Nothing like "new in 1.0.4". Moreover, the errors did not make it obvious there was a version issue (and in any case, the example still needed some minor corrections to work with 1.0.5). Andrew's advice (and some by email) was helpful, but it was hardly obvious a priori what the issue was. Moreover, I have not encountered any change log that addresses woven version differences in any detail. Quite possibly there is such a document, but I do not now know where it is. None of this, btw., means to demean Twisted itself. I do think it could use a bit more directed documentation, but the concept and subpackages themselves seem very useful and well conceived. Yours, David...
On Thu, 29 May 2003 23:02:59 -0400 david mertz <ibook@gnosis.cx> wrote:
Moreover, I have not encountered any change log that addresses woven version differences in any detail. Quite possibly there is such a document, but I do not now know where it is.
The ChangeLog usually doesn't cover code that is unstable. In general, *always* use the latest version of Twisted. Certain parts are pretty stable (e.g. the networking core in twisted.internet), but other parts are under continous development. It's not good that the docs don't mention what's in a given version of Twisted, but we have enough work on our hands writing them and keeping them up to date. Typically, unless the module has a docstring saying the API is stable, it probably isn't. There will usually be a backwards compatability layer if changes are made, though. Woven's been pretty good about that, and is now settling down into stability. Twisted developers will typically develop off CVS, since we're always adding features we need for our own projects. -- Itamar Shtull-Trauring http://itamarst.org/ http://www.zoteca.com -- Python & Twisted consulting
Itamar Shtull-Trauring:
Typically, unless the module has a docstring saying the API is stable, it probably isn't. There will usually be a backwards compatability layer if changes are made, though. Woven's been pretty good about that, and is now settling down into stability.
How comfortable should I be with these modules? conch/__init__.py:This module is unstable. conch/authorizer.py:This module is unstable. conch/error.py:This module is unstable. conch/identity.py:This module is unstable. cred/authorizer.py:Stability: semi-stable cred/identity.py:Stability: semi-stable cred/perspective.py:Stability: semi-stable cred/service.py:Stability: semi-stable cred/util.py:Stability: semi-stable internet/defer.py: API Stability: Unstable internet/error.py:API Stability: semi-stable internet/interfaces.py:API Stability: stable, other than IReactorUDP (semi-stabl e) and internet/interfaces.py:IReactorMulticast (unstable). internet/interfaces.py: This interface is semi-stable. internet/interfaces.py: This interface is semi-stable. internet/interfaces.py: This interface is semi-stable. internet/protocol.py:API Stability: stable, other than ClientCreator. internet/protocol.py: The API for this class is not stable. internet/protocol.py: This class is unstable. internet/protocol.py: This class is unstable. internet/pyuisupport.py:API Stability: unstable internet/stdio.py:API Stability: semi-stable internet/tksupport.py:API Stability: semi-stable internet/udp.py:API Stability: unstable internet/win32eventreactor.py:API Stability: semi-stable names/client.py:API Stability: Unstable names/resolve.py:API Stability: Unstable names/server.py:API Stability: Unstable news/database.py:Stability: semi-stable news/news.py:Stability: semi-stable protocols/basic.py:API Stability: semi-stable. protocols/dns.py:API Stability: Unstable protocols/ftp.py:Stability: semi-stable protocols/ftp.py: This class is unstable (it will be heavily refactored to su pport dynamic protocols/ftp.py: This class is semi-stable. protocols/http.py:API Stability: Server HTTP support is semi-stable, client HTTP is unstable. protocols/imap4.py:API Stability: Semi-stable protocols/irc.py:Stability: semi-stable. protocols/msn.py:Stability: unstable. protocols/nntp.py:Stability: semi-stable protocols/oscar.py:This module is unstable. protocols/policies.py: """Stability: Unstable""" protocols/policies.py: """Stability: Unstable""" protocols/policies.py: Stability: Unstable protocols/policies.py: Stability: Unstable python/roots.py:Stability: Unstable runner/__init__.py:Stability: semi-stable runner/inetd.py:Stability: semi-stable runner/inetdtap.py:Stability: semi-stable spread/__init__.py:Stability: semi-stable spread/banana.py:Stability: semi-stable spread/banana.py:Future Plans: This module is almost entirely stable. The same caveat applies spread/flavors.py:Stability: semi-stable spread/jelly.py:Stability: semi-stable spread/newjelly.py:Stability: semi-stable spread/pb.py:Stability: semi-stable spread/publish.py:Stability: semi-stable spread/refpath.py:Stability: semi-stable web/guard.py:This code is unstable and will probably be reimplemented at some point. web/soap.py:API Stability: unstable web/xmlrpc.py:API Stability: semi-stable words/service.py:Future Plans: Woah boy. This module is incredibly unstable. I t has an words/tendril.py:Stability: No more stable than L{words<twisted.words.service>}. Some of these semi-stable modules By your definition, the following are the only stable modules internet/abstract.py:API Stability: stable internet/app.py:API Stability: stable internet/base.py:API Stability: stable internet/default.py:API Stability: stable internet/defer.py:API Stability: stable internet/fdesc.py:API Stability: stable internet/gtk2reactor.py:API Stability: stable internet/gtkreactor.py:API Stability: stable internet/javareactor.py:API Stability: stable internet/kqreactor.py:API Stability: stable internet/pollreactor.py:API Stability: stable internet/protocol.py:API Stability: stable, other than ClientCreator. internet/qtreactor.py:API Stability: stable internet/ssl.py:API Stability: stable internet/threads.py:API Stability: stable internet/wxsupport.py:API Stability: stable protocols/toc.py:This module is stable, but deprecated. runner/inetdconf.py:Stability: stable spread/banana.py:Future Plans: This module is almost entirely stable. The same caveat applies And what about modules which are not marked as stable or unstable? % grep -i stable enterprise/* % Andrew Dalke dalke@dalkescientific.com
On 2003.05.30 01:47, Andrew Dalke wrote:
Itamar Shtull-Trauring:
Typically, unless the module has a docstring saying the API is stable, it probably isn't. There will usually be a backwards compatability layer if changes are made, though. Woven's been pretty good about that, and is now settling down into stability.
How comfortable should I be with these modules?
We only offer stability info, we don't control your mind. :-)
The same caveat applies
And what about modules which are not marked as stable or unstable?
% grep -i stable enterprise/* %
There's a relevant FAQ item on this: http://twistedmatrix.com/documents/howto/faq In CVS, I've updated the name of the FAQ to just "Which parts of Twisted are stable", rather than being specific to 1.0, btw. -- Twisted | Christopher Armstrong: International Man of Twistery Radix | Release Manager, Twisted Project ---------+ http://twistedmatrix.com/users/radix.twistd/
On Friday, May 30, 2003, at 01:56 AM, Christopher Armstrong wrote:
We only offer stability info, we don't control your mind. :-)
Who's "we", kimosabe - mind control is certainly on my agenda.
How comfortable should I be with these modules?
The modules that you mentioned have mostly accurate stability info, with the exception of banana - we tried to stabilize that one before we had enough users, performance testing, and security auditing, so there are some tweaks that will be happening in an upcoming rewrite. twisted.internet.interfaces looks like it's a little inconsistent, though - Itamar, would you look into updating that? If it says "stable", then we are committed to changing things very little, and providing extensive (and probably indefinite) maintenance of the existing interface even if things do change. If it says "semi-stable", you can probably only join IRC when releases happen and ask anyone if the changes are likely to impact you. (You could attempt to infer this from CVS logs and the ChangeLog file, but considering the quantity and subtlety of changes that happen each release, it's probably for all concerned just to ask.) These interfaces will change seldom and typically be well-announced if anything major happens. If it specifically says "unstable", you should be tracking CVS and on a first-name basis with at least one Twisted developer, preferably the maintainer of the module of your choice :).
On Thu, 29 May 2003 23:47:07 -0600 Andrew Dalke <dalke@dalkescientific.com> wrote:
How comfortable should I be with these modules?
Depends how many people use them. The more people use it, the more chances there will be backwards compatability when things change. We don't change things just for fun, either - if you use, say, FTP server, you will soon find out why it needs a rewrite. Woven was under *massive* development over the past few months, but even so, most old code didn't break. At some point in the future it will not be b/c, but that's why there are DeprecationWarnings.
participants (5)
-
Andrew Dalke -
Christopher Armstrong -
david mertz -
Glyph Lefkowitz -
Itamar Shtull-Trauring