This is a summary of an IRC discussion on the Pylons Book, held 2007-10-28 17:15 UTC on #pylons. I'm posting it in the Cookbook temporarily because I don't have write access to the Pylons Book space.

Participants: James Gardner, Mike Orr, Ben Bangert, Chairos, Zeon, Signum, Justin, Eleftherios, Psnively, robertj_, Steg, Spike.

Existing table of contents

   Part I: Getting Started
   
   Chapter 1. Introducing Pylons
   Chapter 2. Installing
   Chapter 3. Getting Started
   Chapter 4. Tracking Down Problems (Debugging + Logging) * Needs more work
   Chapter 5. Templates
   Chapter 6. Forms
   Chapter 7. Routes URL Configuration
   Chapter 8. Databases
   Chapter 9. Cookies, Sessions, Sending Email, Helpers, Caching
   Chapter 10. QuickWiki Example
   
   Part II. Advanced Pylons
   
   Chapter 11. Object Relational Mappers and Object Databases
   Chapter 12. Web Services, RSS, XML, REST
   Chapter 13. Ajax
   Chapter 14. Internationalization and Localization
   Chapter 15. Testing - Interactive, Functional, Unit
   Chapter 16. Documentation - Pudge, doctest etc - Setting up a trac site etc.
   Chapter 17. Packaging and Releasing Web setup, paster make-config, paste deploy

   Part III. Expert Pylons
   
   Chapter 18. Web Server Gateway Interface
   Chapter 19. Authentication and Authorization
   Chapter 20. Advanced AuthKit
   Chapter 21. Eggs, easy_install, Plugins, paste script
   Chapter 22. Pylons Deployment
   Chapter 23. Managing Production Instances with Buildout
   Chapter 24. Integration Pylons with Django, TurboGears, and others
   Chapter 25. The Pylons Architecture in Detail

Parts and chapters

The parts need to be refocused, although the part titles can remain.

Part I should focus on preparing the user for a beginning Pylons application: the QuickWiki example. QuickWiki includes SQLAlchemy ORM and high-level model methods, Mako templates, WebHelpers form generation. Chapters 1-10 are good, although parts of chapter 4 (customizing error pages, advanced logging) need to move to Part II or III.
Part II should focus on preparing the user for an advanced application (QuickWiki2) and professional deployment. Chapters 19-23 (AuthKit, deployment, Buildout) may belong in Part II.
Part III should be an expansion of chapter 25, explaining Python's/Paste's structure and source code, and why various design decisions were made. The user should learn enough to build a Pylons application without a "paster create" template.

There was some discussion about where to put logging, and whether to split out some of the chapters that were combined. James wants to put logging in its own chapter in Part II, though Part I may need some minimal instructions on setting up basic logging. (E.g., log a controller message, make SQLAlchemy log SQL queries).

Jimmy says Routes has already been moved to Part II, because QuickWiki requires only minimal route configuration.

Chapter 9 has a lot of stuff in it, perhaps too much. Ben says cookies aren't actually part of the framework. Mike says they need to be documented anyway. Jimmy says chapter 9 relates to a helper library he's written, which includes a Django-like email sending library and ISO country codes. TurboGears' schedule model is also under consideration.

Content for Part III

James and/or Mike suggest the following content for Part III:

WSGI introduction.
Making a WSGI middleware.
What happens during Pylons startup and during a request? Pylons Execution Analysis 0.9.6 has material on this.
Entry points and plugins.
easy_install in detail. (Unless zc.buildout is exclusively described, which does not use setuptools/easy_install.)
Integration with TurboGears, Django, etc. The rest of us aren't sure what Jimmy means by this. We should show how TurboGears 2 was implemented on top of Pylons, and how to assemble a hybrid application (with some Pylons controllers and some TG). Django has expressed interest in webObj, Paste's new request/response objects that Pylons 0.9.7 will adopt.

Controversial topics:

Custom paster templates and the minimal template. Mike suggests says leave it out of the book because it's peripheral to successfully building a Pylons app, we need to limit the book's content, and it can be done on the wiki.
Component-oriented pattern. Mike and others have requested an MVC "bundle" structure that can be dropped into a larger Pylons application. This is too experimental at this point to be included in the book, though the book can mention it in passing and point to the wiki for the latest info.

