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() and check_password_async(), which are identical to and called by the check_password() and check_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 HTTP User-Agent header. Defaults to a string listing the versions of pwned-passwords-django, Python, and httpx.

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 optional Add-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 of settings.PWNED_PASSWORDS["ADD_PADDING"], or True 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 of settings.PWNED_PASSWORDS["API_TIMEOUT"], or 1.0 (1 second) if that setting is not provided. See the settings documentation.