Easy Hash

`py_simple.easy_hash`

easy_hash creates checksums for text, bytes, and files without the hashlib boilerplate.

`EasyHashError`

Bases: Exception

Raised when a checksum cannot be created.

Parameters:

Name	Type	Description	Default
`message`	`str`	Description of what went wrong.	required

`compare_file_hashes(filepath1, filepath2, algorithm='sha256')`

Checks whether two files produce the same checksum using chunked reads.

Parameters:

Name	Type	Description	Default
`filepath1`	`str \| Path`	Path to the first file.	required
`filepath2`	`str \| Path`	Path to the second file.	required
`algorithm`	`str`	One of `"sha256"`, `"sha1"`, or `"md5"`. Defaults to `"sha256"`.	`'sha256'`

Returns:

Name	Type	Description
`bool`	`bool`	True when both files have matching checksums, False otherwise.

Raises:

Type	Description
`EasyHashError`	If either file cannot be read or the algorithm is not supported.
`TypeError`	If either path is not a string or path-like object.

Example

The Py_simple WayThe Traditional Way

from py_simple import compare_file_hashes

identical = compare_file_hashes("file1.txt", "file2.txt")
print(identical)

import hashlib

def get_checksum(filepath):
    hasher = hashlib.sha256()
    with open(filepath, "rb") as f:
        while chunk := f.read(64 * 1024):
            hasher.update(chunk)
    return hasher.hexdigest()

identical = get_checksum("file1.txt") == get_checksum("file2.txt")
print(identical)

`hash_bytes(data, algorithm='sha256')`

Create a checksum for bytes that are already in memory.

Parameters:

Name	Type	Description	Default
`data`	`bytes`	The binary data to hash.	required
`algorithm`	`str`	One of `"sha256"`, `"sha1"`, or `"md5"`. Defaults to `"sha256"`.	`'sha256'`

Returns:

Name	Type	Description
`str`	`str`	The checksum as lowercase hex.

Raises:

Type	Description
`EasyHashError`	If `data` is not bytes or the algorithm is not supported.

Example

The Py_simple WayThe Traditional Way

from py_simple import hash_bytes

digest = hash_bytes(b"hello")
print(digest)

import hashlib

digest = hashlib.sha256(b"hello").hexdigest()
print(digest)

`hash_file(filepath, algorithm='sha256')`

Create a checksum for the contents of a file.

Parameters:

Name	Type	Description	Default
`filepath`	`str`	Path to the file.	required
`algorithm`	`str`	One of `"sha256"`, `"sha1"`, or `"md5"`. Defaults to `"sha256"`.	`'sha256'`

Returns:

Name	Type	Description
`str`	`str`	The checksum as lowercase hex.

Raises:

Type	Description
`EasyHashError`	If the file cannot be read or the algorithm is not supported.

Example

The Py_simple WayThe Traditional Way

from py_simple import hash_file

digest = hash_file("notes.txt")

import hashlib

hasher = hashlib.sha256()
with open("notes.txt", "rb") as f:
    hasher.update(f.read())
digest = hasher.hexdigest()

`hash_text(text, algorithm='sha256')`

Create a checksum for a piece of text.

Parameters:

Name	Type	Description	Default
`text`	`str`	The text to hash.	required
`algorithm`	`str`	One of `"sha256"`, `"sha1"`, or `"md5"`. Defaults to `"sha256"`.	`'sha256'`

Returns:

Name	Type	Description
`str`	`str`	The checksum as lowercase hex.

Raises:

Type	Description
`EasyHashError`	If `text` is not a string or the algorithm is not supported.

Example

The Py_simple WayThe Traditional Way

from py_simple import hash_text

digest = hash_text("hello")

import hashlib

digest = hashlib.sha256("hello".encode("utf-8")).hexdigest()

`hashes_match(text, expected, algorithm='sha256')`

Check whether text matches an expected checksum.

Parameters:

Name	Type	Description	Default
`text`	`str`	The text to check.	required
`expected`	`str`	The checksum you expected, in hex.	required
`algorithm`	`str`	Algorithm used to build `expected`. Defaults to `"sha256"`.	`'sha256'`

Returns:

Name	Type	Description
`bool`	`bool`	True when the checksum of `text` equals `expected`.

Example

The Py_simple WayThe Traditional Way

from py_simple import hashes_match

expected = "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
hashes_match("hello", expected)

import hashlib

digest = hashlib.sha256("hello".encode("utf-8")).hexdigest()
matches = digest == "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"

`verify_file_hash(filepath, expected, algorithm='sha256')`

Checks whether a file matches an expected checksum using chunked reads.

Parameters:

Name	Type	Description	Default
`filepath`	`str \| Path`	Path to the file to check.	required
`expected`	`str`	Expected hex checksum, ignoring letter case. Whitespace is not stripped.	required
`algorithm`	`str`	One of `"sha256"`, `"sha1"`, or `"md5"`. Defaults to `"sha256"`.	`'sha256'`

Returns:

Name	Type	Description
`bool`	`bool`	True when the file's checksum equals `expected`. A mismatch, malformed checksum, or non-string `expected` returns False. Non-string checksums are rejected before reading the file or checking the algorithm, as with `hashes_match()`.

Raises:

Type	Description
`EasyHashError`	If the file cannot be read or the algorithm is not supported.
`TypeError`	If `filepath` is not a string or path-like object.

Example

The Py_simple WayThe Traditional Way

from pathlib import Path
from py_simple import verify_file_hash

Path("notes.txt").write_bytes(b"hello")
expected = "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
matches = verify_file_hash("notes.txt", expected)
print(matches)  # True

import hashlib
from pathlib import Path

Path("notes.txt").write_bytes(b"hello")
expected = "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
hasher = hashlib.sha256()
with open("notes.txt", "rb") as file:
    while chunk := file.read(64 * 1024):
        hasher.update(chunk)
matches = hasher.hexdigest() == expected.lower()
print(matches)  # True