Javascript libraries

The book will mainly document YUI and some JQuery. script.aculo.us is considered inadequate, and all Javascript libraries currently suck, but Jimmy leans toward YUI for the book because it's used at Yahoo, which his paying clients respect. Ben wants to move away from scriptac.ulo.us, Prototype, and the Javascript WebHelpers (drag n drop, observer, etc). Jimmy points out that Javascript libraries are where Python web frameworks were a couple years ago: many doing the same thing.

Disadvantages of YUI: it's verbose, and its AJAX connection is significantly different from the pattern used in other JS libraries (or so alleges James).

Mike says the important point is to describe one robust and relatively future-proof library, but also how users can plug in another library of their choice. Signum points out we should also list the existing JS libraries and the advantages/disadvantages of each.

Jimmy found ExtJS too big and slow.

Mootools was also mentioned in passing.

Ben recommends a 5-page intro to Javascript, or a link to Douglas Crockford's "Intro to Javascript" class at YUI Theatre.

Databases

Jimmy doesn't like SQLAlchemy and would prefer to describe raw DB-API.
SQLAlchemy doesn't scale to multiple database servers, he says. Mike and
Ben strongly disagree, saying SA will work in the majority of user cases and
it's what users expect. Also, SA 0.4's sharding addresses the multiple server
issue. We must also keep in mind that any shortcomings to SQLAlchemy can be
addressed in the six months before the book is published, especially if we file
SA bug reports and follow up on them. Also, SQLAlchemy's complexity is another argument for including it in the book, because a gentle Pylons-specific introduction will be invaluable for the many readers who want it.

We discussed whether to describe PostgreSQL, MySQL, or SQLite. We agreed to start with SQLite so readers can easily run the example as they read. Then
switch to PostgreSQL for the more advanced examples, because Jimmy prefers PostgreSQL over MySQL. Also document how to port a SQLite model to PostgreSQL in one step, by changing the DB URI and re-creating
the tables. (That won't copy over the data, but that may be beyond the scope
of the book.)

Neither James nor Mike have experience with Tesla, Elixir, Storm, or DejaVu, so these can't be included besides a brief mention. Durus deserves a brief mention as one of the simpler object databases.

Mike is concerned about the two database chapters being so far apart from each other.

Templates

Use .html for Mako templates rather than .mako, because it's easier to get
syntax highlighting in editors to work with it, and it allows one to
differentiate between .html, .rtf, .css Mako templates.

Buildout vs virtualenv

James recommends Zope's Buildout for sandboxing and deployment. Mike and Ben are afraid Buildout is too advanced for the "Installing Pylons" chapter. Virtualenv is dirt simple, so Mike recommends it for the beginning of the book, and Buildout as an advanced deployment option. Jimmy claims Buildout can do everything Virtualenv can do. Mike challenged Jimmy to write a Buildout HOWTO that's as non-scary to newbies as virtualenv, and also explains Buildout's concepts to existing virtualenv/workingenv/virtual-python users.

Note: Workingenv is out of the running because virtualenv is its replacement, according to Ian Bicking who wrote both. Virtualenv avoids various bugs inherent in workingenv's architecture. Mike is comfortable with workingenv's stability. Mike and Ben will both test virtualenv to ensure it has the same stability.

One key difference between Buildout and virtualenv is that virtualenv installs setuptools/easy_install into its site-packages directory. You can install a package at any time during development by running easy_install, and uninstall it by running "easy_install -m" and deleting it manually. In Buildout, you edit a configuration file and re-run buildout to create a new environment. Buildout is obviously helpful during deployment, especially with its cached eggs directory. The question is whether it's convenient enough during development, when you don't know which libraries you will need and you may have to experiment with a few alternatives before choosing one.

AuthKit

Chairos brought up various ways he thinks AuthKit is inadequate. Jimmy said to send him a list of problems. Mike said not to worry because there's plenty of time to fix any bugs or missing features in AuthKit before the book is published, and there's no alternative library that covers authentication so flexibly (or even covers it at all).