### Install pwnedpasswords

Source: https://github.com/lionheart/pwnedpasswords/blob/master/README.rst

Install the library using pip.

```bash
pip install pwnedpasswords
```

--------------------------------

### Use the Command Line Interface

Source: https://context7.com/lionheart/pwnedpasswords/llms.txt

Provides examples for checking passwords via terminal, including stdin support, verbose logging, and help documentation.

```bash
# Check a password directly
$ pwnedpasswords mypassword
250616

# Check using stdin (password won't appear in shell history)
$ pwnedpasswords --stdin
mypassword
250616

# Run with verbose output to see API calls
$ pwnedpasswords 123456password --verbose
INFO:pwnedpasswords.pwnedpasswords:https://api.pwnedpasswords.com/range/5052C
INFO:pwnedpasswords.pwnedpasswords:Entry found
2452

# Alternative invocation via Python module
$ python -m pwnedpasswords secretpassword
10472

# Force plain text interpretation for hash-like input
$ pwnedpasswords --plain-text abcd1234abcd1234abcd1234abcd1234abcd1234
0

# Display help
$ pwnedpasswords -h
usage: pwnedpasswords [-h] [--verbose] [--plain-text] (--stdin | password)

Checks Pwned Passwords API to see if provided plaintext data was found in a
data breach.

positional arguments:
  password      The password or hashed password to search for.

optional arguments:
  -h, --help    show this help message and exit
  --verbose     Display verbose output.
  --plain-text  Specify that the provided input is plain text, even if it
                looks like a SHA-1 hash.
  --stdin       Read provided input from stdin.
```

--------------------------------

### Installation

Source: https://context7.com/lionheart/pwnedpasswords/llms.txt

Install the pwnedpasswords library using pip.

```APIDOC
## Installation

Install pwnedpasswords from PyPI using pip.

```bash
pip install pwnedpasswords
```
```

--------------------------------

### Python Library Usage

Source: https://github.com/lionheart/pwnedpasswords/blob/master/README.md

Examples of how to use the pwnedpasswords Python library for checking passwords.

```APIDOC
## Python Library Usage

### Installation
```bash
pip install pwnedpasswords
```

### Basic Usage (k-anonymous)
```python
import pwnedpasswords

# Check a password using the k-anonymous method (default)
result = pwnedpasswords.check("testing 123")
print(result) # Output: 1 (number of times pwned)

# Example with a known pwned password
result_pwned = pwnedpasswords.check("mypassword")
print(result_pwned) # Example Output: 250616
```

### Direct Search (non-anonymous)
```python
import pwnedpasswords

# Force the use of the direct search endpoint (less secure)
result_direct = pwnedpasswords.check("password", anonymous=False)
print(result_direct) # Example Output: 46628605
```

### Hashing Handling

`pwnedpasswords` automatically detects if the input looks like a SHA-1 hash. If it appears to be plain text, it will hash it before sending.

```python
import pwnedpasswords

# Input is already a SHA-1 hash
result_hashed = pwnedpasswords.check("b8dfb080bc33fb564249e34252bf143d88fc018f")
print(result_hashed)

# Input is plain text, but looks like a hash. Force hashing.
result_force_hash = pwnedpasswords.check("1231231231231231231231231231231231231231", plain_text=True)
print(result_force_hash)
```

### Using the `range` endpoint directly
```python
import pwnedpasswords

# Get frequency counts for a given hash prefix
range_results = pwnedpasswords.range("098765")
print(range_results)
# Example Output: {'08F5F': 10, '1A2B3': 5}
```
```

--------------------------------

### Display CLI help

Source: https://github.com/lionheart/pwnedpasswords/blob/master/README.md

View available command-line arguments and usage instructions.

```bash
$ pwnedpasswords -h
usage: pwnedpasswords [-h] [--verbose] [--plain-text] (--stdin | password)

Checks Pwned Passwords API to see if provided plaintext data was found in a
data breach.

positional arguments:
  password      The password or hashed password to search for.

optional arguments:
  -h, --help    show this help message and exit
  --verbose     Display verbose output.
  --plain-text  Specify that the provided input is plain text, even if it
                looks like a SHA-1 hash.
  --stdin       Read provided input from stdin.
```

--------------------------------

