Commits

Mike Orr committed 81a32a8

Text.

Comments (0)

Files changed (2)

 
 Akhet is a set of tutorial-level documentation and convenience code for
 Pyramid_. Version 2 focuses more heavily on documentation, and does not contain
-an application scaffold [#]_. Instead of a scaffold, the
+an application scaffold [#]_. Instead the
 documentation shows how to customize Pyramid's built-in scaffolds to give a
-Pylons-like environment. The Akhet library (the ``akhet`` Python package) is
-still around; it's unchanged in this release.
+Pylons-like environment, and it discusses the tradeoffs between various
+alternative APIs. The Akhet library (the convenience classes) are unchanged in
+this release.
 
 Akhet 2.0 runs on Python 2.5 - 2.7.   The next version will probably add
 Python 3 support and drop Python 2.5, as Pyramid 1.3 is doing.
 Introduction to Akhet 2
 %%%%%%%%%%%%%%%%%%%%%%%
 
-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
-reasons.
+* '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
-   to Python 3.
-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
-with HTML templates.
+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
-bin scripts?
+.. 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
-   block. 
-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
-first two.
+    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
+       block. 
+    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
+    first two.
 
-.. [#] 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.
 
 .. _Usage: usage.html