On Tue, 2010-11-23 at 15:29 -0800, Ben Bangert wrote:
> 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.
I'd suggest instead:
newproj/
__init__.py
views.py
tests.py
models.py
templates/
mytemplate.pt
static/
<various static files>
Such a template might be named "pyramid_diy". "pyramid_diy" would be a
template used by folks whom:
- already know how to create packages and whom understand that it's
possible and trivial to turn a module into a package when such an
occasion is required (it needn't be done preemptively for them).
- realize that there are not any incontravertable decisions implied
by the filesystem layout generated by a paster template.
This would essentially just be the "pyramid_starter" template renamed.
It would be the only paster template that ships with Pyramid itself.
> For additional assumptions to be made, ie.
> * I want to use Jinja2
> * I want to use SQLAlchemy
> etc.
(ftr, pyramid_jinja2 does indeed already ship with a paster template,
although I'm not sure it should)
> 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.
There isn't much documentation that refers to package structure in the
Pyramid docs.
The "project" chapter
(http://docs.pylonshq.com/pyramid/dev/narr/project.html) makes lots of
references to files. This chapter is essentially just documentation for
the current starter template. The "project" chapter documentation can
actually just be cutnpasted into each external project template package
and modified as necessary.
The "project" chapter would then just a) document the pyramid_diy
template and b) make reference to existing official pyramid_foo external
paster template packages (initially, there would be only two:
pyramid_sqla and pyramid_zodb).
The wiki tutorials in the docs
(http://docs.pylonshq.com/pyramid/dev/#tutorials) also make reference to
specific files, but I'd suggest moving both of those tutorials to its
most closely related external template package. We can then just create
a single new tutorial for Pyramid itself based on the DIY template.
There are a few other spurious references to ``views.py`` or
``models.py`` in other places in the Pyramid docs (the templates and
resources chapters, for example) but these can be changed to "views
module/package" or "models module/package" as necessary. I think as
long as the name of a module file representing, e.g. views (views.py) is
the same as the name of the package directory (views directory with an
__init__.py file in it), this is sufficient.
> 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 don't think this is useful. A single file app would never live in a
package. There's no purpose in providing a template to generate a
single-file 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? :)
In general, I like the idea. My primary concern about this is that it
places a nontrivial burden on the shoulders of the people who maintain
the external paster packages to keep docs and tutorials up-to-date that
have previously been maintained in the core. I know from experience
that this is a major pain in the ass. With every paster template change
(even very minor ones), I usually have to update 20 or more files to
bring tutorials up to date. The existence of such step-by-step
tutorials is not optional, though, and there's no credible way I can
think of to make maintaining one an easier job.
- C
--
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.
