Pad a string

readme.md

Pad string

Ever wanted to make a block of documentation line up with the prefix on the first line? For example, if you ever had a string like this:

:param test: This is an example parameter, and it's too long to fit in one line, so I want to indent it and make it look nice and pretty.

One way to do so is to indent the line like this:

:param test: This is an example parameter, and it's too long to fit in one
             line, so I want to indent it and make it look nice and pretty. 

This can be annoying to do by hand, so the function pad_string does it automatically.

To convert the string, we need the left component, which is :param test:, and we need what is to the right, which is This is an example parameter, and it's too long to fit in one line, so I want to indent it and make it look nice and pretty.

The code signature would look like this:

left=":param test:"
right="This is an example parameter, and it's too long to fit in one line, so I want to indent it and make it look nice and pretty."
output=pad_string(left, right, space_left=True)

An alternative method is to just add the space to the left component directly, so this code is also going to give the same result:

left=":param test: "
right="This is an example parameter, and it's too long to fit in one line, so I want to indent it and make it look nice and pretty."
output=pad_string(left, right)

You can also add indent to the string, so it's perfect for usage in docstrings.

left=":param test: "
right="This is an example parameter, and it's too long to fit in one line, so I want to indent it and make it look nice and pretty."
output=pad_string(left, right, indent_level=1)

The output here will be:

    :param test: This is an example parameter, and it's too long to fit in one
                 line, so I want to indent it and make it look nice and
                 pretty. 

Finally, you can just indent a block without a prefix, to wrap a long phrase into a docstring without adding any prefix. For example, if we want to indent the previous string without adding :param test:, we could do:

right="This is an example parameter, and it's too long to fit in one line, so I want to indent it and make it look nice and pretty."
output=pad_string("", right, indent_level=1)

The output here will be:

    This is an example parameter, and it's too long to fit in one line, so I
    want to indent it and make it look nice and pretty.

pad.py

def pad_string(left: str, right: str, indent_level: int = 0,
               indent_characters: str = "    ", line_length: int = 79,
               padding_character: str = " ", space_left: bool = False) -> str:
    """Pad a string into multiple lines.

    :param left: The characters to go in the first line at the left.
                 Determines the amount of padding to add to the string.
    :param right: The string to go to the right.
    :param indent_level: The amount of levels of indent to add. (Default: 0)
    :param indent_characters: The characters that represent an indent
                              (Default: 4 spaces)
    :param line_length: The maximum length of a line (Default: 79)
    :param padding_character: The character to use as padding (Default: Space)
    :param space_left: Whether or not the add a space between the characters
                       on the left and the right at the first line (Default:
                       False)
    :returns: The formatted string
    """
    if space_left:
        left += " "
    if indent_level > 0:
        left = indent_characters * indent_level + left
    if len(left) > line_length:
        raise ValueError(
            "The maximum line length has to be greater than the characters in "
            "the left.")
    padding = len(left)
    words = right.split(" ")
    lines = []
    current_string = left
    last_operation_made_newline = False
    op_ran = False
    while words:
        word = words.pop(0)
        new_string = current_string + word + " "
        if len(new_string) <= line_length:
            current_string = new_string
            last_operation_made_newline = False
            op_ran = True
        else:
            if last_operation_made_newline or not op_ran:
                while len(current_string) < line_length:
                    current_string += word[0]
                    word = word[1:]
            current_string = current_string.rstrip(" ")
            lines.append(current_string)
            current_string = padding_character * padding
            words.insert(0, word)
            last_operation_made_newline = True
    if current_string.strip():
        lines.append(current_string)
    return "\n".join(lines)