Building Custom Paragraphs Is Painful

[jrg94]

Here's the current chunk of code I'm trying to write:

def _generate_program_list(language: LanguageCollection) -> MDList:
    """
    A helper function which generates a list of programs for the README.
    :param language: a language collection
    :return: a list of sample programs list items
    """
    list_items = list()
    for program in language.sample_programs:
        program_line = Paragraph([])
        readable_name = program.normalized_name.replace("-", " ").title()
        program_name = f"{readable_name} in {language.get_readable_name()}"
        program_link = InlineText(program_name, url=program.sample_program_doc_url)
        if not program_link.verify_url():
            program_line.add(":warning: ")
            program_link = InlineText(program_name, url=program.sample_program_issue_url)
        else:
            program_line.add(":white_check_mark: ")
        program_line.add(program_link)
        program_line.add(" [Requirements]")
        program_line.insert_link("Requirements", program.sample_program_req_url)
        list_items.append(program_line)
    return MDList(list_items)

All of this to just generate a couple of sentences. The main trouble I'm running into pertains to #19. But even beyond that, it's really hard to tell what this code is even supposed to do. Part of me thinks that the pattern should be to avoid InlineText at all costs. I feel like this would be a lot more readable if the user was able to construct their text first. That way, we could leverage various paragraph functions to modify the text after the fact. One idea I currently have is having a parameter which allows the user to test if their link is valid as they insert it. Right now, insert_link returns a Paragraph, so you can chain the calls. Maybe we need a function that checks all links in a paragraph...

[jrg94]

Here's what I'd love this code to look like:

def _generate_program_list(language: LanguageCollection) -> MDList:
    """
    A helper function which generates a list of programs for the README.
    :param language: a language collection
    :return: a list of sample programs list items
    """
    list_items = list()
    for program in language.sample_programs:
        program_line = Paragraph([f":white_check_mark:  {readable_name} in {language.get_readable_name()} [Requirements]"]) \
            .insert_link(f"{readable_name} in {language.get_readable_name()}", program.sample_program_doc_url) \
            .insert_link("Requirements", program.sample_program_req_url)
        if program_line.verify_urls()[program.sample_program_doc_url]: # -> dict[str: bool]
            program_line.replace(":white_check_mark:", ":warning:")
            program_line.insert_link(f"{readable_name} in {language.get_readable_name()}", program.sample_program_issue_url)
        list_items.append(program_line)
    return MDList(list_items)

To me, this seems infinitely cleaner. For one, I know roughly what the output string is going to look like before we even do anything. I can also quickly tell which portions of the paragraph will have links. Then, we can bulk retrieve URL states and check the string accordingly.

[jrg94]

I added the replace and verify URLs methods to paragraph. Going to merge them in now and call it a night!