Sane defaults for Startapp and Startproject

[Rich Jones]

Hey guys!

So I've just written a blog post about getting started with Django,
http://gun.io/blog/python-for-the-web/, and many of the things here
just make me think, 'why doesn't it just do that by default?'

Here's some of what I propose. I'm not suggesting this be a canonical
list of features by any means, I'm just suggesting that django have
more convenient default settings. We should look at the most common
conventions and best practices and shape the defaults towards them.

Anyway, I propose that:

django-admin.py startproject newproj

should create ./static, ./uploads and ./newproj and ./newproj/
templates

in ./newproj/settings.py..

import os
TEMPLATE_DIRS = (
os.path.join(os.path.dirname(__file__), 'templates'),
)

and at the end, the commonly used from local settings import * block.

I'd also suggest that django-admin.py startproject newapp, if
possible, add the new application to the settings.py file if it can be
done so safely.

I would also suggest that when making a new application, the most
commonly used imports are already there in the py files
(render_to_response, HttpResonse, get_object_or_404, etc).

Who's with me? :)

R

[Javier Guerra Giraldez]

hi,

here are my personal thoughts on the proposals:

On Tue, Oct 18, 2011 at 5:21 PM, Rich Jones <mise...@gmail.com> wrote:
> django-admin.py startproject newproj
>
> should create ./static, ./uploads and ./newproj and ./newproj/
> templates

-0

./static might be common, the others are way too specific.

> in ./newproj/settings.py..
>
> import os
> TEMPLATE_DIRS = (
>    os.path.join(os.path.dirname(__file__), 'templates'),
> )

+0

i use something similar. i don't like exactly this version, but
getting away from static absolute paths is always good

> and at the end, the commonly used from local settings import * block.

-1

there are too many flavors of that.

> I'd also suggest that django-admin.py startproject newapp, if
> possible, add the new application to the settings.py file if it can be
> done so safely.

-1

once the default settings.py is generated, it's my own; i don't want
any 'help process' meddling with it.

> I would also suggest that when making a new application, the most
> commonly used imports are already there in the py files
> (render_to_response, HttpResonse, get_object_or_404, etc).

0

i like the error messages when i don't include things.

--
Javier

[Carl Meyer]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi Rich,

On 10/18/2011 04:21 PM, Rich Jones wrote:
> So I've just written a blog post about getting started with Django,
> http://gun.io/blog/python-for-the-web/, and many of the things here
> just make me think, 'why doesn't it just do that by default?'
>
> Here's some of what I propose. I'm not suggesting this be a canonical
> list of features by any means, I'm just suggesting that django have
> more convenient default settings. We should look at the most common
> conventions and best practices and shape the defaults towards them.

Thanks for giving some thought to what would make Django easier for new
users.

> Anyway, I propose that:
>
> django-admin.py startproject newproj
>
> should create ./static, ./uploads and ./newproj and ./newproj/
> templates

+0.5 to creating static/ and templates/ directories. I know people may
use layouts where those live elsewhere, but I don't think I've ever seen
a real production Django codebase that didn't have a directory for
static assets and a main project-wide directory for templates, in the
same repo with the code.

- -1 to creating an uploads/ directory, I've seen (and written) many
projects that never handle user uploads at all.

> in ./newproj/settings.py..
>
> import os
> TEMPLATE_DIRS = (
> os.path.join(os.path.dirname(__file__), 'templates'),
> )

If startproject creates a templates/ dir, +1 to having it in the default
TEMPLATE_DIRS in a portable way like this.

Same with static/ and STATICFILES_DIRS.

> and at the end, the commonly used from local settings import * block.

- -1; this is often done, but it's far from a consensus best practice.

> I'd also suggest that django-admin.py startproject newapp, if
> possible, add the new application to the settings.py file if it can be
> done so safely.

I'd be -1 on this as well for the same reason as Javier.

> I would also suggest that when making a new application, the most
> commonly used imports are already there in the py files
> (render_to_response, HttpResonse, get_object_or_404, etc).

- -1 on this; I frequently have a views.py that doesn't use one or more of
these utilities (what if I prefer TemplateResponse instead of
render_to_response?). Users should get used to the idea that you import
what you actually need to use and don't have unused imports hanging around.

Carl
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk6eExEACgkQ8W4rlRKtE2cJAgCfdVEI4pysyolpayYs/oGvam20
WvIAnA34ivGF47ZczmCe/KAkHcqhhXAf
=lpHn
-----END PGP SIGNATURE-----

[Joe & Anne Tennies]

On Tue, Oct 18, 2011 at 5:21 PM, Rich Jones <mise...@gmail.com> wrote:

Hey guys!

So I've just written a blog post about getting started with Django,
http://gun.io/blog/python-for-the-web/, and many of the things here
just make me think, 'why doesn't it just do that by default?'

