Docs refer to extras/csrf_migration_helper.py which is not packaged

[Paul Winkler]

There is a script called extras/csrf_migration_helper.py that is recommended by both the 1.3 and dev docs:
​https://docs.djangoproject.com/en/dev/ref/contrib/csrf/#how-to-use-it
and
​https://docs.djangoproject.com/en/1.3/ref/contrib/csrf/#how-to-use-it

However, the only way to get that script is by checking out django from SVN. It's not anywhere in the 1.3 release.

Either that script should be included in releases, or the docs should be changed to tell you to get it from svn, or something.

[Luke Plant]

I checked both the 1.3 and 1.3.1 tarballs from ​https://www.djangoproject.com/download/ and the script is indeed there, in the 'extras' directory as described. Perhaps you are experiencing some downstream packaging bug?

[Paul Winkler]

I see what's happening. The file is included in the tarball, but because it is not under the django/ directory, setuptools doesn't consider it part of the django package. So if you install django via easy_install or pip (which I typically do), you will never see that file.

$ virtualenv temp
$ cd temp
$ source bin/activate
$ pip install django==1.3.1
Downloading/unpacking django
...
$ find . -name csrf_migration_helper.py
$

I still think that's a problem.

[Luke Plant]

I don't think there is a way we can fix this, because there is no place for it to live. It doesn't belong inside the django namespace, and certainly not in a new 'extras' namespace.

Since csrf_migration_helper.py is only intended for use at development time, and as a one off, it doesn't need to be on a production machine, and falls under the category of something that is nice to have during development. This makes it essentially the same as docs, and pip/setuptools doesn't install docs either, or any other items under 'extras' which are also useful things to have offline.

We could possibly add it to 'scripts', but I don't think it is nice to litter the system PATH with something that is used at development time only, and is going to be used so rarely - once per project, really.

I believe the '-d' option to pip or the '--editable' option for easy_install should get you the full source tarball.

[Paul Winkler]

I think I would be happy if the docs just made some mention of "where is extras".

[Carl Meyer]

I agree with Luke that these extras scripts shouldn't be installed, but I agree with the OP that the documentation references to such scripts should be clearer about where they can (and can't) be found.

[Tim Graham <timograham@…>]

In 15202baace1453e7576806f13d137ae930de6dcb:

Fixed #17058 - Clarified where extras/csrf_migration_helper.py is located