[Twisted-Python] Re: My review of Abe's book "Twisted Network Programming Essentials"

[Abe Fettig]

Tommi Virtanen wrote:
> Hi. I just finished a review of the new O'Reilly book on Twisted,
> by Abe Fettig (hi Abe!), and thought you all might be interested in it:
> 
> http://tv.debian.net/articles/review-snakeball/

Wow, Tommi, thanks for the very thorough review. I'm seriously
impressed. You picked up on a lot of details I'd missed, especially the
places where I didn't follow best practices in the code examples. I'll
get these incorporated into the official errata. And next time I'm
definitely going to have you involved as an official tech reviewer. You
 have a talent for it.

Overally I think you're accurate in pointing out the weaknesses of TNPE.
There are a couple of points that I'll push back on, though:

1. "DO NOT BUY TNPE TO LEARN TO WRITE WEB APPS"

Sigh. Writing the chapter on web servers was extremely frustrating. For
years now Twisted web app developers have had two choices: use stable
APIs that are widely considered to be broken and/or deprecated, or use
new, improved APIs that are currently under heavy development and
unstable. I put off writing this chapter for as long as possible, hoping
that there'd be a stable release of twisted.web2 to write about, but it
didn't happen. So in the end I decided it was better to document the
current stable twisted.web code, for all its faults, than to try to
document APIs that were in flux and very likely to change.

Hopefully readers will understand that this chapter is explaining how to
use the current twisted.web, not teaching the ideal architecture for web
applications. On page 54 it says "The classes in twisted.web.resource
and twisted.web.server are, as of this writing, widely considered to be
past their prime. They have some serious shortcomings ... Both are
scheduled to be deprecated in the future in favor of improved classes
provided by a next-generation web package known as twisted.web2." It
also says that if you're building a major web appication you should use
Nevow.

In retrospect, it probably would have been best to do both: include
examples of the stable APIs, but write more about nevow and
twisted.web2, including some examples.

2. It's not a Twisted Bible.

This is certainly true. If you look at the oreilly.com page [1] you'll
see that this book is in the "Developer's Notebook" series
(http://devnotebooks.oreilly.com/). Here's how O'Reilly describes
developer's notebooks:

"A Developer's Notebook is just what it claims to be--the often frantic
scribbling and notes that a true-blue alpha geek makes when working with
a new language, API, or project. It's the no-nonsense code that solves
problems, stripped of page-filling commentary that can often serve as
more of a paperweight than an epiphany. It's hackery, focused not on
what's nifty or might be fun if you've got some spare time, but what you
need to simply make it work now. This isn't a lecture, folks; it's a lab."

TNPE was written as a developer's notebook, and it shows. Unfortunately
as I was getting close to finishing the book O'Reilly decided that the
developer's notebook line wasn't doing very well and that they'd scrap
the "notebook" design and naming convention in favor of the more familar
animal book. I was happy to get a cool animal book cover, and my editor
and I tried to pick a title that accurately portrayed the contents of
the book. But in hindsight I think it would have been better to keep the
developer's notebook name and design. When some people see an animal
book they think "definitive guide", and then they're disappointed when
it's something else.

I hope that at least clarifies those points. This was my first book, and
I'm proud of it, but at the same time I'm sure I have a lot to learn.
Probably it's a lot like writing code, and somebody I'll look back on it
and be able to see clearly all the things I did wrong :-). In any case,
thanks for taking the time to read it and write this!

Abe

[1] http://www.oreilly.com/catalog/twistedadn/ (you can see traces of
the original "twisted - a developer's notebook" title in the URL)