Here's some of what I propose. I'm not suggesting this be a canonical
list of features by any means, I'm just suggesting that django have
more convenient default settings. We should look at the most common
conventions and best practices and shape the defaults towards them.

Anyway, I propose that:

django-admin.py startproject newproj

should create ./static, ./uploads and ./newproj and ./newproj/
templates

I personally +1 on the ./static and ./uploads. I like a starting point for putting the static files and the uploaded files. If you don't use static files or uploaded files, it'll never get used and deleting a folder is pretty easy. For consistency, I'd rename ./uploads to ./media (to match the MEDIA_ROOT notation used in settings.py). I'd also fill-in MEDIA_URL ('/media'), MEDIA_ROOT, and STATIC_ROOT to work out of the gate. Is there a way to statically serve the MEDIA_ROOT folder to '/media/' without collectstatic collecting it and/or findstatic finding it by default?

 

in ./newproj/settings.py..

import os
TEMPLATE_DIRS = (
   os.path.join(os.path.dirname(__file__), 'templates'),
)

+1 for something to accomplish this. I personally don't care how it's done.

 

and at the end, the commonly used from local settings import * block.

-1 'from <module> import *' should always be avoided. You never know what can happen down the road that you may override later.

 

I'd also suggest that django-admin.py startproject newapp, if
possible, add the new application to the settings.py file if it can be
done so safely.

-1 I can see why this seems like a good idea, but I agree that I don't want anything touching my settings file. I also think people should learn how to start a new app and about manage.py, startapp seems like the obvious answer from a teaching perspective.

 

I would also suggest that when making a new application, the most
commonly used imports are already there in the py files
(render_to_response, HttpResonse, get_object_or_404, etc).

-1 If the exception wasn't so blatently obvious and worded well in the error, I might agree.

 

Who's with me? :)

R

--
You received this message because you are subscribed to the Google Groups "Django developers" group.
To post to this group, send email to django-d...@googlegroups.com.
To unsubscribe from this group, send email to django-develop...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/django-developers?hl=en.

I also want to add another change. Put TEMPLATE_CONTEXT_PROCESSORS in the settings.py. I would just it rather be more explicit that you may be using these things. If there's any other settings like this that 'slide' a default value in w/o your knowledge, I'd like it to add to the settings.py by default. Most problems I have helping people is a default value that's not explicitly done in the settings.py, so people don't realize it's something they can override (or may need to). My criteria would be anything that could require modification (within reason) when adding or removing an app to make the app work properly.  (See TEMPLATE_CONTEXT_PROCESSORS as an example.)

--
Joe & Anne Tennies
ten...@gmail.com

[h3]

I'd like the settings file to be more convenient too, but most of the
suggestion are too specific.

It's an excellent idea to automate more things, but it's a really bad
idea to pretend that we know
everybody's needs.

Personally here's what I'd like to see in the generated settings.py:

import os

PROJECT_PATH = os.path.dirname(os.path.abspath(__file__))

...

MEDIA_ROOT = os.path.join(PROJECT_PATH, 'media/')

...

TEMPLATE_DIRS = (
os.path.join(PROJECT_PATH, 'templates/'),
)

This would already be a big time saver.

Another things that would be nice is commonly used code like
TEMPLATE_CONTEXT_PROCESSORS,
some middlewares and apps being commented. This wouldn't hurt anybody
I think.

About adding stuff to views or other files generated by starapp or
startproject .. -1. I think the bare minimum is a win for everybody.

That said, it would be nice to let people write their own templates
for thoses files. Startapp and startproject could look for them
in a path like $USER/.django/templates/newapp/ or $USER/.django/
templates/newproject/ and/or let startapp/startproject accept
a --templates argument to make something like this possible:

python manage.py startapp myapp --templates=/some/path/templates/
newapp/

python manage.py startproject myproject --templates=/some/path/
templates/newproject/


my 2¢


On Oct 18, 9:20 pm, "Joe & Anne Tennies" <tenn...@gmail.com> wrote:

> tenn...@gmail.com

[stan]

Hi Rich,


I'am not Django core but I think that most of your propositions are
unpythonic/unkiss, unclear and way too specific or magical.

I don't want to waste 10 more minutes after a startapp/startproject to
think about what directory I have to remove and which files I have to
repair because all those additions does not fit with my arch.

There is no rules about local_settings.py (sometimes my local
dispatchs live in settings.py and can deal with that :-) nor about
media, static, templates (in app, in project, both or outside ?).

I thing this is clearly not the way to follow and not the spirit of
Python/Django. Again, Keep It Simple.

Cheers,

Stanislas.


On Oct 19, 3:20 am, "Joe & Anne Tennies" <tenn...@gmail.com> wrote:

> tenn...@gmail.com

[Aymeric Augustin]

