[Twisted-Python] Proposed new homepage

Albert Brandl albert.brandl at weiermayer.com
Mon Oct 10 03:20:27 EDT 2011


Hi!

On Sun, Oct 09, 2011 at 02:44:41PM -0400, Itamar Turner-Trauring wrote:
> http://twistedmatrix.com/trac/wiki/ProposedWikiStart
> 
> What do you think?

I like the approach to instantly "dive into" the library by showing some 
code. But I have a programming background - not sure if all (relevant) 
visitors will be happy with this.

> Twisted is an event-driven networking engine written in Python and 
> licensed under the MIT license.

Is the license really so important that it should be mentioned in the 
first paragraph? If it is, you might want to consider splitting the 
sentence. And yes, I know that the current homepage starts with the
same sentence ;-).

The following summary of Twisted projects on the current homepage might 
be a good completion of the first paragraph:

> Twisted projects variously support TCP, UDP, SSL/TLS, multicast, Unix 
> sockets, a large number of protocols (including HTTP, NNTP, IMAP, SSH, 
> IRC, FTP, and others), and much more.

One comment on the first code example:

> class EchoFactory(protocol.Factory):
>    def buildProtocol(self, addr):
>        return Echo()

It might be better to just define the `protocol` class variable and 
leave the instantiation to the default implementation of 
`buildProtocol`. 

Otherwise, the reader might assume that overriding `buildProtocol` is 
always necessary. Even worse, she might think that just returning an 
instance is enough; AFAIK, `buildProtocol` should also set the 
instance's `factory`. 

Of course that is an implementation detail, but I don't think we should 
set visitors on the wrong track right at the beginning ;-).

Best regards,
-- 
Albert Brandl
Weiermayer Solutions GmbH      | Abteistraße 12, A-4813 Altmünster
phone: +43 (0) 720 70 30 14    | fax: +43 (0) 7612 20 3 56
web: http://www.weiermayer.com



More information about the Twisted-Python mailing list