pwdlib

https://frankie567.github.io/pwdlib/
Admin
pwdlib is a modern password hashing and verification library for Python supporting secure algorithms...
Tokens:4,459
Snippets:52
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install both Argon2 and Bcrypt dependencies

Source: https://frankie567.github.io/pwdlib/guide

Install both Argon2 and Bcrypt extras for pwdlib.

```bash
pip install 'pwdlib[argon2,bcrypt]'
```

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

### Install Bcrypt dependency

Source: https://frankie567.github.io/pwdlib/guide

Install the Bcrypt extra for pwdlib.

```bash
pip install 'pwdlib[bcrypt]'
```

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

### Install pwdlib with Argon2 support

Source: https://frankie567.github.io/pwdlib

Install the pwdlib package with the argon2 extra using pip.

```bash
pip install 'pwdlib[argon2]'

```

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

### Install Argon2 dependency

Source: https://frankie567.github.io/pwdlib/guide

Install the Argon2 extra for pwdlib.

```bash
pip install 'pwdlib[argon2]'
```

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

### HasherNotAvailable.__init__(hasher)

Source: https://frankie567.github.io/pwdlib/reference/pwdlib.exceptions

Error raised when an unavailable hash algorithm was installed. Constructor accepts the name of the unavailable hasher.

```APIDOC
## HasherNotAvailable.__init__(hasher)

### Description
Error raised when an unavailable hash algorithm was installed. Constructor accepts the name of the unavailable hasher.

### Method
Constructor

### Signature
`__init__(hasher)`

### Parameters
- **hasher** (str) - Required - The unavailable hash algorithm.

```

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

### Example Argon2 hash string

Source: https://frankie567.github.io/pwdlib/guide

An example of an Argon2 hash string containing parameters and salt.

```text
$argon2id$v=19$m=65536,t=3,p=4$ugY9gvgMUycvF7hrnoi8oQ$uqcZOh96YysaG+s3A+RcZIccgaiQsynxfBlqUNxeRT4
```

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

### Serve MkDocs documentation with hatch

Source: https://frankie567.github.io/pwdlib

Serve the MkDocs documentation locally, automatically watching for changes in your code.

```bash
hatch run docs-serve

```

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

### Initialize and use recommended hashers

Source: https://frankie567.github.io/pwdlib/reference/pwdlib

Creates a PasswordHash instance with recommended hashers (Argon2) and demonstrates hashing and verification.

```python
>>> password_hash = PasswordHash.recommended()
>>> hash = password_hash.hash("herminetincture")
>>> password_hash.verify(hash, "herminetincture")
True
```

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

### Initialize PasswordHash with recommended settings

Source: https://frankie567.github.io/pwdlib/guide

Use the recommended class method to instantiate PasswordHash with Argon2 as the default algorithm.

```python
password_hash = PasswordHash.recommended()
```

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

### Hash and verify a password with pwdlib

Source: https://frankie567.github.io/pwdlib

Use PasswordHash.recommended() to create a password hash and verify it. The verify call returns True for the correct password.

```python
from pwdlib import PasswordHash

password_hash = PasswordHash.recommended()
hash = password_hash.hash("herminetincture")
password_hash.verify("herminetincture", hash)  # True

```

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

### Run unit tests with just

Source: https://frankie567.github.io/pwdlib

Execute all unit tests using the just command runner.

```bash
just test

```

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

### Initialize PasswordHash with Argon2 and Bcrypt

Source: https://frankie567.github.io/pwdlib/guide

Create a PasswordHash instance by passing a tuple of hashing algorithm objects. The first algorithm in the tuple is used for new hashes.

```python
from pwdlib import PasswordHash, exceptions
from pwdlib.hashers.argon2 import Argon2Hasher
from pwdlib.hashers.bcrypt import BcryptHasher

password_hash = PasswordHash((
    Argon2Hasher(),
    BcryptHasher(),
))
```

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

