cs-hashutils

Convenience hashing facilities.

Latest release 20250414.1: Update the module docstring.

This predefines classes for various hash algorithms: BLAKE3 (if we can import blake3), MD5, SHA1, SHA224, SHA256, SHA384, SHA512, and a BaseHashCode base class as a common ancestor with a .hashclass() factory method for creating new subclasses for other algorithms.

All BaseHashCode classes have a variety of convenience factories for making instances:

• from_hashbytes: from an existing digest bytes
• from_hashbytes_hex: from a hex string of an existing digest
• from_named_hashbytes_hex: from a hashname (eg 'blake3') and a hex string
• from_named_hashbytes_hex: from a hashname:hex string
• from_data: from bytes content
• from_buffer: from a CornuCopyBuffer or anything which can be promoted to one
• from_fspath: from a filesystem path

Hashing some content returns instances of these classes, which are subclasses of bytes i.e. the digest. All BaseHashCode classes various methods:

• str(hashcode): returns a hashname:hex string
• .hashname: the hash function name
• .hex(): the digest as a hex string

The common example:

# obtain the contwnt hash from the file `fspath`
hashcode = hashclass.from_fspath(fspath)

where hashclass is whatever BaseHashCode subclass is in use.

Module contents:

• Class BaseHashCode(builtins.bytes): Base class for hashcodes, subclassed by SHA1, SHA256` et al.

  You can obtain the class for a particular hasher by name, example:

  SHA256 = BaseHashCode.hashclass('sha256')
  

BaseHashCode.__str__(self): Return f'{self.hashname}:{self.hex()}'.

BaseHashCode.from_buffer(bfr: cs.buffer.CornuCopyBuffer): Compute hashcode from the contents of the CornuCopyBuffer bfr.

BaseHashCode.from_data(bs): Compute hashcode from the data bs.

BaseHashCode.from_fspath(fspath, **kw): Compute hashcode from the contents of the file fspath.

BaseHashCode.from_hashbytes(hashbytes): Factory function returning a BaseHashCode object from the hash bytes.

BaseHashCode.from_hashbytes_hex(hashhex: str): Factory function returning a BaseHashCode object from the hash bytes hex text.

BaseHashCode.from_named_hashbytes_hex(hashname, hashhex): Factory function to return a BaseHashCode object from the hash type name and the hash bytes hex text.

BaseHashCode.from_prefixed_hashbytes_hex(hashtext: str): Factory function returning a BaseHashCode object from the hash bytes hex text prefixed by the hashname. This is the reverse of __str__.

BaseHashCode.get_hashfunc(hashname: str): Fetch the hash function implied by hashname.

BaseHashCode.hashclass(hashname: str, hashfunc=None, **kw): Return the class for the hash function named hashname.

Parameters:

• hashname: the name of the hash function
• hashfunc: optional hash function for the class

BaseHashCode.hashname: The hash code type name, derived from the class name.

BaseHashCode.hex(self) -> str: Return the hashcode bytes transcribes as a hexadecimal ASCII str.

BaseHashCode.promote(obj): Promote to a BaseHashCode instance.

• Class BLAKE3(BaseHashCode)`: Hash class for the 'blake3' algorithm.

BLAKE3.hashfunc

• Class MD5(BaseHashCode)`: Hash class for the 'md5' algorithm.

MD5.hashfunc

• Class SHA1(BaseHashCode)`: Hash class for the 'sha1' algorithm.

SHA1.hashfunc

• Class SHA224(BaseHashCode)`: Hash class for the 'sha224' algorithm.

SHA224.hashfunc

• Class SHA256(BaseHashCode)`: Hash class for the 'sha256' algorithm.

SHA256.hashfunc

• Class SHA384(BaseHashCode)`: Hash class for the 'sha384' algorithm.

SHA384.hashfunc

• Class SHA512(BaseHashCode)`: Hash class for the 'sha512' algorithm.

SHA512.hashfunc

Release Log

Release 20250414.1: Update the module docstring.

Release 20250414: Define BLAKE3 if we can import blake3.

Release 20241207: BaseHashCode.hashclass: raise ValueError from unknown hash function name with greater detail on the underlying failure.

Release 20240412:

• BaseHashCode.hashclass(hashname): fall back to looking for blake3 from the blake3 module.
• BaseHashCode: new get_hashfunc(hashname) static method.

Release 20240316: Fixed release upload artifacts.

Release 20240211: Initial PyPI release: BaseHashCode(bytes) and subclasses for various hash algorithms.