Project structure for Google App Engine
<p>I started an application in Google App Engine right when it came out, to play with the technology and work on a pet project that I had been thinking about for a long time but never gotten around to starting.  The result is <a href="http://www.bowlsk.com" rel="nofollow">BowlSK</a>.  However, as it has grown, and features have been added, it has gotten really difficult to keep things organized - mainly due to the fact that this is my first python project, and I didn't know anything about it until I started working.</p>

<p>What I have:</p>

<ul>
<li>Main Level contains:

<ul>
<li>all .py files (didn't know how to make packages work)</li>
<li>all .html templates for main level pages</li>
</ul></li>
<li>Subdirectories:

<ul>
<li>separate folders for css, images, js, etc.</li>
<li>folders that hold .html templates for subdirecty-type urls</li>
</ul></li>
</ul>

<p>Example:<br/>
<a href="http://www.bowlsk.com/" rel="nofollow">http://www.bowlsk.com/</a> maps to HomePage (default package), template at "index.html"<br/>
<a href="http://www.bowlsk.com/games/view-series.html?series=7130" rel="nofollow">http://www.bowlsk.com/games/view-series.html?series=7130</a> maps to ViewSeriesPage (again, default package), template at "games/view-series.html"</p>

<p>It's nasty.  How do I restructure?  I had 2 ideas:</p>

<ul>
<li><p>Main Folder containing: appdef, indexes, main.py?</p>

<ul>
<li>Subfolder for code.  Does this have to be my first package?</li>
<li>Subfolder for templates.  Folder heirarchy would match package heirarchy</li>
<li>Individual subfolders for css, images, js, etc.</li>
</ul></li>
<li><p>Main Folder containing appdef, indexes, main.py?</p>

<ul>
<li>Subfolder for code + templates.  This way I have the handler class right next to the template, because in this stage, I'm adding lots of features, so modifications to one mean modifications to the other.  Again, do I have to have this folder name be the first package name for my classes?  I'd like the folder to be "src", but I don't want my classes to be "src.WhateverPage"</li>
</ul></li>
</ul>

<p>Is there a best practice?  With Django 1.0 on the horizon, is there something I can do now to improve my ability to integrate with it when it becomes the official GAE templating engine?  I would simply start trying these things, and seeing which seems better, but pyDev's refactoring support doesn't seem to handle package moves very well, so it will likely be a non-trivial task to get all of this working again.</p>

<p>First, I would suggest you have a look at "<a href="http://sites.google.com/site/io/rapid-development-with-python-django-and-google-app-engine">Rapid Development with Python, Django, and Google App Engine</a>"</p>

<p>GvR describes a general/standard project layout on page 10 of his <a href="http://sites.google.com/site/io/rapid-development-with-python-django-and-google-app-engine/rapid_development_with_django_gae.pdf?attredirects=0">slide presentation</a>.  </p>

<p>Here I'll post a slightly modified version of the layout/structure from that page. I pretty much follow this pattern myself. You also mentioned you had trouble with packages. Just make sure each of your sub folders has an __init__.py file. It's ok if its empty.</p>

<h2>Boilerplate files</h2>

<ul>
<li>These hardly vary between projects</li>
<li>app.yaml: direct all non-static requests to main.py </li>
<li>main.py: initialize app and send it all requests </li>
</ul>

<h2>Project lay-out</h2>

<ul>
<li>static/*: static files; served directly by App Engine</li>
<li>myapp/*.py: app-specific python code
<ul>
<li>views.py, models.py, tests.py, __init__.py, and more</li>
</ul></li>
<li>templates/*.html: templates (or myapp/templates/*.html)</li>
</ul>

<p>Here are some code examples that may help as well:</p>

<h2>main.py</h2>

<pre><code>import wsgiref.handlers

from google.appengine.ext import webapp
from myapp.views import *

application = webapp.WSGIApplication([
  ('/', IndexHandler),
  ('/foo', FooHandler)
], debug=True)

def main():
  wsgiref.handlers.CGIHandler().run(application)
</code></pre>

<h2>myapp/views.py</h2>

<pre><code>import os
import datetime
import logging
import time

from google.appengine.api import urlfetch
from google.appengine.ext.webapp import template
from google.appengine.api import users
from google.appengine.ext import webapp
from models import *

class IndexHandler(webapp.RequestHandler):
  def get(self):
    date = "foo"
    # Do some processing		
    template_values = {'data': data }
    path = os.path.join(os.path.dirname(__file__) + '/../templates/', 'main.html')
    self.response.out.write(template.render(path, template_values))

class FooHandler(webapp.RequestHandler):
  def get(self):
    #logging.debug("start of handler")
</code></pre>

<h2>myapp/models.py</h2>

<pre><code>from google.appengine.ext import db

class SampleModel(db.Model):
</code></pre>

<p>I think this layout works great for new and relatively small to medium projects. For larger projects I would suggest breaking up the views and models to have their own sub-folders with something like:</p>

<h2>Project lay-out</h2>

<ul>
<li>static/: static files; served directly by App Engine
<ul>
<li>js/*.js</li>
<li>images/*.gif|png|jpg</li>
<li>css/*.css</li>
</ul></li>
<li>myapp/: app structure
<ul>
<li>models/*.py</li>
<li>views/*.py</li>
<li>tests/*.py</li>
<li>templates/*.html: templates</li>
</ul></li>
</ul>