### PwdlibError.__init__(message)

Source: https://frankie567.github.io/pwdlib/reference/pwdlib.exceptions

Base pwdlib error. Constructor accepts an error message string.

```APIDOC
## PwdlibError.__init__(message)

### Description
Base pwdlib error. Constructor accepts an error message string.

### Method
Constructor

### Signature
`__init__(message)`

### Parameters
- **message** (str) - Required - The error message.

```

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

### BcryptHasher.__init__

Source: https://frankie567.github.io/pwdlib/reference/pwdlib.hashers

Initializes a BcryptHasher with the number of hashing rounds and a prefix version. This constructor is used to create a password hasher based on the bcrypt algorithm.

```APIDOC
## BcryptHasher.__init__

### Description
Initializes a BcryptHasher with configurable rounds and prefix.

### Parameters

#### Parameter Parameters
- **rounds** (`int`) - Optional - The number of rounds to use for hashing. Default: `12`.
- **prefix** (`Literal['2a', '2b']`) - Optional - The prefix to use for hashing. Default: `'2b'`.
```

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

### Format code and check typing with hatch

Source: https://frankie567.github.io/pwdlib

Apply linting and check typing using the hatch run lint command.

```bash
hatch run lint

```

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

### Argon2Hasher.__init__

Source: https://frankie567.github.io/pwdlib/reference/pwdlib.hashers

Initializes an Argon2Hasher instance with configurable cost parameters, memory usage, parallelism, hash length, salt length, and Argon2 type. This constructor is used to create a password hasher based on the Argon2 algorithm.

```APIDOC
## Argon2Hasher.__init__

### Description
Initializes an Argon2Hasher with configurable cost parameters, memory usage, parallelism, hash length, salt length, and hash type.

### Parameters

#### Constructor Parameters
- **time_cost** (`int`) - Optional - Defines the amount of computation realized and therefore the execution time, given in number of iterations. Default: `argon2.DEFAULT_TIME_COST`.
- **memory_cost** (`int`) - Optional - Defines the memory usage, given in kibibytes. Default: `argon2.DEFAULT_MEMORY_COST`.
- **parallelism** (`int`) - Optional - Defines the number of parallel threads (_changes_ the resulting hash value). Default: `argon2.DEFAULT_PARALLELISM`.
- **hash_len** (`int`) - Optional - Length of the hash in bytes. Default: `argon2.DEFAULT_HASH_LENGTH`.
- **salt_len** (`int`) - Optional - Length of random salt to be generated for each password. Default: `argon2.DEFAULT_RANDOM_SALT_LENGTH`.
- **type** (`Type`) - Optional - Argon2 type to use. Only change for interoperability with legacy systems. Default: `argon2.Type.ID`.
```

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

### Verify an invalid password

Source: https://frankie567.github.io/pwdlib/reference/pwdlib

Demonstrates that verifying an incorrect password returns False.

```python
>>> password_hash.verify("INVALID_PASSWORD", hash)
False
```

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

### Bump version to patch with hatch

Source: https://frankie567.github.io/pwdlib

Bump the version to a patch release, creating a commit and tag. Your default Git text editor will open for release notes.

```bash
hatch version patch

```

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

### Bump version to minor with hatch

Source: https://frankie567.github.io/pwdlib

Bump the version to a minor release, creating a commit and tag. Your default Git text editor will open for release notes.

```bash
hatch version minor

```

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

### UnknownHashError.__init__(hash)

Source: https://frankie567.github.io/pwdlib/reference/pwdlib.exceptions

Error raised when the hash can't be identified from the list of provided hashers. Constructor accepts the hash that failed to identify.

```APIDOC
## UnknownHashError.__init__(hash)

### Description
Error raised when the hash can't be identified from the list of provided hashers. Constructor accepts the hash that failed to identify.

### Method
Constructor

### Signature
`__init__(hash)`

### Parameters
- **hash** (str | bytes) - Required - The hash we failed to identify.

```

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