### Display CLI help information

Source: https://github.com/lionheart/pwnedpasswords/blob/master/README.rst

Use the -h flag to view available command-line arguments and usage instructions.

```bash
$ pwnedpasswords -h
```

--------------------------------

### Use command line utility

Source: https://github.com/lionheart/pwnedpasswords/blob/master/README.rst

Check passwords directly from the terminal.

```bash
$ pwnedpasswords 123456password
2452
$ python -m pwnedpasswords 123456password
2452
```

--------------------------------

### Handle API Exceptions in Python

Source: https://context7.com/lionheart/pwnedpasswords/llms.txt

Demonstrates granular error handling for API-specific conditions like rate limiting or missing User-Agent headers.

```python
import pwnedpasswords
from pwnedpasswords import PasswordNotFound, BadRequest, RateLimitExceeded, NoUserAgent

def check_password_safely(password):
    """Check password with comprehensive error handling."""
    try:
        count = pwnedpasswords.check(password, anonymous=False)
        if count > 0:
            return f"WARNING: Password found {count} times in breaches!"
        return "Password not found in any known breaches"
    except PasswordNotFound:
        return "Password not found in any known breaches"
    except BadRequest as e:
        return f"Invalid request: {e}"
    except RateLimitExceeded:
        return "Rate limit exceeded - please wait and try again"
    except NoUserAgent:
        return "API requires User-Agent header (library handles this)"
    except Exception as e:
        return f"Unexpected error: {e}"

# Example usage
result = check_password_safely("mypassword")
print(result)
# Output: WARNING: Password found 250616 times in breaches!

result = check_password_safely("xK9#mP2$vL8@nQ5!")
print(result)
# Output: Password not found in any known breaches
```

--------------------------------

### Integrate Password Validation

Source: https://context7.com/lionheart/pwnedpasswords/llms.txt

Shows how to incorporate breach checking into application logic, such as user registration, with configurable breach thresholds.

```python
import pwnedpasswords

def validate_password(password, min_length=8, max_breaches=0):
    """
    Validate password strength and check against known breaches.

    Args:
        password: The password to validate
        min_length: Minimum required password length
        max_breaches: Maximum acceptable breach count (0 = must not be breached)

    Returns:
        Tuple of (is_valid, error_message)
    """
    # Basic length check
    if len(password) < min_length:
        return False, f"Password must be at least {min_length} characters"

    # Check against Pwned Passwords database
    try:
        breach_count = pwnedpasswords.check(password)
        if breach_count > max_breaches:
            return False, f"Password has been exposed in {breach_count} data breaches. Please choose a different password."
        return True, None
    except Exception as e:
        # Log error but don't block registration if API is unavailable
        print(f"Warning: Could not verify password against breach database: {e}")
        return True, None

# Usage in registration flow
password = "Password123"
is_valid, error = validate_password(password)
if not is_valid:
    print(f"Error: {error}")
    # Output: Error: Password has been exposed in 42681 data breaches. Please choose a different password.
else:
    print("Password accepted")

# Check with more lenient threshold
password = "uncommonpassword"
is_valid, error = validate_password(password, max_breaches=10)
print("Valid" if is_valid else error)
```

--------------------------------

### Check password with verbose output

Source: https://github.com/lionheart/pwnedpasswords/blob/master/README.md

Enable the --verbose flag to see API request details and internal processing logs.

```bash
$ pwnedpasswords 123456password --verbose
INFO:pwnedpasswords.pwnedpasswords:https://api.pwnedpasswords.com/range/5052C
INFO:pwnedpasswords.pwnedpasswords:Entry found
240
```

--------------------------------

### Check password with verbose output

Source: https://github.com/lionheart/pwnedpasswords/blob/master/README.rst

Use the --verbose flag to display detailed information about the API request and search results.

```bash
$ pwnedpasswords 123456password --verbose
```

--------------------------------

### Check password with default settings

Source: https://github.com/lionheart/pwnedpasswords/blob/master/README.rst

The check method uses the k-anonymous range endpoint by default.

```python
pwnedpasswords.check("mypassword")
# 250616
```

--------------------------------

### Use stdin for command line input

Source: https://github.com/lionheart/pwnedpasswords/blob/master/README.rst

