Using the Pwned Passwords API directly#
If the validator and middleware do not meet your needs, you can also directly check a password against Pwned Passwords. The following two functions handle this use case, depending on whether you are writing synchronous or asynchronous Python:
- pwned_passwords_django.api.check_password(password: str) int #
Check a password against the Pwned Passwords API and return the count of times it appears in breaches in the Pwned Passwords database.
- Parameters:
password – The password to check.
- Raises:
TypeError – When the given password value is not a string.
exceptions.PwnedPasswordsError – When the Pwned Passwords API times out, returns an HTTP 4XX or 5XX status code, or when any other error occurs in contacting the Pwned Passwords API or checking the password.
- async pwned_passwords_django.api.check_password_async(password: str) int #
Check a password against the Pwned Passwords API and return the count of times it appears in breaches in the Pwned Passwords database.
This is an asynchronous version of
check_password()
, and will use an asynchronous HTTP client to make the request to Pwned Passwords.- Raises:
TypeError – When the given password value is not a string.
exceptions.PwnedPasswordsError – When the Pwned Passwords API times out, returns an HTTP 4XX or 5XX status code, or when any other error occurs in contacting the Pwned Passwords API or checking the password.
Using the API client class#
If you want even finer-grained control over interaction with Pwned Passwords,
there is also an API client class – which is what check_password()
and
check_password_async()
and all other public API of
pwned-passwords-django
passes through to – provided:
- class pwned_passwords_django.api.PwnedPasswords(client: Client | None = None, async_client: AsyncClient | None = None)[source]#
A client for interacting with the Pwned Passwords API.
There are two useful public methods here:
check_password()
andcheck_password_async()
, which are identical to and called by thecheck_password()
andcheck_password_async()
functions exposed at the module level.Constructor arguments are all optional; use them only if you want to pass in your own custom sync or async HTTP clients (which must be API-compatible with the corresponding sync and async client objects in the HTTPX library). Otherwise, default client objects from
httpx
will be used.- Parameters:
client – A synchronous HTTP client object. Defaults to an
httpx.Client
.async_client – An asynchronous HTTP client object. Defaults to an
httpx.AsyncClient
.
You also can subclass and override the following attributes:
- api_endpoint#
A
str
indicating the API endpoint to request when talking to Pwned Passwords. Defaults to the Pwned Passwords v3 API endpoint:"https://api.pwnedpasswords.com/range/"
.
- user_agent#
A
str
containing the value to send in the HTTPUser-Agent
header. Defaults to a string listing the versions ofpwned-passwords-django
, Python, andhttpx
.
Also, in a subclass you can override the constructor to control how the following values are set:
- add_padding#
A
bool
indicating whether or not to include the optionalAdd-Padding
header to the request, causing Pwned Passwords to add random padding to the size of the response body, as an additional security measure. The default value is the value ofsettings.PWNED_PASSWORDS["ADD_PADDING"]
, orTrue
if that setting is not provided. See the settings documentation.
- request_timeout#
A
float
setting a timeout, in seconds, for communicating with Pwned Passwords. The default value is the value ofsettings.PWNED_PASSWORDS["API_TIMEOUT"]
, or1.0
(1 second) if that setting is not provided. See the settings documentation.