def get_font(font_path, desired_height):
    """Return font obj whose surfaces are of desired height.

    Otherwise raises a custom exception notifying that the
    height couldn't be obtained for the font.

    The font object is a pygame.font.Font instance.

    This is achieved by trial and error, that is,
    instantiating fonts and using their 'size' method.
    This is so because each font has a different ratio
    between the size argument provided and the actual
    height in pixels of its rendered text surfaces.
    Such ratio even changes within the font itself
    depending on the specific size used.

    Since instantiating pygame.font.Font and using its
    'size' method is very quick, this is fast enough as
    to not be noticeable.

    Furthermore, this is done only once per font and
    desired height, since the resulting font object
    is stored for future reference in the FontsMap
    object that makes use of this funtion.

    Coming up with a font which renders text surfaces
    of the exact desired height is not always possible.

    For instance, you cannot have a pygame.font.Font
    from an "ubuntu medium" font file with surfaces of
    height 36. This is so because such font, when
    instantiated with size 31 renders surfaces of
    height 35 and when instantiated with size 32
    renders surfaces with height 37.

    In such case, as explained above, we raise a custom
    error so the person can choose another height and
    try checking whether it is possible to obtain a
    font which renders surface of that height.

    However, it must be noted that obtaining a font
    for a specific height doesn't mean all rendered
    text surfaces will have that height. It depends
    on the characters being rendered.

    Also note that we don't use pygame.font.Font.get_height()
    because it returns the average of the height of each
    glyph in the font. We, on the other hand, prefer to
    measure the height based on the height of a space
    character.
    """
    ### create a set to keep track of the attempted sizes
    attempted_sizes = set()

    ### create variable to store the chosen font
    chosen_font = None

    ### create variable to store highest height achieved
    ### which doesn't surpass the desired height (but
    ### can be equal)
    highest_achieved = 0

    ### before searching for the perfect font size inside
    ### the "while loop", define an initial size that takes
    ### into account the difference between the value used
    ### for the font size (here we use the desired height)
    ### and the actual height of a produced surface

    raise_if_unattainable(desired_height, desired_height, font_path)

    font = Font(font_path, desired_height)
    _, surf_height = font.size(" ")

    diff = desired_height - surf_height

    size = desired_height + diff

    ### we'll now enter a "while loop" with 02 exit points:
    ###
    ### 1) if while trying different sizes, we come up with
    ###    one we already attempted, it means that we are
    ###    out of viable options, so we have no choice but
    ###    to exit the loop; this condition is the one
    ###    passed to the "while" statement;
    ###
    ### 2) if we find a size which produces the desired
    ###    height; this condition is inside the body of
    ###    the "while loop" (in an "if block" with a
    ###    "break" statement)

    while size not in attempted_sizes:

        ### create font and calculate the height of the
        ### surface of an arbitrary character (space) when
        ### rendered

        raise_if_unattainable(desired_height, size, font_path)

        font = Font(font_path, size)
        _, surf_height = font.size(" ")

        ### store current size as an attempted one since
        ### we just tried it
        attempted_sizes.add(size)

        ### if we reached a font whose rendered surface
        ### satisfies our height requirement, we can break
        ### out of the loop after storing the surf height
        ### as the highest achieved one and the font as the
        ### chosen one

        if surf_height == desired_height:

            highest_achieved = surf_height
            chosen_font = font

            break

        ### otherwise, we come up with another value for
        ### the size by incrementing/decrementing the
        ### current one according to whether the height
        ### of the surface we obtained is lower/higher
        ### than the desired one;

        else:

            size += 1 if surf_height < desired_height else -1

        ### if the height of the text surface is higher
        ### than the ones achieved until now but still
        ### below the desired height, consider it the
        ### highest height achieved until now, and its
        ### font as the chosen one (at least for now)

        if highest_achieved < surf_height < desired_height:

            highest_achieved = surf_height
            chosen_font = font

    ### if the highest height achieved isn't the desired
    ### one, raise an error to notify the user

    if highest_achieved != desired_height:

        raise UnattainableFontHeight(font_path, desired_height)

    ### finally return the chosen font
    return chosen_font
Return font obj whose surfaces are of desired height.

    Otherwise raises a custom exception notifying that the
    height couldn't be obtained for the font.

    The font object is a pygame.font.Font instance.

    This is achieved by trial and error, that is,
    instantiating fonts and using their 'size' method.
    This is so because each font has a different ratio
    between the size argument provided and the actual
    height in pixels of its rendered text surfaces.
    Such ratio even changes within the font itself
    depending on the specific size used.

    Since instantiating pygame.font.Font and using its
    'size' method is very quick, this is fast enough as
    to not be noticeable.

    Furthermore, this is done only once per font and
    desired height, since the resulting font object
    is stored for future reference in the FontsMap
    object that makes use of this funtion.

    Coming up with a font which renders text surfaces
    of the exact desired height is not always possible.

    For instance, you cannot have a pygame.font.Font
    from an "ubuntu medium" font file with surfaces of
    height 36. This is so because such font, when
    instantiated with size 31 renders surfaces of
    height 35 and when instantiated with size 32
    renders surfaces with height 37.

    In such case, as explained above, we raise a custom
    error so the person can choose another height and
    try checking whether it is possible to obtain a
    font which renders surface of that height.

    However, it must be noted that obtaining a font
    for a specific height doesn't mean all rendered
    text surfaces will have that height. It depends
    on the characters being rendered.

    Also note that we don't use pygame.font.Font.get_height()
    because it returns the average of the height of each
    glyph in the font. We, on the other hand, prefer to
    measure the height based on the height of a space
    character.
    
nodezator/fontsman/cache.py