Provide input via stdin to avoid leaving passwords in shell history.

```bash
$ pwnedpasswords --stdin
mypassword
```

--------------------------------

### Force hashing for SHA-1-like passwords

Source: https://github.com/lionheart/pwnedpasswords/blob/master/README.rst

Use the plain_text parameter to force hashing when a password happens to match the SHA-1 format.

```python
pwnedpasswords.check("1231231231231231231231231231231231231231", plain_text=True)
```

--------------------------------

### Check pre-hashed password

Source: https://github.com/lionheart/pwnedpasswords/blob/master/README.rst

Provide an already-hashed SHA-1 password to the check method.

```python
pwnedpasswords.check("b8dfb080bc33fb564249e34252bf143d88fc018f")
```

--------------------------------

### Use Password Object-Oriented Interface

Source: https://context7.com/lionheart/pwnedpasswords/llms.txt

The Password class provides a stateful interface for checking passwords, supporting configurable verbosity and multiple check methods.

```python
import pwnedpasswords
import logging

# Create a Password object from plaintext
password = pwnedpasswords.Password("testing123")

# Check using k-anonymous method (default)
count = password.check()
print(f"Breach count: {count}")

# Check using direct search (non-anonymous)
count = password.check(anonymous=False)
print(f"Breach count (direct): {count}")

# Get range results for custom processing
range_results = password.range()
print(f"Total hashes in range: {len(range_results)}")

# Create Password with SHA-1 hash input (auto-detected)
password_from_hash = pwnedpasswords.Password("5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8")
count = password_from_hash.check()
print(f"Count for 'password': {count}")

# Force plain text mode for hash-like strings
password_forced = pwnedpasswords.Password(
    "abcd1234abcd1234abcd1234abcd1234abcd1234",
    plain_text=True
)

# Enable verbose logging
password_verbose = pwnedpasswords.Password(
    "mypassword",
    verbosity=logging.DEBUG
)
count = password_verbose.check()
# Logs: INFO:pwnedpasswords.pwnedpasswords:https://api.pwnedpasswords.com/range/DC724
# Logs: INFO:pwnedpasswords.pwnedpasswords:Entry found
```

--------------------------------

### POST /range

Source: https://github.com/lionheart/pwnedpasswords/blob/master/README.md

Checks a password against the Pwned Passwords API using k-anonymity. The first 5 characters of the SHA-1 hash are sent to the API.

```APIDOC
## POST /range

### Description
Checks if a password has been pwned using the Pwned Passwords v2 API with k-anonymity. Only the first 5 characters of the SHA-1 hash are sent to the API, ensuring plaintext passwords never leave the user's machine.

### Method
POST

### Endpoint
https://api.pwnedpasswords.com/range/

### Parameters
#### Query Parameters
- **hash_prefix** (string) - Required - The first 5 characters of the SHA-1 hash of the password.

### Request Body
This endpoint does not typically use a request body in the traditional sense. The hash prefix is usually passed as a query parameter or handled internally by the library.

### Response
#### Success Response (200)
- **response_body** (object) - A dictionary mapping SHA-1 hash suffixes to their frequency counts.
  - **hash_suffix** (string) - The remaining characters of the SHA-1 hash.
  - **count** (integer) - The number of times this hash suffix has appeared.

#### Response Example
```json
{
  "08F5F": 10,
  "1A2B3": 5
}
```
```

--------------------------------

### range() - Query K-Anonymous Range Endpoint

Source: https://context7.com/lionheart/pwnedpasswords/llms.txt

Returns a dictionary mapping SHA-1 hash suffixes to their breach counts for a given 5-character hash prefix. Useful for batch checking or custom implementations.

```APIDOC
## range() - Query K-Anonymous Range Endpoint

Returns a dictionary mapping SHA-1 hash suffixes to their breach counts for a given 5-character hash prefix. Useful for batch checking or custom implementations.

```python
import pwnedpasswords
import hashlib

# Get all entries matching a hash prefix
entries = pwnedpasswords.range("password")
print(f"Retrieved {len(entries)} hash suffixes")
# Output: Retrieved ~500 hash suffixes

