Jannis has, I believe, previously mentioned in his SoC updates the 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."
On 7/8/07, James Bennett <ubernost...@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 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
On 7/9/07, Adrian Holovaty <holov...@gmail.com> wrote:
> On 7/8/07, James Bennett <ubernost...@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.
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.
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:
I thought you guys might appreciate some feedback from a total newbie.
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.
I definitely agree that some additional documentation is in order. 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.
On 7/9/07, Marty Alchin <gulop...@gamemusic.org> wrote:
> 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.
-- "Bureaucrat Conrad, you are technically correct -- the best kind of correct."
On 7/9/07, James Bennett <ubernost...@gmail.com> wrote:
> 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.
For each new site I work on I have a root folder which contains a copy 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.
> 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.
Adrian
-- Adrian Holovaty holovaty.com | djangoproject.com
