I agree with Carlos that 'how do I structure my app' is the biggest missing piece of most (Python) web frameworks' documentation. The lack is just as true for big ones like Zope as it is for all the small players.
One explanation, at least anecdotal, is that we don't know the answer. I started such a document for Webware, but quickly decided the explanation showed off some glaring problems in the setup and went off to fix them, distracting myself and never finishing the original documentation. And really, I only fixed a small portion of the code problems while I was at it. I'm sure other developer/documenters have the same problem of thinking why should I document stupid stuff instead of fixing it, then getting distracted.
When I started doing Zope development for my day job, I felt pretty much out in the wilderness as well. Some documents told me how I should do things, but all the legacy code was so very, very far from that model that I felt somewhat abandoned. It's not that the legacy code was bad (well, some of it was, but that's inevitable), but that there's a lot of really bad advice out there on how to make Zope applications. My hint: anything documentation that talks about DTML, or starts you out coding in the Zope Management Interface (the web interface to Zope) is probably a bad idea to follow. Unfortunately that's most of the documentation :(
Since the Python community (or at least the bloggers) are going through a little what's-Rails-got-that-we-don't phase, this is another point we can put on that. Rails has strong conventions about application layout, and it isn't afraid to tell you about it. There's no shy well, this is how I do it, but whatever works for you stuff -- people usually come in happily willing to accept the most draconian and inflexible of standards, because at least it gives them a starting point and an opportunity to avoid gratuitous differences in code.
I think that there is a lot to be said for what Rails has to offer. I love Python and use it daily, but have yet to find anything as integrated, easy to use, and clear as Rails. I am not a big Ruby fan (too much like perl after an "extreme makeover"), but have been using Rails to develop some personal web apps because its so much more pleasant than digging through scant documentation, figuring out how to integrate packages, and reconciling all the bits and pieces available for Python.
I actually think the Rails approach is the best way (and more Pythonic than Python web frameworks in a way), rather than the approach that both Python and Java use. In Python and Java, there are tons of packages available for doing templating, persistence, controllers, etc. These packages are written by different people, with different terminology, and different styles. Sure, its more "flexible" but its a lot less convenient. With Rails there is only one way, and what's more Pythonic than that? Isn't Python supposed to be the "there's only one way to do it" language! This is why I love Python more as a language than Ruby, but Rails really got it right in terms of framework. When it comes to frameworks, consistency, simplicity, and integration are the most important things! Why don't people understand that?
Python bloggers have been talking a lot about how we can do all the things Rails does in Python using WebWare, CherryPy, Quixote, Kid, PSP, mod_python, SqlObject, PyDO, Zope, Plone, etc, etc, etc... but THATS NOT THE POINT! You can do all the Rails things (well, many of them) in Java too... but the problem is that its a pain in the ass. Granted, its less of a pain in the ass in Python than in Java, but still not nearly as pleasant and integrated as in Rails.
Rails makes writing web apps fun again. I can't say that for any of the combinations (permutations?) of Python packages available. And, no, I don't think that the "Subway" approach is right... it would be wiser to start from scratch to get the best integration, or at least fork the "starting point" packages (CherryPy, etc) so that you can make things more consistent and tightly integrated from the get-go.
Has anyone done any study into what exactly is so tightly integrated that a platform can't just piece existing components together using Adapters and similar approaches?
Building the ORM scaffold stuff doesn't seem to require rewriting anything from scratch. If you build the table first, then SQLObject can keep the fields in order (the only irritation I have when using SQLObject to create the tables), and the platform can use Adapters to build a FunFormKit-based system to edit/create the objects, and simple list/view things too. In other words, the developer only need do what the Rails developer does: create a model and a controller. The rest magically springs to life.
What _does_ require stronger integration, especially to the point of rewriting the existing components?
In part integration saves you a lot of little jobs. But later the integration might not be a big win, as your particular application goes further from the assumptions the integration makes. But, that still leaves you with a base to start with, and a convention -- if the integration serves no purpose except to codify application layout and object composition, that's still a valuable thing.
Hmm... I've noticed the column ordering problem in SQLObject as well. It would be good to keep track of the chronological order in which the Col objects were created, then sort on that. That should give the ordering you want.
As far as adapters, that's certainly how they are intended to be used. I've had mixed results using them; I might just be using them incorrectly, but I might again blame it on a lack of codifying best practices ;)
I think this is the biggest factor in Rails' ease of use:
These packages [python] are written by different people, with different terminology, and different styles.
It's like reading a work of fiction (assuming continous, sensible story line) written by multiple authors. They might all get the job done very well on their own, but it just doesn't hold together as well or have the same "flow". Or like when you see a horrible Hollywood flick that has clearly been rewritten and worked over by a committee, losing any strong vision or voice it had.
Then there's the whole personality of the languages and communities using them, but that's a fire I dare not step into...
>people usually come in happily willing to accept the most draconian and inflexible of standards, because at least it gives them a starting point and an opportunity to avoid gratuitous differences in code.
... not to mention an opportunity to avoid wasting time reinventing tedious and trivial wheels when they could instead be devoting effort to thinking about how their application could do things that are interesting (and/or that somebody might actually want to pay for)
I'm not for a moment suggesting that things like Webkit or SQLObject are tedious and trivial to write - but let's face it, once somebody has done the world the service of writing them, that should be it. I want to spend more time thinking about what do I want in my database, what interesting things do I want to with my data and show to the world, than how I'm going to go about the tedious mechanics of shovelling it into and out of an RDBMS and a web server.
> ... not to mention an opportunity to avoid wasting time reinventing tedious and trivial wheels when they could instead be devoting effort to thinking about how their application could do things that are interesting (and/or that somebody might actually want to pay for)
That is supposed to be the benefit for any 'framework', and for successful ones with actual users ( sqrt(n) > # of framework developers) it works to some extent. The diversity of approaches to building web applications that is so visible in the python world may be due to the ease with which ideas can be dressed out in python, and the social incentives for being a framework developer. Other languages have the same diversity of approach but don't see it as being as much of a problem.
I wonder if the 'web applications are engineering projects' metaphor is a good map for the problem space. There may be others that would give us better mental tools for dealing with different classes of projects, perhaps 'web application styles are like literary forms'; we all know the difference between a short story, a sonnet and a sales pitch, and what situations each is appropriate for, and that some forms are more structured than others, and can make better use of predefined components.
# larry price