One thing that Paste has in it is a command to create a set of files for a new project. The idea of this (admittedly borrowed directly from Rails) is to strongly encourage people to use a common set of conventions.
But, of course, the conventions should be good! So, what should an application look like (at least a Paste app, but maybe any web app)? Here's my current thoughts (files that are only meaningful for Webware-ish applications are marked with *):
ProjectName/
setup.py
ProjectName.egg-info/
?
projectname/
__init__.py
app_config.conf
sample_config.conf
sitepage.py *
web/ *
sample.py *
templates/
standard_template.XXX
sample.XXX
resources/
stylesheet.css
doc/
ProjectName.txt
The aspect that's specific to Webware (and Wareweb) is a directory of servlets and an abstract application-specific superclass for those servlets. Everything else feels reasonably standard to me. We don't have completely standard names, but the ideas are the same across frameworks. And some systems have more or different hierarchy -- a models package, for instance -- but that's really an aside to this, just like web is an aside.
resources/ is where static associated files go (I don't like the name, but eh). These can potentially be mapped into someplace where Apache can serve them directly, or Paste can serve them for expedience.
The configuration changes a bit from the current Paste standard. In practice there's a few kinds of configuration. One is the application configuring itself for Paste -- to tell Paste what kind of application it is (e.g., the framework), where some basic files are, what some defaults are for the application-specific configuration. This is in app_config.conf, and is shared by all application instances.
sample_config.conf is basis for a configuration file that describes one installation of an application. app_config.conf would be loaded first, and the instance configuration file can override anything it wants. This describes one fully-instantiated WSGI application.
The last bit of configuration is the deployment configuration. This is the server/app hookup, though it can be more than that, like you might simply put the application into a server process that is already running other applications (using paste.urlmap).
This also adds a setup.py, which I hadn't used before. In the past I have avoided installing applications as globally-importable code, because of versioning issues and because it didn't seem that useful. With Eggs and easy_install/setuptools the versioning is no longer an issue, and the way deployment works with setuptools is finally starting to click for me.
Lastly the .egg-info directory is for some other Egg/setuptools/easy_install metadata, but I'm not yet sure quite what that will be (most of the standard metadata goes in setup.py).
One thing I clearly forgot is tests. Do tests go in the projectname/ directory? I used to put them there, but now I think not. I think there should be another ProjectName/tests/ directory, with a test_config.conf file, a conftest.py file (for py.test configuration), and perhaps new servlets/resources should automatically create a stub tests/test_newservlet.py file, which might start with a (disabled) extremely simple existance test.
# Ian Bicking
I tend to think of resources in the RESTful sense, so if anything, I would put my objects into a "resources" folder, and my templates into a "representations" folder. Static files (images, scripts, styles) would reside in sub-folders of the "static" folder.
My two cents,
- Daniel Burr
# anonymous
Good point. Like I said, I didn't really like resources, but then I don't like static either (though that's actually what I've been using up to now). It defines it purely by its source... which is kind of okay -- I'm not obsessive about this kind of naming -- but I feel like there should be some better name. media might be a good name -- it seems a bit odd for CSS and Javascript, but even there it's not entirely bad. Or perhaps separate out Javascript particularly (along with other programmer-centric files like an XSLT stylesheet). This helps separate files out by roles; at least for those people who work in a collaborative atmosphere, there's a significant practical difference between Javascript and CSS/images, in that it's a very different group of people working with them.
# Ian Bicking
Agreed, "static" isn't too hot either. I think I'll just bite the bullet and go with "mimetypes", and categorize the static content in that way. I could see this approach becoming painful if you had a lot of different types, but for my usual scenario, there would just be text/javascript, text/css, and image/png; not too terrible, I think.
# L. Daniel Burr
But then you are just duplicating the file extensions in the directory layout. DRY, and all that. Some people are anti-file-extension, but I'm actually not in URLs (and definitely not on disk) at least insofar as the extension indicates the content type of the response, not the content type on disk.
There's so many ways to cut it, maybe "static" is the best because it's just the least complex.
# Ian Bicking
Like everything else in software engineering, this depends on your needs.
Have one js file that everything needs? One simple .css file that everything uses?
Sure, stick them in static.
Have a bazillion php files, each depending on a complex system of rules to generate the various CSS files it's using? Things get more complicated.