On 19 oct. 2011, at 00:21, Rich Jones wrote:
> Here's some of what I propose. I'm not suggesting this be a canonical
> list of features by any means, I'm just suggesting that django have
> more convenient default settings. We should look at the most common
> conventions and best practices and shape the defaults towards them.

Hello,

Collecting static files and putting media uploads in the "project directory" (whatever that means) isn't really a best practice. In production, the code area should be read-only for the web server user: code goes in /usr/... and data in /var/www/...

In order to make deployment easier, I also recommend putting site-wide templates and templatetags in an application, and keeping TEMPLATE_DIRS empty, but that's a personal preference.

There are many ways to specialize settings by environment, and local_settings.py is only convenient for the smallest projects — as soon as two people work on the project, it's better to have "dev.py" / "prod.py" and to symlink or import * from the appropriate module.

Sorry for sounding negative, but I'm also against import pollution.

In short, I think that Django is a general purpose framework, and putting default values geared towards one-man projects isn't good for us in the long term. I prefer if newcomers have to read the appropriate page of the doc — discovering in the process that we have an excellent documentation — rather than blindly use the template loader or the static files without understanding it, and then complain that it breaks when they deploy to production.

Following Carl's cleanup of the PYTHONPATH mess, we considered writing a documentation page about project layout. It would touch many of the points discussed in your proposal. I think that's the best solution to the question discussed here: "how should I organize my (first) Django project?"

Best regards,

--
Aymeric Augustin.

[Gabriel Hurley]

Thanks for the suggestions, Rich... I'll try not to repeat what others have said, but have a couple notes to add:

should create ./static, ./uploads and ./newproj and ./newproj/
templates

I could get behind static, and maybe even templates, but absolutely not uploads. I would argue against Django automatically creating any directories inside your project that you wouldn't ever want to check into your VCS, and I definitely don't want my user uploads ever getting checked in to my repos. As others have noted, there are many other solutions for how those should be handled.

 

and at the end, the commonly used from local settings import * block.

Others have already spoken out against this, but as extra corroboration see our lovely BDFL Jacob's "Best and Worst of Django" presentation (particularly slides 46-51) where he argues against this explicitly (and rightly, IMHO).

 

As for the rest: I don't believe in adding magic in order to save a couple lines of typing (explicit > implicit), but I am in favor of things we can do to encourage best practices where the community agrees. So to that task I wish you excellent luck!

All the best,

    - Gabriel

[Andre Terra]

Hi all,

On Wed, Oct 19, 2011 at 5:50 AM, Gabriel Hurley <gab...@gmail.com> wrote:

Thanks for the suggestions, Rich... I'll try not to repeat what others have said, but have a couple notes to add:

(....)

As for the rest: I don't believe in adding magic in order to save a couple lines of typing (explicit > implicit), but I am in favor of things we can do to encourage best practices where the community agrees. So to that task I wish you excellent luck!

All the best,

    - Gabriel

I think you hit the nail on the head. This sounds to me like exactly what we need to discuss, regardless of how we address it. I'm not in favor of adding too much magic to startapp/startproject, except for maybe the templates dir, its relative import and explicitly listing every default settings (AUTHENTICATION_BACKENDS included). Again, explicit > implicit.

I do however believe that we need to create a section in the docs with some suggestions as to how to layout your project. Perhaps your blog post could be turned into a documentation patch? Too often when I was starting with Django I felt the need for such a guide, and even though we may not agree on one single solution, we should at least point to some "canonical" alternatives which we believe constitute best practices.

"Give a man a fish and you feed him for a day. Teach a man how to fish and you feed him for a lifetime."

This is a valid concern and request, and any experienced user will know enough Python and Django to roll out their own customized setup.


Cheers,
AT

[Gabriel Hurley]

I think there is sufficient interest in the idea of a "how to organize your Django project" page in the documentation that it would be worth beginning work on a patch for one, much in the way that the "How to contribute to Django"/"Spirit of contributing" page got started.

That means:

  1. Opening a ticket for it if one doesn't already exist.

  2. Creating a wiki page to start crafting the text where everyone can contribute.

  3. Writing an initial draft to get the ball rolling.

  4. Working with the mailing list to garner attention and consensus.

  5. Writing a patch in proper reST once general consensus has been reached.

I think there are going to be quite a few different opinions on this topic, so structuring it in such a way as to provide "Common patterns" with pros and cons of each would be a wise way to go about it.

[Carl Meyer]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi Aymeric,

On 10/19/2011 01:07 AM, Aymeric Augustin wrote:
> Collecting static files and putting media uploads in the "project
> directory" (whatever that means) isn't really a best practice. In
> production, the code area should be read-only for the web server
> user: code goes in /usr/... and data in /var/www/...

(FWIW, my +0.5 was for creating a static/ directory that would go in
STATICFILES_DIRS, definitely not setting a default value for STATIC_ROOT).

