Feature align dict colon

[lizawang]

Hello all yapf founders!

I have some new features I want to share with the yapf community. This is also a response to issue #194 and issue #346.

The alignment features added are referred to the yapf function _AlignTrailingComments(final_lines).

The knobs

The main functions for all the knobs are added in reformatter.py.

knob: ALIGN_DICT_COLON

This is an option to align colons inside dictionary.

• The condition : it is only effective if all key-value pairs inside the dictionary are placed on separate lines, e.g. when 'EACH_DICT_ENTRY_ON_SEPARATE_LINE' is set True.
• New block of key-value pairs starts with new alignment. There are 3 cases featured as an indication for new alignment block:
  • Each nested dictionary is a new block:

    fields = [
        {
            "field"    : "ediid",
            "type"     : "text",
            "required" : True,
            "html"     :
                {
                    "attr"   : 'style="width: 250px;" maxlength="30"',
                    "page"   : 0,
                    "span"   : 8,
                    "column" : 0,
                },
        }
    ]
    

  • A comment line inside a dictionary of same level creates a new block:

    fields =  
        {
            "field" : "ediid",
            "type"  : "text",
            # key: value
            "required" : True,
        }
    

  • An object(a list/a dictionary/a set/a argument list) with its items in newlines in between creates a new block inside the dictionary of the same level:

    fields = {
        "field"      : "ediid",
        "long_value" :
            get_dataframe_from_excel_sheet(
                filepath, usecols = [ 0 ], header = None, dtype = str ),
        "type"     : "text",
        "required" : True,
    }
    

knob: NEW_ALIGNMENT_AFTER_COMMENTLINE

This option is made under the consideration that some programmers may prefer to remain the alignment with comment lines inside.

• If it is set False, a comment line in between won't create a new alignment block. Entries before and after the comment line/lines will align with their colons.

Preparations

To make the alignment functions possible, some other changes are made to other files.

• format_token.py: necessary boolean functions are added, is_dict_key, is_dict_key_start, is_dict_value.

Finally

In the end, the knobs are added into the style.py and tests for each one are also updated in yapftests folder.

• style.py: all the 2 knobs are set to be False by default.
• Unitests are added into reformatter_basic_test.py.

[JackLilhammers]

Bump!

[gsmethells]

+1

[Spitfire1900]

@lizawang this PR is blocked by merge conflicts.

[Spitfire1900]

I don't see anything standing out besides resolving merge conflicts. @bwendling. @EeyoreLee , @char101 any thoughts ?

[EeyoreLee]

@Spitfire1900 - Thanks for your invitation. I think this feature should be considered cause the feature-request has 42 upvotes. A code review is essential before merging, e.g., the function _AlignDictColon has too many lines, a space missing between # and TODO. In addition, the name of second knob should be considered a more readable one as I can't understand the function of this knob clearly enough through the name or explanation unless I walk through the whole PR overview.

[Spitfire1900]

Thanks for reviewing @bwendling 👍