- Link to document: http://twistedmatrix.com/projects/core/documentation/howto/clients.html
- Reviewer's name: Andrew Bennetts
- Review date: 7th March 2006
Before someone begins using this document, I'd really really like it if they knew:
- more or less what a TCP socket is, and that they connect to endpoints specified by host + port.
- more or less what Deferreds are.
Once someone has read this document they should understand:
- how to write a Twisted program that connects (and uses) a single TCP client.
- how to write a Twisted program that connects & uses multiple concurrent TCP clients.
- how to write a Twisted program that uses TCP clients concurrently with other functionality, like running a TCP server.
- how to use
ClientCreatorto create try-once client connection.
- how to use
ReconnectingClientFactoryto make a client that tries to reconnect lost connections automatically.
- how to define custom reconnection logic (in the same manner that
ReconnectingClientFactorydoes), including how to abort a connection attempt.
- that Protocols work the same way for servers and clients (even though most protocols aren't symmetrical).
Coverage of subject matter
This document seems to cover the following subject matter at least acceptably well:
- the relationship of protocol instances to connections (although theoretically
this doesn't have to be true, in practice most
ClientFactoriesdo this, so the simplification here is fine).
- it recommends the use of
ReconnectingClientFactoryfor reconnection logic, and gives an example of using it.
ircLogBotexample is a good, real example, that does something useful and interesting, and demonstrates use of
reactor.connectTCP. (and judging from the number of times I've seen "twistedbot" join #twisted, people actually run and play with this code a fair bit).
This document seems to be attempting to cover the following subject matter, but its coverage is flawed:
- the use of the term "configuration" for application state usually held in a factory is confusing and probably too abstract.
- the example in "Simple, single-use clients" is good, except that it's not quite a complete, executable example. It should have a reactor.run() line.
- "Simple, single-use clients" should give a comprehensive list of methods that
are specific to
ClientFactories(or perhaps this could come later in the document, but it definitely should be in this document somewhere).
- "Simple, single-use clients" gives an example that needs to take connector
arguments, and although it never uses them, it's a bit weird to just never
mention them or what they are here. Also, it should say that "reason" is a
ClientFactoryshould be introduced with a comprehensive API overview.
- The "To connect this
EchoClientFactoryto a server, you could use this code:" snippet may as well be part of the main example in this section.
- The "Reconnection" section starts talking about calling various methods on
connector" variable, but never says what it is or links to the API docs for
- The explanation of
ClientCreatoris too terse -- e.g. it doesn't make it clear that it returns a
Deferredof the connected protocol.
twisted.protocols.irc, which has been deprecated. It should import
This document ought to be covering the following subject matter but is not:
- Never are connectors or the
- The APIs of
- How to make concurrent connections -- it should explicitly state that:
connectTCP(and other variations like
connector.connect()) don't block -- they start the process of establishing the connection, and you wait for an event handler like
connectionMadeto be called.
- you can simply call
connectTCP(or whatever) multiple times -- in a row, even -- to make multiple connections. It's obvious once you "get it", but needs to be explicitly stated, as it's not obvious to many people new to Twisted.
This document could be supplemented by links to these existing follow-up ("now that you know X you can try Y") documents:
- GUI docs (because client programs are often interactive)
- Choosing a reactor and GUI toolkit integration
- Reactor basics
- Logging howto
This document could be supplemented by as-yet non-existant pre-requisite ("you should read this first") documents on:
- "Mastering TCP in under 3 minutes" ;)
This document could be supplemented by links to these as-yet non-existant follow-up ("now that you know X you can try Y") documents:
- comprehensive description of
twisted.internet.protocol.Protocol, the methods you can override, and the actions you can perfrom (e.g.
self.transport.loseConnection()). i.e. "Guide to writing protocols"
- Guide to
- Guide to
twisted.words.protocols.irc(for better understanding of the IRC example).
- Guide to
twisted.internet.stdio(many client programs are likely to be interactive).
gtkdemo.py(we seem to have one for every other GUI...)
The following changes to the style of the document would make it easier to read:
- typo: s/decended/descended/
- it starts with a pretty jargon-heavy introduction. I think a simple example that is then dissected would be a better introduction.
- "is usually where set up" -> "is where set up usually"
- first sentence of
ClientFactoryis "We use
ClientFactory." The sentence doesn't really make sense... use it to do what? I'd expect some sort of explanation about why you'd want to use it, e.g. "
ClientFactorycan be subclassed to XXX."
- "Persistent Data in the Factory" appears to be presenting an extract of the previous example (to highlight certain things), but it's not clear that this is an extract rather than a new example.
This document is: better than having no documentation, but with some glaringly obvious improvements to make