Checksum API

pathapi.checksum

__all__ = ['md5', 'native', 'sha256', 'stream'] module-attribute

md5(path, chunk_size=65536)

Calculate MD5 checksum of the file at path.

Source code in src/pathapi/checksum.py

def md5(path: "_BinaryOpen", chunk_size: int = 65536) -> str:
    """Calculate MD5 checksum of the file at `path`."""
    return stream(path, "md5", chunk_size)

native(path, algorithm='md5')

Try path's backend-native NativeChecksum.checksum() (see protocols/checksum.py); return None if path doesn't implement the protocol at all, or if it does but can't produce algorithm (raises NotImplementedError -- the protocol's documented contract for "unsupported", never a wrong-algorithm value). Never raises for either of those two cases; any other exception the backend raises propagates.

Source code in src/pathapi/checksum.py

def native(
    path: "_NativeChecksum | _BinaryOpen", algorithm: str = "md5"
) -> "str | None":
    """Try `path`'s backend-native `NativeChecksum.checksum()` (see
    `protocols/checksum.py`); return `None` if `path` doesn't implement the
    protocol at all, or if it does but can't produce `algorithm` (raises
    `NotImplementedError` -- the protocol's documented contract for
    "unsupported", never a wrong-algorithm value). Never raises for either
    of those two cases; any other exception the backend raises propagates.
    """
    if not _supports(path, _NativeChecksum):
        return None
    checksum = getattr(path, "checksum", None)
    if checksum is None:
        return None
    try:
        return checksum(algorithm)
    except NotImplementedError:
        return None

sha256(path, chunk_size=65536)

Calculate SHA-256 checksum of the file at path.

Source code in src/pathapi/checksum.py

def sha256(path: "_BinaryOpen", chunk_size: int = 65536) -> str:
    """Calculate SHA-256 checksum of the file at `path`."""
    return stream(path, "sha256", chunk_size)

stream(path, algorithm='md5', chunk_size=65536)

Streaming checksum for an arbitrary hashlib algorithm name (the generic form of md5/sha256 above, used where the algorithm is a runtime parameter rather than fixed at the call site -- e.g. PathSyncer's streaming fallback, which must match whatever algorithm a native checksum attempt was made under).

The digest compares content; it is not a security use, so it is created with usedforsecurity=False -- on a FIPS-mode host hashlib.md5() otherwise raises ValueError.

Source code in src/pathapi/checksum.py

def stream(path: "_BinaryOpen", algorithm: str = "md5", chunk_size: int = 65536) -> str:
    """Streaming checksum for an arbitrary `hashlib` `algorithm` name (the
    generic form of `md5`/`sha256` above, used where the algorithm is a
    runtime parameter rather than fixed at the call site -- e.g.
    `PathSyncer`'s streaming fallback, which must match whatever algorithm
    a native checksum attempt was made under).

    The digest compares content; it is not a security use, so it is created
    with `usedforsecurity=False` -- on a FIPS-mode host `hashlib.md5()`
    otherwise raises ValueError.
    """
    h = _hashlib.new(algorithm, usedforsecurity=False)
    with path.open("rb") as f:
        while True:
            chunk = f.read(chunk_size)
            if not chunk:
                break
            h.update(chunk)
    return h.hexdigest()