remember Tutorial users to invoke the shell by "python manage.py shell" before setting up the test environment

[anonymous]

Working through the Tutorial 5 I stumbled across something I haven't expected.
The tutorial suggest to setup the test environment, starting with:

>>> from django.test.utils import setup_test_environment

I used the standard python shell throughout the whole tutorial without any problems, but now I got the following message:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/usr/lib/python2.7/site-packages/django/test/__init__.py", line 5, in <module>
    from django.test.client import Client, RequestFactory
  File "/usr/lib/python2.7/site-packages/django/test/client.py", line 16, in <module>
    from django.contrib.auth import authenticate, login
  File "/usr/lib/python2.7/site-packages/django/contrib/auth/__init__.py", line 5, in <module>
    from django.middleware.csrf import rotate_token
  File "/usr/lib/python2.7/site-packages/django/middleware/csrf.py", line 16, in <module>
    from django.utils.cache import patch_vary_headers
  File "/usr/lib/python2.7/site-packages/django/utils/cache.py", line 26, in <module>
    from django.core.cache import get_cache
  File "/usr/lib/python2.7/site-packages/django/core/cache/__init__.py", line 70, in <module>
    if DEFAULT_CACHE_ALIAS not in settings.CACHES:
  File "/usr/lib/python2.7/site-packages/django/conf/__init__.py", line 53, in __getattr__
    self._setup(name)
  File "/usr/lib/python2.7/site-packages/django/conf/__init__.py", line 46, in _setup
    % (desc, ENVIRONMENT_VARIABLE))
django.core.exceptions.ImproperlyConfigured: Requested setting CACHES, but settings are not configured. 
You must either define the environment variable DJANGO_SETTINGS_MODULE or call settings.configure() 
before accessing settings.

Of course, this ought to be happen, since I have bypassed manage.py and thus the DJANGO_SETTINGS_MODULE environment variable wasn't set. Anyway, for django newbies who didn't follow your advise in part 1 of the tutorial this might come as an surprise.

My suggestions:

1) Make the consequences of bypassing manage.py in part 1 of the tutorial more explicit ("XYZ won't work unless ...")
2) Some newbies might appreciate at this early point of the tutorial a deeper explanation of the DJANGO_SETTINGS_MODULE environment variable.
3) Repeat the advise to invoke the shell through manage.py in "Tutorial 5 / Test a view", to help lazy newbies like me :-)

Best regards
Stephan

[Tim Graham]

I think the warning in part 1 is already quite explicit and the error message you encountered suggests what the problem is. Also the fact that you could do the rest of the tutorial with a plain python shell seems to be a bit odd -- perhaps you modified your PYTHONPATH to point to the current directory or something? I get errors if I don't use manage.py. If you can offer a patch, however, I'd be happy to take a look at your suggestion.

[st.sempert@…]

Timo!

a) No, I didn't changed PYTHONPATH, but I started python always from the project directory -- which seemed fine enough until it didn't.
b) I would be glad to offer a patch to the tutorial. As newbie I'm bit shy to fork the document on github and request a pull. Would you rather have my suggestions there or here e.g. as a attachment?

[Tim Graham]

If you'd like to attach a diff that would be fine, but I'm concerned that I can't reproduce the behavior you are seeing and maybe we should include a different piece of advice to avoid what's happening on your system that causes a plain python shell to work with the rest of the tutorial. Here's what I see. Could you include some more details regarding your setup?

~/code/mysite$ python
Python 2.7.3 (default, Apr 10 2013, 06:20:15)
[GCC 4.6.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> from polls import models
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "polls/models.py", line 3, in <module>
    from django.db import models
  File "/home/timgraham/code/django/django/db/__init__.py", line 97, in <module>
    signals.request_started.connect(reset_queries)
  File "/home/timgraham/code/django/django/dispatch/dispatcher.py", line 88, in connect
    if settings.DEBUG:
  File "/home/timgraham/code/django/django/conf/__init__.py", line 54, in __getattr__
    self._setup(name)
  File "/home/timgraham/code/django/django/conf/__init__.py", line 47, in _setup
    % (desc, ENVIRONMENT_VARIABLE))
django.core.exceptions.ImproperlyConfigured: Requested setting DEBUG, but settings are not configured. You must either define the environment variable DJANGO_SETTINGS_MODULE or call settings.configure() before accessing settings.

[st.sempert@…]

My setup: openSuse 12.3, python 2.7.3, django 1.5.2, eclipse kepler with pyDev and pyDev Django 2.7.0

I just went through the tutorial again and I think I found the "cause" for my mistake.

a) In my current setting no examples in part 1 work with plain python shell. Anyway, I assume I invoked manage.py there, since it is advised to do so in this part of the tutorial.
b) In part 2, 3 and 4 no examples include calls from the python shell -- which presumably gave me enough time to forget the warning in part 1. MY FAULT.
c) I can't replicate that the first part of tutorial 5 worked with plain python, neither from the bash nor from my current settings of kepler. BUT: there are way's to make it work in kepler/pyDev (as you certainly know) AND I have reorganized the project as part of my effort to "solve" the problem. I suppose I have killed a preference or something in the course of the reorganization without realizing.

Bottom Line:

I would suggest (and will append a corresponded diff later)

a) to remind the tutorial user in Part 5 to invoke the shell through manage.py or to make sure the DJANGO_SETTINGS_MODULE environment variable is set. I may not be the only one living in oblivion :-)

b) to explain the consequences of bypassing manage.oy without setting DJANGO_SETTINGS_MODULE environment variable in a less abstract way.

Another rather cautious suggestion: What about a few words in the Installation part of the doc about IDE's in general and maybe even pyDev/pyDev django in particular?

BTW: The quality of the django documentation and the tutorial in general is in imho excellent.

[Tim Graham]

a) Thanks for the investigation. My suggestion would be to replace "shell" in the docs with :djadmin:`shell` -- that will create a link to manage.py shell to create a reminder for the reader without being too verbose. Could you replace any occurrences of this in the other parts of the tutorial as well?

b) Sounds ok, I'll be interested to see the wording you come up with.

Regarding IDEs, I think it's outside the scope of Django's docs to recommend anything in that regard.

[bussau]

will do tomorrow. thx & good night

[Daniele Procida]

I've marked this ticket as especially suitable for first-time committers or people following the ​Don't be afraid to commit tutorial. If you're tackling this ticket, please don't hesitate to ask me for guidance if you'd like any, either here or on the Django IRC channels, where I can be found as EvilDMP.

[MaxV]

Working on this ticket at PyconIE Dublin sprint. About to submit a patch that solves part 'a' as suggested by timo in comment 7. Given that bussau hasn't provided a suggested wording for part 'b', I will not include an attempt at that fix myself. Perhaps that deserves a ticket of it's own?

[Tim Graham <timograham@…>]

In 13ddf0e0027b7646953a4c7d872ca682667c9b3f:

Fixed #21027 -- Updated tutorial 5 docs to link to management shell command page.

[Tim Graham <timograham@…>]

In e532d1e38f30689f6483ee5fd580eaf8d08a6b1e:

[1.5.x] Fixed #21027 -- Updated tutorial 5 docs to link to management shell command page.

Backport of 13ddf0e002 from master

[Tim Graham <timograham@…>]

In 8f5ea9d19b7a50839dead7eaf2ce6566e336067d:

[1.6.x] Fixed #21027 -- Updated tutorial 5 docs to link to management shell command page.

Backport of 13ddf0e002 from master