> In order to make deployment easier, I also recommend putting
> site-wide templates and templatetags in an application, and keeping
> TEMPLATE_DIRS empty, but that's a personal preference.

Just out of curiosity, why would you say it makes deployment easier to
put static assets and templates into an installed app, rather than using
TEMPLATE_DIRS/STATICFILES_DIRS? (Templatetags are a different issue;
those have to go in an app).

Carl
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk6ggvQACgkQ8W4rlRKtE2fHVACg2RxqopGeAYaMReVbV/u7SkVq
TuAAn1Zso3AYjGrtem6QFuhpZlq1tJS0
=OpHw
-----END PGP SIGNATURE-----

[Carl Meyer]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 10/19/2011 01:07 PM, Gabriel Hurley wrote:
> I think there is sufficient interest in the idea of a "how to organize
> your Django project" page in the documentation that it would be worth
> beginning work on a patch for one, much in the way that the "How to
> contribute to Django"/"Spirit of contributing" page got started.

Agreed.

> That means:
>
> 1. Opening a ticket for it if one doesn't already exist.

The ticket already exists: https://code.djangoproject.com/ticket/17044

Carl
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk6giaUACgkQ8W4rlRKtE2e10ACg55foQJffrStkk3iiekzaxmH6
f9YAoLQrpRPO+H2I8qPfMqssk5shkvrN
=bevB
-----END PGP SIGNATURE-----

[Aymeric Augustin]

On 20 oct. 2011, at 22:22, Carl Meyer wrote:

>> In order to make deployment easier, I also recommend putting
>> site-wide templates and templatetags in an application, and keeping
>> TEMPLATE_DIRS empty, but that's a personal preference.
>
> Just out of curiosity, why would you say it makes deployment easier to
> put static assets and templates into an installed app, rather than using
> TEMPLATE_DIRS/STATICFILES_DIRS? (Templatetags are a different issue;
> those have to go in an app).

I see two advantages:
- everything is an app: there are no special directories to handle when you build a package,
- templates and static files work with the same settings in development and production.

These arguments aren't very strong:
- you still have to ensure that static files and templates are properly packaged within apps,
- generally, you have different settings in development and production anyway, and the overhead of changing TEMPLATE_DIRS/STATICFILES_DIRS is negligible.

That's why I said it's a personal preference, maybe even an aesthetic matter :)

[Rich Jones]

How would you guys feel about a manage.py startexample

which would create an example application? A simple, templated hello
world with an example model and an example view and an example
template?

R

On Oct 20, 4:50 pm, Aymeric Augustin

[Carl Meyer]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi Rich,

On 10/21/2011 10:21 AM, Rich Jones wrote:
> How would you guys feel about a manage.py startexample
>
> which would create an example application? A simple, templated hello
> world with an example model and an example view and an example
> template?

Indifferent? I kinda feel like following the tutorial gives you this
already, and I'm not real excited about having another "sample project"
in core to maintain and update. OTOH I understand that a lot of people
learn best by tweaking existing working code, and if this were done
outside of core the people who most need it (beginners) are not likely
to be aware of it. Maybe there'd be a way to make it a downloadable part
of the docs rather than a management command?

I'm not going to work on this or commit it, but if other people
(including at least one core dev) are excited about it I wouldn't stand
in the way. So I guess that's a -0.

Carl
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk6huGUACgkQ8W4rlRKtE2dAWQCg6mKdlRHDkk+sPYJvafjyms5C
Q2wAoN70oNfxh3vTzd4W7DqrUCzO/RD8
=mCZ7
-----END PGP SIGNATURE-----

[Rich Jones]

Having an example project to fork/fiddle with in the documentation is
a fair compromise.

svn co http://code.djangoproject.com/svn/django/trunk/ django-example

?

R

On Oct 21, 2:22 pm, Carl Meyer <c...@oddbird.net> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> Hi Rich,
>
> On 10/21/2011 10:21 AM, Rich Jones wrote:
>
> > How would you guys feel about a manage.py startexample
>
> > which would create an example application? A simple, templated hello
> > world with an example model and an example view and an example
> > template?
>
> Indifferent? I kinda feel like following the tutorial gives you this
> already, and I'm not real excited about having another "sample project"
> in core to maintain and update. OTOH I understand that a lot of people
> learn best by tweaking existing working code, and if this were done
> outside of core the people who most need it (beginners) are not likely
> to be aware of it. Maybe there'd be a way to make it a downloadable part
> of the docs rather than a management command?
>
> I'm not going to work on this or commit it, but if other people
> (including at least one core dev) are excited about it I wouldn't stand
> in the way. So I guess that's a -0.
>
> Carl
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.10 (GNU/Linux)

> Comment: Using GnuPG with Mozilla -http://enigmail.mozdev.org/