Opened 6 years ago

Closed 6 years ago

Last modified 6 years ago

#27013 closed Cleanup/optimization (fixed)

Docs - Using Argon2 with Django - more appropriate pip command

Reported by: Matt C Owned by: nobody
Component: Documentation Version: 1.10
Severity: Normal Keywords: documentation password argon2 pip
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no


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 is recommended here?

Change History (10)

comment:1 Changed 6 years ago by 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".

comment:2 Changed 6 years ago by 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.

comment:3 Changed 6 years ago by 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.

comment:4 Changed 6 years ago by Tim Graham

Triage Stage: UnreviewedAccepted
Type: BugCleanup/optimization

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 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.

comment:5 Changed 6 years ago by Matt C

Is hardcoding the version necessary?

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

comment:6 Changed 6 years ago by Tim Graham

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

comment:7 Changed 6 years ago by 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.

comment:8 Changed 6 years ago by Tim Graham

Has patch: set

Does this clarify help? PR

comment:9 Changed 6 years ago by GitHub <noreply@…>

Resolution: fixed
Status: newclosed

In 9f27735:

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

comment:10 Changed 6 years ago by Tim Graham <timograham@…>

In 7c0c3fb6:

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

Backport of 9f27735612fc775380d7801c68af0ea1c97cf5a3 from master

Note: See TracTickets for help on using tickets.
Back to Top