-This is a background chapter on what we learned in Pyramid's first year and
-the reasons behind Akhet 2's changes.
+Akhet evolved out of a Pyramid/SQLAlchemy application scaffold. It then grew
+more Pylons-like features, a small library, and documentation that
+expanded to become a general introduction to Pyramid. In Akhet 2, the
+documentation takes center stage and the scaffold has been retired. Why this
+reversal? Pyramid 1.3 (to be released by the end of 2011), reduces the number
+of built-in scaffolds to three:
-Akhet started as a Pyramid/SQLAlchemy application scaffold. It grew more
-Pylons-like features and documentation, until finally the database was just a
-small part of the scaffold. [#]_ In Akhet 2, the documentation takes center
-stage and the scaffold has been retired. Why this reversal? There are four main
+* 'alchemy': URL dispatch + SQLAlchemy
+* 'zodb': traversal + ZODB
+* 'starter': traversal only, no database [#]_
-1. Maintaining a scaffold turned out to be significantly burdensome.
-2. Users' feedback on what they do after they gain experience in both Akhet and
- "raw" Pyramid. (Many want to mix and match features.)
-3. Pyramid's move away from Paste and PasteScript, which have not been ported
-4. Pyramid users' persistent requests for "more tutorials".
+This represents a change of direction for Pyramid. Instead of having scaffolds
+for all combinations of libraries, only the most-used application styles have
+scaffolds. Most people use URL dispatch with SQLAlchemy, and traversal with
+ZODB, so these are the combinations offered.
-The first three have to do with the nature of Paste scaffolds. The scaffold API
-is primitive. It doesn't do inheritance, so you can't derive a scaffold by just
-specifying the differences with an existing scaffold: you have to copy the
-entire scaffold, and update it as the original changes. Testing a scaffold
-requires several manual steps to create and run an application every time you
-make a change. "paster create" calls scaffolds "templates", which is confusing
+If you're coming from Akhet 1, or from Pylons/Django/Rails/PHP, use the
+'alchemy' scaffold in Pyramid 1.3 (or the identical 'routesalchemy' scaffold in
+Pyramid 1.2 and earlier, NOT 'alchemy' which is different). Then read on to see
+how to customize the application to add all the features Akhet 1 had. Each
+feature requires pasting in only a few lines of code, and by doing it yourself
+you'll get a better feel of how it's implemented and what it's doing.
-The final barrier was Python 3. Other packages descended from Paste had been
-ported to 3: PasteDeploy, WebOb. But nobody volunteered to port Paste and
-PasteScript, especially since the scaffold API needed to be overhauled anyway,
-many of its subcommands were obsolete, and some people questioned the whole
-concept of new plugin subcommands: what exactly was the benefit over simpler
+.. topic:: Rant about scaffolds
-In Pyramid 1.3 [#]_, the developers dropped the Paste and PasteScript
-dependencies, and added bin scripts for the essential utilities Pyramid needs:
-'pcreate', 'pserve', 'pshell', 'proutes', 'ptweens', and 'pviews'. These were
-derived from the Paste code, and the scaffold API is unchanged.
+ There are four main reasons.
-Pyramid 1.3 reduces the number of built-in scaffolds to three. This is
-good news for new developers because it focuses on the two most-used
-application styles (URL dispatch + SQLAlchemy, or traversal + ZODB), rather
-than on having scaffolds for every little-used permutation of libraries. Akhet
-is following suit by endorsing one of them (called 'alchemy' in Pyramid 1.3,
-and 'routesalchemy' in Pyramid 1.2 and earlier). The differences between
-'alchemy' and 'akhet' are small enough that you can paste in the code yourself
-for the features you want, and there are increasing reasons to do so.
+ 1. Pyramid users' biggest request has been for "more tutorials".
+ 2. Maintaining a scaffold turned out to be significantly burdensome.
+ 3. The scaffold is based on PasteScript, which Pyramid is moving away from.
-1. Some users like to mix and match between Akhet features and other features.
-2. The 'akhet' scaffold can't absorb every new feature that comes down the
-3. Pasting the code yourself helps you understand how it's implemented.
-4. It makes the Akhet maintainer happier because he can sluff the
- responsibility of maintaining the scaffold onto somebody else who's doing it
- already, and it will automatically be updated as Pyramid changes.
+ There are several problems with maintaining a scaffold. Testing it requires
+ several manual steps -- every time you change a bit of code. Scaffolds aren't
+ inheritable, so you can't just specify the differences from an existing
+ scaffold, you have to copy the whole thing... and duplicate any later changes
+ in the original. The scaffold API is primitive and limited. The final barrier
+ was Python 3. Other packages descended from Paste have been ported to 3
+ (PasteDeploy, WebOb), but Paste and PasteScript haven't been. There doesn't
+ seem to be much point because the scaffold API needs to be overhauled anyway,
+ many of paster's subcommands are obsolete, and some people question the whole
+ concept of plugin subcommands: what exactly is its benefit over bin scripts?
-The other thing that happened this year is users kept asking for "more
-tutorials". People want more examples of how to get started with their first
-application, how to choose between alternative API styles and libraries, and
-examples of larger integrated applications (with AJAX and the whole hog). This
-Akhet manual won't help with the last one, but it's adding content for the
+ Pyramid 1.3 (to be released by the end of 2011) drops the Paste and PasteScript
+ dependencies, and adds bin scripts for the essential utilities Pyramid needs:
+ 'pcreate', 'pserve', 'pshell', 'proutes', 'ptweens', and 'pviews'. These were
+ derived from the Paste code, and the scaffold API is unchanged.
+ 1. Some users like to mix and match between Akhet features and other features.
+ 2. The 'akhet' scaffold can't absorb every new feature that comes down the
+ 3. Pasting the code yourself helps you understand how it's implemented.
+ 4. It makes the Akhet maintainer happier because he can sluff the
+ responsibility of maintaining the scaffold onto somebody else who's doing it
+ already, and it will automatically be updated as Pyramid changes.
+ The other thing that happened this year is users kept asking for "more
+ tutorials". People want more examples of how to get started with their first
+ application, how to choose between alternative API styles and libraries, and
+ examples of larger integrated applications (with AJAX and the whole hog). This
+ Akhet manual won't help with the last one, but it's adding content for the
-.. [#] Strictly speaking, the original scaffold was called 'pyramid_sqla', as
- was the distribution. It was renamed to Akhet to show it wasn't primarily
- about SQLAlchemy. Also because of a general decision to give
- third-party scaffolds their own identity rather than pyramid_something.
-.. [#] Pyramid 1.3 was in development as of November 2011. It's expected to be
- released in December or soon thereafter.
+.. _[#]: There is discussion about changing 'starter' to URL dispatch,
+ but that had not done as of this writing.