# The entries dictionary maps hash suffixes (without first 5 chars) to counts
# Example key: "1E4C9B93F3F0682250B6CF8331B7EE68FD8" -> 3861493
password_hash = hashlib.sha1("password".encode()).hexdigest().upper()
suffix = password_hash[5:]
if suffix in entries:
    print(f"Password breach count: {entries[suffix]}")
# Output: Password breach count: 3861493

# Query with a specific 5-character prefix directly
entries = pwnedpasswords.range("5BAA6")  # First 5 chars of "password" SHA-1
print(f"Entries for prefix 5BAA6: {len(entries)}")
```
```

--------------------------------

### Check password via stdin

Source: https://github.com/lionheart/pwnedpasswords/blob/master/README.md

Use the --stdin flag to provide input without saving the password in the shell history.

```bash
$ pwnedpasswords --stdin
mypassword
250616
```

--------------------------------

### Query range endpoint directly

Source: https://github.com/lionheart/pwnedpasswords/blob/master/README.rst

Access the range endpoint directly to retrieve a dictionary of hash suffixes and counts.

```python
pwnedpasswords.range("098765")
# outputs a dictionary mapping SHA-1 hash suffixes to frequency counts
```

--------------------------------

### POST /pwnedpassword

Source: https://github.com/lionheart/pwnedpasswords/blob/master/README.md

Checks a password against the Pwned Passwords API directly. This method is faster but less secure as it sends the full SHA-1 hash.

```APIDOC
## POST /pwnedpassword

### Description
Checks if a password has been pwned by sending its full SHA-1 hash directly to the Pwned Passwords API. This method offers faster response times but does not provide k-anonymity, meaning the plaintext password's hash is exposed.

### Method
POST

### Endpoint
https://api.pwnedpasswords.com/pwnedpassword/

### Parameters
#### Request Body
- **hash** (string) - Required - The full SHA-1 hash of the password.

### Request Example
```json
{
  "hash": "b8dfb080bc33fb564249e34252bf143d88fc018f"
}
```

### Response
#### Success Response (200)
- **count** (integer) - The number of times the password hash has been found in data breaches.

#### Response Example
```json
46628605
```
```

--------------------------------

### Query K-Anonymous Range Endpoint

Source: https://context7.com/lionheart/pwnedpasswords/llms.txt

The range() function retrieves breach counts for a 5-character hash prefix. This is useful for batch processing or custom implementations.

```python
import pwnedpasswords
import hashlib

# Get all entries matching a hash prefix
entries = pwnedpasswords.range("password")
print(f"Retrieved {len(entries)} hash suffixes")
# Output: Retrieved ~500 hash suffixes

# The entries dictionary maps hash suffixes (without first 5 chars) to counts
# Example key: "1E4C9B93F3F0682250B6CF8331B7EE68FD8" -> 3861493
password_hash = hashlib.sha1("password".encode()).hexdigest().upper()
suffix = password_hash[5:]
if suffix in entries:
    print(f"Password breach count: {entries[suffix]}")
# Output: Password breach count: 3861493

# Query with a specific 5-character prefix directly
entries = pwnedpasswords.range("5BAA6")  # First 5 chars of "password" SHA-1
print(f"Entries for prefix 5BAA6: {len(entries)}")
```

--------------------------------

### Check password without anonymity

Source: https://github.com/lionheart/pwnedpasswords/blob/master/README.rst

Set anonymous to False to use the faster search endpoint, noting that this sends more data over the network.

```python
pwnedpasswords.check("password", anonymous=False)
# 46628605
```

--------------------------------

### Password Class - Object-Oriented Interface

Source: https://context7.com/lionheart/pwnedpasswords/llms.txt

The Password class provides an object-oriented interface for password checking with configurable verbosity and multiple check methods.

```APIDOC
## Password Class - Object-Oriented Interface

The Password class provides an object-oriented interface for password checking with configurable verbosity and multiple check methods.

```python
import pwnedpasswords
import logging

# Create a Password object from plaintext
password = pwnedpasswords.Password("testing123")

# Check using k-anonymous method (default)
count = password.check()
print(f"Breach count: {count}")

# Check using direct search (non-anonymous)
count = password.check(anonymous=False)
print(f"Breach count (direct): {count}")

# Get range results for custom processing
range_results = password.range()
print(f"Total hashes in range: {len(range_results)}")

