[Twisted-Python] Proposed new homepage

[Itamar Turner-Trauring]

On Mon, 2011-10-10 at 09:20 +0200, Albert Brandl wrote:

> > 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 ;-).

Open source and not GPL is probably the important bit.

> 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.

I get the impression some people think Twisted is complex and big
because of all the features it has. So first I want to show them with
code "look it's so simple"... and only then give the full list of
features.

> 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`. 

I have just closed two tickets making buildProtocol explicitly used in
both the server and client howtos, and I've also updated a relevant code
example in the website's FAQ. The current way of doing things, setting
an attribute on Factory, is really bad from an educational point of
view, since it makes protocol creation "magic". By having an explicit
buildProtocol users know where protocol instances come from, and how to
override this creation.

> 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`. 

buildProtocol does not always need to set factory as an attribute, you
can just return a protocol instance. If you do need the factory, better
to pass it in to Protocol's __init__ explicitly instead of having an
extra attribute shoved on later.