Default application layout, project/app distinction and encouraging best practices
James Bennett
possibility of changing the default app skeleton Django uses for the
'startapp' target, or at least providing an alternate skeleton more
suited to distributable/packageable applications. I'd like to revisit
that, and the way we document the process of writing Django
applications, because I think they're closely related and have warts
that need to be worked out as we head toward easy packaging and
distribution of apps.
The default app skeleton is sparse, and that's a good thing -- it
leaves out lots of optional bits and optimizes for the common case of
an application which provides some models and views. But at the same
time, it'd be awfully handy if it also at least dropped a blank
setup.py for packaging, and possibly some other distribution-oriented
metadata. Ideally, we could also subtly encourage best practices by
dropping 'docs' and 'tests' directories into the skeleton as well.
The way we teach people to write applications is really the more
problematic thing, though; the tutorial works off 'manage.py startapp'
and has the sample application developed inside of -- and, more
importantly -- completely coupled to the sample project (witness all
the 'from mysite.polls' imports in the tutorial). That's good for a
quick start with Django, because it reduces the number of things
people have to learn just to start playing with the APIs, but it's
also extremely bad because it encourages poor practice.
I've noticed that one of the biggest stumbling blocks a lot of people
have when they venture out of the tutorial/experimentation phase and
start writing "real" applications is that they don't realize the best
practice is to do exactly the opposite of what the tutorial suggests:
develop the application standalone, usually directly on your Python
path, and independent of any particular project. The fact that we've
gotten people used to 'manage.py startapp' instead of 'django-admin.py
startapp' really hurts us there, because manage.py only works within a
project and can't be used to start an independent application.
So I'd like to propose that, as we move closer to having
packaged/distributed apps supported directly, we do a couple things in
support of that (some of which, though not necessarily all, will
probably fall onto Jannis' SoC plate):
1. Expand the default application skeleton, or differentiate somehow
between a minimal, "traditional" app skeleton and a more robust one
which includes files and directories oriented at a distributable
application.
2. Spend a lot more time documenting best practices of application
development, possibly even mentioning in the tutorial that the "apps
inside project" model it uses is followed for convenience and not
because it's the best/only way to work.
Any thoughts or strong opinions one way or another?
--
"Bureaucrat Conrad, you are technically correct -- the best kind of correct."
Adrian Holovaty
> 1. Expand the default application skeleton, or differentiate somehow
> between a minimal, "traditional" app skeleton and a more robust one
> which includes files and directories oriented at a distributable
> application.
>
> 2. Spend a lot more time documenting best practices of application
> development, possibly even mentioning in the tutorial that the "apps
> inside project" model it uses is followed for convenience and not
> because it's the best/only way to work.
>
> Any thoughts or strong opinions one way or another?
I'm heavily in favor of #2, documenting best practices of application
development. Personally I never use "projects" -- they were just a
quick thing we made up just before we open-sourced Django, with the
thinking being "projects" would make it quicker and easier for people
to get started. Some solid documentation in this area -- both a
standalone document and notes in appropriate places in the tutorial --
would be excellent.
I'm not too crazy about #1, if only because two options makes things
more confusing, but I could be convinced otherwise with a decent
proposal.
Adrian
--
Adrian Holovaty
holovaty.com | djangoproject.com
Russell Keith-Magee
>
> On 7/8/07, James Bennett <ubern...@gmail.com> wrote:
> > 1. Expand the default application skeleton, or differentiate somehow
> > between a minimal, "traditional" app skeleton and a more robust one
> > which includes files and directories oriented at a distributable
> > application.
> >
> > 2. Spend a lot more time documenting best practices of application
> > development, possibly even mentioning in the tutorial that the "apps
> > inside project" model it uses is followed for convenience and not
> > because it's the best/only way to work.
> >
> > Any thoughts or strong opinions one way or another?
>
> I'm heavily in favor of #2, documenting best practices of application
> I'm not too crazy about #1, if only because two options makes things
...
I pretty much concur with Adrian.
Anything more than a basic skeleton for an app is going to end up
being wrong more often than it is right. I can see your point
regarding adding default metadata, etc for an app - that sort of
addition might be worthwhile, but beyond simple additions of that
sort, I'm not sure I see much value in beefing up the template
projects.
Besides, about the only time I ever use startapp/startproject is when
I'm trying to debug a problem that someone has had with the tutorial.
I usually end up rolling my own or copying an existing project/app as
a starting point. If we're not going to eat the dogfood... :-)
I think #2 is where the effort is worthwhile. Actually, I would
broaden the scope a little. I don't know why, but there seems to be a
general misunderstanding about exactly what Django is. A lot of people
seem to treat Django as some sort of magical programming language on
its own, rather than a set of APIs and tools built on and for Python.
A fair number of the questions asked regularly on the users list could
be avoided if the point was made that Django code is just Python code
- if it isn't legal Python, it isn't going to work in Django, and any
nifty trick that works in Python will work in Django too. Using the
tutorials to reinforce the point that Django == Python would hopefully
reduce the frequency of these questions. Pointing out the possibility
of putting apps outside the project directory would be one good way to
exemplify the point.
Yours,
Russ Magee %-)
Jeremy Dunck
> A fair number of the questions asked regularly on the users list could
> be avoided if the point was made that Django code is just Python code
I think a fair number of people start learning Python at the same time
the start learning Django.
This is not a bad thing!
Perhaps we should make the point that learning Python is a worthwhile
thing, and link them to the tutorial. ... I haven't seen one web page
that explains exactly how sys.path and sys.modules get built up, but
that'd be good too. Nearest I can find:
http://effbot.org/pyref/import.htm
http://effbot.org/zone/import-confusion.htm
http://www.python.org/doc/essays/packages.html
http://docs.python.org/lib/module-site.html
...Which is an awful lot to read in order to get going. :-/
cjl
I am trying to learn Django and Python and the same time, and greatly
appreciate the documentation available on Djangoproject and in the
Django Book. They are clearly one of Django's greatest strengths.
I have worked through the tutorials, and I must say that it is not
clear to me at all that I can build a website using Django and not use
'projects'. A newbie (like me) would ask: where would settings.py and
urls.py live? Without manage.py how could I launch the development
server, sync my database, etc.
I'm guessing that other newbies like me would also be confused when
the hear the core developers say that they don't use 'projects' when
developing with Django.
Also confusing, why include 'startapp' functionality in django-admin
and in manage.py? In fact, maybe I missed it in the tutorial, but I
didn't even know I could do 'django-admin startapp', but I guess it
does make sense.
I'm not asking for answers to the above questions, I'm just pointing
out that most newbies reading the official documentation would
probably have the same questions. I don't think all of the questions
would arise from a lack of Python knowledge.
Thanks again for all the hard work, and sorry for jumping in on this
discussion.
Marty Alchin
Over the past few months, I've released a couple apps that used to be
tied specifically to a project, and I had quite a bit of
back-and-forth on this list trying to figure out the best practices
for releasing them.
I think the single biggest improvement that could be made in any of
this documentation is that we could express very clearly that it's in
everbody's best interests to make an app reusable. Even if a developer
doesn't plan on distributing an app, making it reusable will make it
more useful even internally.
I don't know if this is what Adrian was referring to, but I would
think an ideal "project" would be nothing more than settings.py,
urls.py (which might be split into multiple files), a set of templates
and static media content. Essentially, in addition to models, every
app would be written to have generic views, which can be dropped into
any environment, provided the proper dependencies are provided.
Of course, not everything fits into the ideal project, so most people
are still going to have a few things that are specific to a project,
but if apps are written well, this would be minimal. I expect it would
mostly just be special views for site-specific custom form handling.
That said, I had been considering doing a nice, long writeup on
advanced Django development, picking up where Pro Django leaves off,
with part of it being dedicated to planning for a distributed app.
From the sounds of this conversation though, planning for a reusable
app shouldn't be considered advanced, but rather standard.
-Gul
James Bennett
> I don't know if this is what Adrian was referring to, but I would
> think an ideal "project" would be nothing more than settings.py,
> urls.py (which might be split into multiple files), a set of templates
> and static media content. Essentially, in addition to models, every
> app would be written to have generic views, which can be dropped into
> any environment, provided the proper dependencies are provided.
That's pretty much what I've been doing for a good long while now;
djangosnippets.org, for example, is a project that has a settings
file, root URLConf and templates, and everything else lives inside the
apps it uses.
The biggest hurdle I've seen a lot of people hit is the "how do I have
a home page" question; some folks even go so far as to dedicate an
application to that, which I personally think is overkill, but it'd be
nice if we're going to write up best practices to document ways of
tackling that problem.
Marty Alchin
> That's pretty much what I've been doing for a good long while now;
> djangosnippets.org, for example, is a project that has a settings
> file, root URLConf and templates, and everything else lives inside the
> apps it uses.
Good to know I was on the right track.
> The biggest hurdle I've seen a lot of people hit is the "how do I have
> a home page" question; some folks even go so far as to dedicate an
> application to that, which I personally think is overkill, but it'd be
> nice if we're going to write up best practices to document ways of
> tackling that problem.
Well, as I was just refactoring one of my projects to use more generic
views, I found that direct_to_template works quite well for my home
page needs. I don't know if that's an adequate recommendation, but it
should do for most sites, I would think.
-Gul
Nick
> On 7/9/07, Russell Keith-Magee <freakboy3...@gmail.com> wrote:
>
> > A fair number of the questions asked regularly on the users list could
> > be avoided if the point was made that Django code is just Python code
>
> I think a fair number of people start learning Python at the same time
> the start learning Django.
That was the case for me when I started, and I know I made some poor
app layout decisions to begin with (probably because of this).
I agree that more documentation in this area would be very handy for
newcomers.
Tai Lee
of Django, other 3rd party libs I need, and a Django project for my
site. I do this so I can upgrade or customise Django for each site
individually without breaking other sites. I'll probably switch back
to a common Django after 1.0 is released.
I usually treat the Django "project" as an application by adding it to
the INSTALLED_APPS list and adding models, views, and templates
directly to the project folder. I guess this is basically just an app
in my pythonpath + a settings.py and a manage.py.
If it's a large project that can be broken up into several
applications, i put those in root/myproject/apps/myapp. I had never
considered putting apps at the root level completely outside of any
Django project folder. I can see now that I could benefit by putting
any extra apps at the root level alongside Django and myproject, so
they can be more easily re-used by other sites/projects.
I did find that I do a lot of small sites which have pretty much the
same structure, so I thought it'd be nice to be able to specify a skel
folder or a skel settings file during startproject or startapp which
would create the folder structure I commonly need. e.g. django-
admin.py startproject --skel ~/django_skel, could just copy the files
and folders across, and if there's a settings.py it could override the
options from the default settings.py with those found in my ~/
django_skel/settings.py. This wouldn't require Django developers to
determine a best fit skel for all users, but would allow users who
create many small sites/projects to setup their own skel structure.
Adrian Holovaty
> Thanks again for all the hard work, and sorry for jumping in on this
> discussion.
For the record, there's absolutely no need to apologize for jumping
in! Your comments were very insightful -- I wish more relative
newcomers would participate in these sorts of discussions. Thanks very
much.