# Create Password with SHA-1 hash input (auto-detected)
password_from_hash = pwnedpasswords.Password("5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8")
count = password_from_hash.check()
print(f"Count for 'password': {count}")

# Force plain text mode for hash-like strings
password_forced = pwnedpasswords.Password(
    "abcd1234abcd1234abcd1234abcd1234abcd1234",
    plain_text=True
)

# Enable verbose logging
password_verbose = pwnedpasswords.Password(
    "mypassword",
    verbosity=logging.DEBUG
)
count = password_verbose.check()
# Logs: INFO:pwnedpasswords.pwnedpasswords:https://api.pwnedpasswords.com/range/DC724
# Logs: INFO:pwnedpasswords.pwnedpasswords:Entry found
```
```

--------------------------------

### Check password exposure

Source: https://github.com/lionheart/pwnedpasswords/blob/master/README.rst

Check if a password has been pwned. The library automatically hashes plaintext passwords.

```python
import pwnedpasswords

pwnedpasswords.check("testing 123")
# Returns 1
```

--------------------------------

### Check password exposure

Source: https://github.com/lionheart/pwnedpasswords/blob/master/README.md

Check if a password has been pwned. The library automatically detects if the input is a SHA-1 hash or plaintext.

```python
import pwnedpasswords

pwnedpasswords.check("testing 123")
# Returns 1
```

```python
pwnedpasswords.check("b8dfb080bc33fb564249e34252bf143d88fc018f")
```

```python
pwnedpasswords.check("1231231231231231231231231231231231231231", plain_text=True)
```

```python
pwnedpasswords.check("mypassword")
# 250616
```

```python
pwnedpasswords.check("password", anonymous=False)
# 46628605
```

--------------------------------

### Check Password Against Breach Database

Source: https://context7.com/lionheart/pwnedpasswords/llms.txt

The check() function verifies if a password has been compromised. It supports k-anonymous mode by default, custom timeouts, and non-anonymous direct hash lookups.

```python
import pwnedpasswords

# Check a plaintext password (k-anonymous, secure)
count = pwnedpasswords.check("mypassword")
print(f"Password found {count} times in breaches")
# Output: Password found 250616 times in breaches

# Check a common weak password
count = pwnedpasswords.check("123456")
print(f"Password found {count} times")
# Output: Password found 42542807 times

# Check using non-anonymous mode (faster but sends full hash)
count = pwnedpasswords.check("password", anonymous=False)
print(f"Password found {count} times")
# Output: Password found 46628605 times

# Check with custom timeout (in seconds)
count = pwnedpasswords.check("securepassword123", timeout=10)
print(f"Found: {count}")

# Force plain text interpretation for hash-like strings
count = pwnedpasswords.check("1231231231231231231231231231231231231231", plain_text=True)
print(f"Hash-like password found {count} times")
```

--------------------------------

### check() - Check Password Against Breach Database

Source: https://context7.com/lionheart/pwnedpasswords/llms.txt

The primary function for checking if a password has been compromised. By default, uses the k-anonymous range endpoint to protect plaintext passwords. Returns the count of times the password has appeared in breaches, or 0 if not found.

```APIDOC
## check() - Check Password Against Breach Database

The primary function for checking if a password has been compromised. By default, uses the k-anonymous range endpoint to protect plaintext passwords. Returns the count of times the password has appeared in breaches, or 0 if not found.

```python
import pwnedpasswords

# Check a plaintext password (k-anonymous, secure)
count = pwnedpasswords.check("mypassword")
print(f"Password found {count} times in breaches")
# Output: Password found 250616 times in breaches

# Check a common weak password
count = pwnedpasswords.check("123456")
print(f"Password found {count} times")
# Output: Password found 42542807 times

# Check using non-anonymous mode (faster but sends full hash)
count = pwnedpasswords.check("password", anonymous=False)
print(f"Password found {count} times")
# Output: Password found 46628605 times

# Check with custom timeout (in seconds)
count = pwnedpasswords.check("securepassword123", timeout=10)
print(f"Found: {count}")

# Force plain text interpretation for hash-like strings
count = pwnedpasswords.check("1231231231231231231231231231231231231231", plain_text=True)
print(f"Hash-like password found {count} times")
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.