Improve names in password hash interface

[GoogleCodeExporter]

Certain parts of the password hash interface could have been named better.

encrypt()
---------
The name of the `.encrypt()` method has the implication that there might be a 
`.decrypt()` that recovers the password. This is of course not the case. 

One alternative name, `.encode()`, suffers a similar problem. Another 
alternative, `.digest()`, might be better... that name matches the 
similarly-purposed method used by the python hash interface (though the call 
syntax is different... would that cause confusion?) 

In any case, this rename could be done, though it would have to have a very 
slow deprecation cycle.

rounds
------
The name of standard parameter `rounds` reflects the unit of measurement, not 
the purpose: to adjust the time-cost of digesting a password. As well, it not 
technically correct for hashes which use a log2 cost parameter (eg bcrypt), as 
the actual number of iterations = 2**rounds. 

Renaming it (and related informational attributes) to `cost` would perhaps 
clarify things... though before doing so the nature of scrypt's multiple 
parameters should be studied to make sure a longer name such as `time_cost` 
isn't required. 

In any case, renaming this setting would be extremely disruptive and 
burdensome, particularly if the deprecation cycle was long (which it would need 
to be). So this will probably not be done any time soon (if ever).

Original issue reported on code.google.com by elic@astllc.org on 31 Aug 2011 at 11:06

[GoogleCodeExporter]

Original comment by elic@astllc.org on 31 Aug 2011 at 11:06

• Changed state: Discussing

[GoogleCodeExporter]

Original comment by elic@astllc.org on 7 Sep 2011 at 1:01

• Added labels: Type-Enhancement
• Removed labels: Type-Other

[GoogleCodeExporter]

Is there anything preventing this from happening? There's been no movement on 
it. Would a patch move this ticket forward?

Original comment by donald-...@stufft.io on 27 Apr 2013 at 2:57

[GoogleCodeExporter]

This is somewhat of a long-term ticket. It's main purpose is to let people know 
that I'm aware the naming could be improved... though I should probably spell 
out why nothing has happened yet.

---

What's holding this issue back isn't so much the coding, as it is remaining 
doubts I have about the usefulness of the change, when compared to the 
maintenance and compatibility costs it would incur.

I'm not normally uptight about API changes - I do it with barely a thought in 
some of my company's code, and I've been evolving Passlib slowly as well. But 
changing something this central in Passlib's API means pretty much all of it's 
userbase has to update their application code, and (for some of those 
applications) maintain backwards-compatibility with older versions of Passlib. 

To ease the transition, I'd want Passlib to support both old and new APIs for 
at least min(1.5 years, 2 minor releases). During that time, there would be the 
added complexity of duplicated code paths and unit tests, new code paths and 
tests devoted to handling mixed use of old and new APIs, and the potential for 
unforeseen new bugs. 

Compared to all of that, I'm not entirely sure making a few changes for 
semantic clarity is necessarily worth it. That said, I'm slowly improving bits 
of Passlib's API, leading up to a 2.0 release where I plan to strip out any 
deprecated APIs that are still lying around. If this API change gets made at 
all, it'll be in the 1.8 and 1.9 releases leading up to that. 

Original comment by elic@astllc.org on 27 Apr 2013 at 10:39