Function get_purl_hash

aboutcode/hashid/__init__.py:343–410

Return a short lower cased hash string from a ``purl`` string or object. The PURL is normalized and we drop its version, qualifiers and subpath. This function takes a normalized PURL string and a ``_bit_count`` argument defaulting to 0 bits which represents 2**0 = 1 possible hash v

(purl: Union[PackageURL, str], _bit_count: int = 0)

def get_purl_hash(purl: Union[PackageURL, str], _bit_count: int = 0) -> str:
    """
    Return a short lower cased hash string from a ``purl`` string or object. The PURL is normalized
    and we drop its version, qualifiers and subpath.

    This function takes a normalized PURL string and a ``_bit_count`` argument defaulting to 0 bits
    which represents 2**0 = 1 possible hash value. It returns a fixed length short hash string
    that is left-padded with zeros.

    The hash length is derived from the bit_count and the number of bits-per-byte stored in an hex
    encoding of this bits count. For 10 bits, this means up to 3 characters.

    The function is carefully designed to be portable across tech stacks and easy to implement in
    many programming languages:

    - the hash is computed using sha256 which is available is all common language,
    - the hash is using simple lowercased HEX encoding,
    - we use simple arithmetics on integer with modulo.

    The processing goes through these steps:

    First, a SHA256 hash computed on the PURL bytes encoded as UTF-8.

    Then, the hash digest bytes are converted to an integer, which is reduced modulo the largest
    possible value for the bit_count.

    Finally, this number is converted to hex, left-padded with zero up to the hash_length, and
    returned as a lowercase string.

    For example::

    The hash does not change with version or qualifiers::
    >>> get_purl_hash("pkg:pypi/univers@30.12.0", 7)
    '09'
    >>> get_purl_hash("pkg:pypi/univers@10.12.0", 7)
    '09'
    >>> get_purl_hash("pkg:pypi/univers@30.12.0?foo=bar#sub/path", 7)
    '09'

    The hash is left padded with zero if it::
    >>> get_purl_hash("pkg:pypi/expressionss", 7)
    '57'

    We normalize the PURL. Here pypi normalization always uses dash for underscore ::

    >>> get_purl_hash("pkg:pypi/license_expression", 7)
    '50'
    >>> get_purl_hash("pkg:pypi/license-expression", 7)
    '50'

    Originally from:
    https://github.com/nexB/purldb/pull/235/files#diff-a1fd023bd42d73f56019d540f38be711255403547add15108540d70f9948dd40R154
    """

    core_purl = get_core_purl(purl).to_string()
    # compute the hash from a UTF-8 encoded string
    purl_bytes = core_purl.encode("utf-8")
    hash_bytes = sha256(purl_bytes).digest()