API reference

The everyday API is the lock() / unlock() pair, which encrypt and decrypt a file in place. The lower-level encrypt() / decrypt() functions return the envelope or plaintext bytes without touching the file, and the prompt helpers read a password from the terminal. Everything below is imported directly from the top-level pydlock package.

Locking and unlocking files

pydlock.lock(path, encoding='utf-8', password=None)[source]

Encrypts a file in place, replacing its contents with the v2 envelope.

Parameters:
Return type:

None

pydlock.unlock(path, encoding='utf-8', password=None)[source]

Decrypts a file in place. Returns True if decryption was successful, and False otherwise.

Parameters:
Return type:

bool

Byte-level encryption

pydlock.encrypt(path, encoding='utf-8', password=None)[source]

Encrypts the contents of a file and returns the v2 envelope bytes: the magic prefix, a JSON header carrying the KDF parameters and per-file salt, a newline, and the Fernet token.

The password may be passed as str or bytes (or omitted, to prompt): a str is encoded to bytes with encoding at this public API boundary, since scrypt operates on bytes.

Parameters:
Return type:

bytes

pydlock.decrypt(path, encoding='utf-8', password=None)[source]

Decrypts a pydlock file and returns its plaintext bytes. A v2 file (magic prefix) is read via the envelope header (key re-derived from the stored salt and parameters); a non-magic file is treated as a legacy v1 raw Fernet token and read with the old scheme, so no existing file is stranded (re-locking rewrites it as v2). Fernet verifies the token, so a wrong password or a tampered header/token fails cleanly rather than yielding wrong plaintext.

The password may be passed as str or bytes (or omitted, to prompt): a str is encoded to bytes with encoding at this public API boundary, covering both the v2 scrypt path and the v1 legacy path.

Parameters:
Return type:

bytes | None

Password prompts

pydlock.password_prompt(encoding='utf-8', prompt='Enter password: ')[source]

Prompts the user for a password and returns it encoded as bytes. Key derivation is deferred to encrypt/decrypt, where the per-file salt is available.

Parameters:
Return type:

bytes

pydlock.double_password_prompt(encoding='utf-8')[source]

Prompts and re-prompts the user for a password, returning it encoded as bytes. If the two entries do not match, the user is prompted to retry.

Parameters:

encoding (str)

Return type:

bytes