There's been a lot of debate about the 'best set' of pyramid project templates
for awhile, and after going over a few options with Chris McDonough, reading
the messages here from Graham Higgins and Mike Orr, I think I might have a
decent solution.
One of the things thats come up is what exactly the options are that the
project template comes with. This is further confused by the Pylons merger
which has some other assumptions about a default project layout (and tools
built with those assumptions that created controllers/etc), vs BFG which went
for a more do it yourself (DIY) approach.
A decent amount of DIY'ers are not going to want a full project hierarchy. So
the issue comes with how much 'assistance' Pyramid provides to them out of box
in the form of project templates, each of which requires ppl to maintain it....
document it... etc. At the same time, a great many people just want something
right away with the assumption it'll work for their project (which is not a
simple wiki or hello world app).
So here is a proposal that I went over with Chris that tries to combine the
best of the most worlds at once. :)
Essentially the goal is to combine the benefits of having a unified project
structure such as:
* Consistent location of things for documentation purposes
* Easy for new people to start on a project and see where things are
Pyramid should come with a single main project template, that has the following
layout (in addition to the default package stuff):
newproj/
__init__.py
templates/
models/
__init__.py
views/
__init__.py
static/
tests/
Since both Mako and Chameleon are configured out of box, no additional
config/options are necessary to support it. There is nothing in the template
that configures traversal, or a database, or what exactly the models are. The
__init__ merely has the basic config for the project.
For additional assumptions to be made, ie.
* I want to use Jinja2
* I want to use SQLAlchemy
etc.
The package providing the hook points for a specific database, or template
engine, may include (and document!) a paster template extension that configures
it. Or if using it only requires a single line to be added (as is the case of
pyramid_jinja2 to add the jinja 2 renderer), then just document which line to
add to ones __init__.py. All the Pyramid documentation when referring to an
existing project will assume the project was created using the default template
layout above.
For the DIY'er, some instructions will be provided in the beginning about using
the default 'paster create someproj' template that creates an empty package,
and adding a few files yourself that setup Pyramid. Which is after all very
easy since pyramid can be configured in a single module.
pyramid_sqla and pyramid_zodb packages will be created. The pyramid_sqla
package will include a configuration line that can be added to the config
section which will setup a DBSession available in the pyramid_sqla package
itself. This avoids having a bunch of additional project boiler-plate as the
SQLAlchemy ones have right now, and means that no imports are needed at all
from the models during config (which also means table reflection should be less
messy since those classes can actually be at module scope).
For those that want declarative config, that section of the docs will include
the file to add, and the one additional config line to add.
There will be one other template, has just:
newproj/
__init__.py
All it does is make a basic config instance, and include an INI file for
running it. This would be the starting point for the DIY'er that was making
something other than a one-module app.
I think this will substantially help straighten out the template situation, and
other packages that provide other templates will then be responsible for
documenting it. pyramid_sqla also means there's a point to build additional
sets of functionality that assist with SQLAlchemy usage in Pyramid that would
help for those who want to make bits that assume you're using SQLAlchemy.
So, any thoughts on this proposal? :)
Cheers,
Ben
--
You received this message because you are subscribed to the Google Groups
"pylons-devel" group.
To post to this group, send email to pylons-de...@googlegroups.com.
To unsubscribe from this group, send email to
pylons-devel+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/pylons-devel?hl=en.
