Docs - Using Argon2 with Django - more appropriate pip command

[Matt C]

On ​this docs page:

The recommended command to install argon2 is:

pip install django[argon2]

This tripped me up when upgrading to 1.10 from 1.9.x.

Should it not be:

pip install argon2_cffi

...as is recommended ​here?

[Simon Charette]

Hi freshquiz,

This tripped me up when upgrading to 1.10 from 1.9.x.

I'm not sure about what you mean here. The 1.10 documentation you linked to assumes you have Django 1.10 installed which exposes the argon2 ​extra requirement.

Running pip install django[argon2] with Django 1.10 installed should be equivalent to pip install "argon2-cffi>=16.1.0".

[Matt C]

Thanks charettes.

I hadn't used the [] pip syntax before and hadn't realised that django[argon2] roughly translates to:

django + argon2 (extra requirement)

It makes sense now, but I still think the docs should change (as the ticket description outlines), to separate the installation of Django itself and argon2 (from pip), so as to prevent others not familiar with the [] pip syntax, from stumbling as I did.

I tripped up by simply changing my requirements.txt file to include django[argon2], in addition to modifying Django==1.9.5 --> Django==1.10. So the combination of django[argon2] and Django==1.10 produced conflicts in pip.
My point being is if the docs said argon2_cffi, we wouldn't be having this conversation.

If you don't think it's worth the change, please feel free to close the ticket, otherwise I don't mind creating a PR for it.

[Simon Charette]

I see, as I'm familar with the syntax I'll let other contributor chime in to figure out whether or not the documentation should be adjusted.

FWIW the correct way of specifying your requirement would be Django[argon2]>=1.10 which should be read as Django >= 1.10 with the argon2 extra requirement.

[Tim Graham]

I suppose a clarification wouldn't hurt, although this wording is copy/pasted from the bcrypt steps so similar changes should be done there. I think we could replace "downloading the library and installing it with python setup.py install" (which I think is mostly obsolete these days -- at least, I wouldn't recommend that to anyone new who doesn't know how to install a library) to the pip install argon2-cffi>=16.1.0. The only downside I see there is hardcoding the argon2-cffi version.

[Matt C]

Is hardcoding the version necessary?

Wouldn't argon2-cffi give the latest stable version?

[Tim Graham]

It's possible (though probably unlikely for most users) that an older version of the package could already be installed.

[Ryan Castner]

If you have Django <1.10 and run pip install django[argon2] you get a nice error message Django 1.9.5 does not provide the extra 'argon2'. pip install argon2-cffi>=16.1.0 would give no such clarification. Are we sure this should be in there? You shouldn't really be doing the original install by appending to requirements.txt argon2-cffi>-16.1.0 should you? It should be through pip and after you ensure everything works you pin the requirement.

I do agree though that installing libraries with setup tools as part of the recommendation is probably somewhat obsolete now.

[Tim Graham]

Does this clarify help? ​PR

[GitHub <noreply@…>]

In 9f27735:

Fixed #27013 -- Clarified commands to install argon2/bcrypt packages.

[Tim Graham <timograham@…>]

In 7c0c3fb6:

[1.10.x] Fixed #27013 -- Clarified commands to install argon2/bcrypt packages.

Backport of 9f27735612fc775380d7801c68af0ea1c97cf5a3 from master