import math


def return_hpos_to_display(hpo_names, max_num_sites_to_display):
    """
    Function is intended to return a means for divide the number of HPOs into an
    appropriate number of lists based on the maximum number of sites a user
    wants to display.
    
    This is useful for creating graphs that will only display a fraction of the
    total HPOs.
    
    Parameters
    ----------
    hpo_names (list): list of all the health provider organizations (in string form)
    
    num_sites_to_display (int): user-specified number of sites to display in each graph
    
    
    Returns
    -------
    all_hpos (list): contains several lists, each of which contains a number of sites
        (or one fewer) defined by the user. the combination of all the lists should
        have all of the original HPOs given by the hpo_names parameter
    """
    length = len(hpo_names)

    num_lists = math.ceil(length / max_num_sites_to_display)

    base = math.floor(length / num_lists)

    remainder = length - (base * num_lists)

    all_hpos = []

    starting_idx = 0
    ending_idx = starting_idx + base  # add one because it is not inclusive

    for list_num in range(num_lists):

        # this is useful for when the number of sites to display
        # does not go evenly into the number of HPOs - essentially
        # add it to the 'earlier' lists
        if list_num < remainder:
            ending_idx = ending_idx + 1

        sites = hpo_names[starting_idx:ending_idx]

        # reset for subsequent lists
        starting_idx = ending_idx
        ending_idx = starting_idx + base

        all_hpos.append(sites)

    return all_hpos