From fade17c9ee0e291ce4af13097dd95d8ace777bc6 Mon Sep 17 00:00:00 2001
From: Hynek Schlawack <hs@ox.cx>
Date: Sat, 22 Feb 2025 08:45:03 +0100
Subject: [PATCH] Add get_default_parameters & UnsupportedParametersError to
 API docs

---
 docs/api.rst                  |  8 +++++++-
 src/argon2/_utils.py          |  4 ++--
 src/argon2/exceptions.py      | 12 +++---------
 src/argon2/profiles.py        |  3 +++
 tests/test_password_hasher.py |  6 +++---
 5 files changed, 18 insertions(+), 15 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst
index fd8cde1..e6a7e2d 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -14,7 +14,8 @@ If you don't specify any parameters, the following constants are used:
 .. data:: DEFAULT_MEMORY_COST
 .. data:: DEFAULT_PARALLELISM
 
-They are taken from :data:`argon2.profiles.RFC_9106_LOW_MEMORY`.
+They are taken from :data:`argon2.profiles.RFC_9106_LOW_MEMORY`, but they may vary depending on the platform.
+You can use :func:`argon2.profiles.get_default_parameters` to get the current platform's defaults.
 
 
 Profiles
@@ -79,6 +80,8 @@ That should give you a feeling on how they perform in *your* environment.
    .. versionadded:: 21.2.0
 
 
+.. autofunction:: argon2.profiles.get_default_parameters
+
 .. _`RFC 9106`: https://www.rfc-editor.org/rfc/rfc9106.html
 
 
@@ -95,6 +98,9 @@ Exceptions
 
 .. autoexception:: argon2.exceptions.InvalidHash
 
+.. autoexception:: argon2.exceptions.UnsupportedParametersError
+
+
 
 Utilities
 ---------
diff --git a/src/argon2/_utils.py b/src/argon2/_utils.py
index fd56c17..21a6362 100644
--- a/src/argon2/_utils.py
+++ b/src/argon2/_utils.py
@@ -8,7 +8,7 @@ import sys
 from dataclasses import dataclass
 from typing import Any
 
-from .exceptions import InvalidHashError, UnsupportedParamsError
+from .exceptions import InvalidHashError, UnsupportedParametersError
 from .low_level import Type
 
 
@@ -171,4 +171,4 @@ def validate_params_for_platform(params: Parameters) -> None:
     """
     if _is_wasm() and params.parallelism != 1:
         msg = "In WebAssembly environments `parallelism` must be 1."
-        raise UnsupportedParamsError(msg)
+        raise UnsupportedParametersError(msg)
diff --git a/src/argon2/exceptions.py b/src/argon2/exceptions.py
index c0d9a32..a0dade5 100644
--- a/src/argon2/exceptions.py
+++ b/src/argon2/exceptions.py
@@ -46,21 +46,15 @@ class InvalidHashError(ValueError):
     """
 
 
-class UnsupportedParamsError(ValueError):
+class UnsupportedParametersError(ValueError):
     """
-        Raised if the current platform does not support the parameters.
+    Raised if the current platform does not support the parameters.
 
-        For example, in WebAssembly parallelism must be set to 1.
+    For example, in WebAssembly parallelism must be set to 1.
 
     .. versionadded:: 25.1.0
     """
 
-    def __init__(
-        self,
-        message: str = "Params are not compatible with the current platform",
-    ) -> None:
-        super().__init__(message)
-
 
 InvalidHash = InvalidHashError
 """
diff --git a/src/argon2/profiles.py b/src/argon2/profiles.py
index d5cd049..e6fd69b 100644
--- a/src/argon2/profiles.py
+++ b/src/argon2/profiles.py
@@ -21,6 +21,9 @@ def get_default_parameters() -> Parameters:
     """
     Create default parameters for current platform.
 
+    Returns:
+        Default, compatible, parameters for current platform.
+
     .. versionadded:: 25.1.0
     """
     params = RFC_9106_LOW_MEMORY
diff --git a/tests/test_password_hasher.py b/tests/test_password_hasher.py
index 791e854..9a29d07 100644
--- a/tests/test_password_hasher.py
+++ b/tests/test_password_hasher.py
@@ -10,7 +10,7 @@ from argon2._utils import Parameters
 from argon2.exceptions import (
     InvalidHash,
     InvalidHashError,
-    UnsupportedParamsError,
+    UnsupportedParametersError,
 )
 
 
@@ -167,7 +167,7 @@ class TestPasswordHasher:
         for machine in ["wasm32", "wasm64"]:
             with mock.patch("platform.machine", return_value=machine):
                 with pytest.raises(
-                    UnsupportedParamsError,
+                    UnsupportedParametersError,
                     match="In WebAssembly environments `parallelism` must be 1.",
                 ):
                     PasswordHasher(parallelism=2)
@@ -175,7 +175,7 @@ class TestPasswordHasher:
                 # last param is parallelism so it should fail
                 params = Parameters(Type.I, 2, 8, 8, 3, 256, 8)
                 with pytest.raises(
-                    UnsupportedParamsError,
+                    UnsupportedParametersError,
                     match="In WebAssembly environments `parallelism` must be 1.",
                 ):
                     ph = PasswordHasher.from_parameters(params)