Refactor low-level functions

CHANGELOG.rst

@@ -10,6 +10,14 @@ The third digit is only for regressions.
 
 Vendoring ``argon2`` @ 4fe0d8cda37691228dd5a96a310be57369403a4b_.
 
+Deprecations:
+^^^^^^^^^^^^^
+
+- ``hash_password()``, ``hash_password_raw()``, and ``verify_password()`` should not be used anymore.
+  For hashing passwords, use the new ``argon2.PasswordHasher``.
+  If you want to implement your own higher-level abstractions, use the new low-level APIs ``hash_secret()``, ``hash_secret_raw()``, and ``verify_secret()`` from the ``argon2.low_level`` module.
+  The old functions will *not* raise any warnings though and there are *no* immediate plans to remove them.
+
 Changes:
 ^^^^^^^^
 

dev-requirements.txt

@@ -1,5 +1,4 @@
 coverage
 hypothesis
-hypothesis-pytest
 pytest
 wheel

docs/api.rst

@@ -37,34 +37,40 @@ Low Level
 
 Use these functions if you want to build your own high-level abstraction.
 
-.. autofunction:: hash_password
+.. autoclass:: Type
+  :members: D, I
+
+
+.. module:: argon2.low_level
+
+.. autofunction:: hash_secret
 
 .. doctest::
 
   >>> import argon2
-  >>> argon2.hash_password(
+  >>> argon2.low_level.hash_secret(
   ...     b"secret", b"somesalt",
-  ...     time_cost=1,         # number of iterations
-  ...     memory_cost=8,       # used memory in KiB
-  ...     parallelism=1,       # number of threads used; changes hash!
-  ...     hash_len=64,         # length of resulting raw hash
-  ...     type=argon2.Type.D,  # choose Argon2i or Argon2d
+  ...     time_cost=1, memory_cost=8, parallelism=1, hash_len=64, type=argon2.Type.D
   ... )
   b'$argon2d$m=8,t=1,p=1$c29tZXNhbHQ$H0oN1/L3H8t8hcg47pAyJZ8toBh2UbgcMt0zRFrqt4mEJCeKSEWGxt+KpZrMwxvr7M5qktNcc/bk/hvbinueJA'
 
 
-.. autofunction:: verify_password
+.. autofunction:: verify_secret
 
 
 The raw hash can also be computed:
 
-.. autofunction:: hash_password_raw
+.. autofunction:: hash_secret_raw
 
 .. code-block:: pycon
 
-  >>> argon2.hash_password_raw(b"secret", b"somesalt")
+  >>> argon2.low_level.hash_password_raw(b"secret", b"somesalt")
   b'\xd8\x87h5X%U<[\xf7\x0e\x18T\x9a\x96\xf3'
 
 
-.. autoclass:: Type
-  :members: D, I
+Deprecated APIs
+---------------
+
+.. autofunction:: argon2.hash_password
+.. autofunction:: argon2.hash_password_raw
+.. autofunction:: argon2.verify_password

src/argon2/__init__.py

@@ -2,19 +2,21 @@
 
 from __future__ import absolute_import, division, print_function
 
-from . import exceptions
-from ._util import Type
-from ._api import (
+from . import exceptions, low_level
+from ._legacy import (
+    hash_password,
+    hash_password_raw,
+    verify_password,
+)
+from ._password_hasher import (
     DEFAULT_HASH_LENGTH,
     DEFAULT_MEMORY_COST,
     DEFAULT_PARALLELISM,
     DEFAULT_RANDOM_SALT_LENGTH,
     DEFAULT_TIME_COST,
-    hash_password,
-    hash_password_raw,
-    verify_password,
+    PasswordHasher,
 )
-from ._password_hasher import PasswordHasher
+from ._util import Type
 
 
 __version__ = "16.0.0.dev0"
@@ -41,5 +43,9 @@
     "exceptions",
     "hash_password",
     "hash_password_raw",
+    "hash_secret",
+    "hash_secret_raw",
+    "low_level",
     "verify_password",
+    "verify_secret",
 ]

src/argon2/_legacy.py

@@ -0,0 +1,66 @@
+"""
+Legacy mid-level functions.
+"""
+
+from __future__ import absolute_import, division, print_function
+
+import os
+
+from ._util import Type
+
+from ._password_hasher import (
+    DEFAULT_HASH_LENGTH,
+    DEFAULT_MEMORY_COST,
+    DEFAULT_PARALLELISM,
+    DEFAULT_RANDOM_SALT_LENGTH,
+    DEFAULT_TIME_COST,
+)
+from .low_level import hash_secret, hash_secret_raw, verify_secret
+
+
+def hash_password(password, salt=None,
+                  time_cost=DEFAULT_TIME_COST,
+                  memory_cost=DEFAULT_MEMORY_COST,
+                  parallelism=DEFAULT_PARALLELISM,
+                  hash_len=DEFAULT_HASH_LENGTH,
+                  type=Type.I):
+    """
+    Legacy alias for :func:`hash_secret` with default parameters.
+
+    .. deprecated:: 16.0.0
+        Use :class:`PasswordHasher` for passwords.
+    """
+    if salt is None:
+        salt = os.urandom(DEFAULT_RANDOM_SALT_LENGTH)
+    return hash_secret(
+        password, salt, time_cost, memory_cost, parallelism, hash_len, type
+    )
+
+
+def hash_password_raw(password, salt=None,
+                      time_cost=DEFAULT_TIME_COST,
+                      memory_cost=DEFAULT_MEMORY_COST,
+                      parallelism=DEFAULT_PARALLELISM,
+                      hash_len=DEFAULT_HASH_LENGTH,
+                      type=Type.I):
+    """
+    Legacy alias for :func:`hash_secret_raw` with default parameters.
+
+    .. deprecated:: 16.0.0
+        Use :class:`PasswordHasher` for passwords.
+    """
+    if salt is None:
+        salt = os.urandom(DEFAULT_RANDOM_SALT_LENGTH)
+    return hash_secret_raw(
+        password, salt, time_cost, memory_cost, parallelism, hash_len, type
+    )
+
+
+def verify_password(hash, password, type=Type.I):
+    """
+    Legacy alias for :func:`verify_secret` with default parameters.
+
+    .. deprecated:: 16.0.0
+        Use :class:`PasswordHasher` for passwords.
+    """
+    return verify_secret(hash, password, type)