### Bump version to major with hatch

Source: https://frankie567.github.io/pwdlib

Bump the version to a major release, creating a commit and tag. Your default Git text editor will open for release notes.

```bash
hatch version major

```

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

### PasswordHash Class Reference

Source: https://frankie567.github.io/pwdlib/reference/pwdlib

Documentation for the PasswordHash class methods, including constructor, hashing, verification, and update operations.

```APIDOC
## PasswordHash.__init__(hashers)

### Description
Initializes a PasswordHash instance with a sequence of hashers to be used for password hashing.

### Method
Constructor

### Parameters
- `hashers` (Sequence[HasherProtocol]) - Required - A sequence of hashers to be used for password hashing.

### Raises
- `AssertionError` - If no hashers are specified.
```

```APIDOC
## PasswordHash.hash(password, *, salt=None)

### Description
Hashes a password using the current hasher.

### Method
Function

### Parameters
- `password` (str | bytes) - Required - The password to be hashed.
- `salt` (bytes | None) - Optional - The salt to be used for hashing. Defaults to None.

### Returns
- `str` - The hashed password.

### Example
```python
>>> hash = password_hash.hash("herminetincture")
```
```

```APIDOC
## PasswordHash.recommended()

### Description
Returns a PasswordHash instance with recommended hashers. Currently, the hasher is Argon2 with default parameters.

### Method
Classmethod

### Returns
- `PasswordHash` - A PasswordHash instance with recommended hashers.

### Example
```python
>>> password_hash = PasswordHash.recommended()
>>> hash = password_hash.hash("herminetincture")
>>> password_hash.verify(hash, "herminetincture")
True
```
```

```APIDOC
## PasswordHash.verify(password, hash)

### Description
Verifies if a password matches a given hash.

### Method
Function

### Parameters
- `password` (str | bytes) - Required - The password to be checked.
- `hash` (str | bytes) - Required - The hash to be verified.

### Returns
- `bool` - True if the password matches the hash, False otherwise.

### Raises
- `UnknownHashError` - If the hash is not recognized by any of the hashers.

### Examples
```python
>>> password_hash.verify("herminetincture", hash)
True
```
```python
>>> password_hash.verify("INVALID_PASSWORD", hash)
False
```
```

```APIDOC
## PasswordHash.verify_and_update(password, hash)

### Description
Verifies if a password matches a given hash and updates the hash if necessary.

### Method
Function

### Parameters
- `password` (str | bytes) - Required - The password to be checked.
- `hash` (str | bytes) - Required - The hash to be verified.

### Returns
- `tuple[bool, str | None]` - A tuple containing a boolean indicating if the password matches the hash, and an updated hash if the current hasher or the hash itself needs to be updated.

### Raises
- `UnknownHashError` - If the hash is not recognized by any of the hashers.

### Example
```python
>>> valid, updated_hash = password_hash.verify_and_update("herminetincture", hash)
```
```

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

### Hash a password

Source: https://frankie567.github.io/pwdlib/guide

Generate a hash from a password using the current algorithm.

```python
hash = password_hash.hash("herminetincture")
```

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

### Verify a password with PasswordHash.verify

Source: https://frankie567.github.io/pwdlib/reference/pwdlib

Checks if a password matches a given hash, returning True if valid.

```python
>>> password_hash.verify("herminetincture", hash)
True
```

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

### Verify and update a password hash

Source: https://frankie567.github.io/pwdlib/reference/pwdlib

Verifies a password and returns a tuple containing the validity and an optional updated hash.

```python
>>> valid, updated_hash = password_hash.verify_and_update("herminetincture", hash)
```

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

### Hash a password with PasswordHash.hash

Source: https://frankie567.github.io/pwdlib/reference/pwdlib

Hashes a password using the current hasher instance.

```python
>>> hash = password_hash.hash("herminetincture")
```
Tokens:
Raw