Skip to content

PEP 8 planning

Jump to bottom
Paul McGuire edited this page Aug 21, 2021 · 8 revisions

[The first step in PEP8 naming is taking place with release 3.0.0. PEP8 names have been implemented throughout, with compatibility synonyms defined.]

Migration of Pyparsing's API over to PEP-8 will be a multi-step process, involving synonym definitions of many methods, method arguments, and module-level variables to provide a migration path for existing pyparsing users. These include:

  • no change to existing class names, as they are already PEP-8 compliant; constructor arguments that are camel case will be duplicated with current naming and PEP-8 naming

  • no change to pyparsing_unicode or pyparsing_common; even though these are classes, their intent is to serve as module-like namespaces, so they will retain module naming style

  • conversion of non-PEP-8 methods to classes (while redefining current names as synonyms to the new names):

    • delimitedList -> DelimitedList
    • oneOf -> OneOf
    • dictOf -> DictOf
    • infixNotation -> InfixNotation
    • countedArray -> CountedArray
    • matchPreviousLiteral -> MatchPreviousLiteral
    • matchPreviousExpr -> MatchPreviousExpr
    • originalTextFor -> OriginalTextFor
    • locatedExpr -> Located [done in 3.0.0]
    • nestedExpr -> NestedExpr
    • indentedBlock -> IndentedBlock
    • opAssoc -> OpAssoc
    • commonHTMLentity -> CommonHtmlEntity
    • restOfLine -> RestOfLine
    • commaSeparatedList -> CommaSeparatedList
    • ungroup -> Ungroup

    Method argument names in synonyms will be retained as-is, while argument names in new classes will be PEP-8.

    This conversion will also make grammar definitions more consistent in appearance, as most will use just class names, not a mix of class names and method names.

  • no change to:

    • alphas
    • nums
    • alphanums
    • hexnums
    • printables
    • col
    • lineno
    • line
    • alphas8bit (may be deprecated in favor of pyparsing_unicode.Latin1.alphas)
    • punc8bit (may be deprecated in favor of pyparsing_unicode.Latin1.printables)
    • srange

  • renaming (with retained synonyms) [done in 3.0.0]:

    • quotedString -> quoted_string
    • dblQuotedString -> dbl_quoted_string
    • sglQuotedString -> sgl_quoted_string
    • unicodeString -> unicode_string
    • removeQuotes -> remove_quotes
    • traceParseAction -> trace_parse_action
    • nullDebugAction -> null_debug_action
    • matchOnlyAtCol -> match_only_at_col
    • replaceWith -> replace_with
    • tokenMap -> token_map
    • makeHTMLTags -> make_html_tags
    • makeXMLTags -> make_xml_tags
    • withAttribute -> with_attribute
    • withClass -> with_class
    • replaceHTMLentity -> replace_html_entity
    • cStyleComment -> c_style_comment
    • cppStyleComment -> cpp_style_comment
    • htmlComment -> html_comment
    • dblSlashComment -> dbl_slash_comment
    • javaStyleComment -> java_style_comment
    • pythonStyleComment -> python_style_comment
    • pyparsing_common methods:
      • convertToFloat -> convert_to_float
      • convertToInteger -> convert_to_integer
      • upcaseTokens -> upcase_tokens
      • downcaseTokens -> downcase_tokens

  • deprecate

    • empty, lineStart, lineEnd, stringStart, stringEnd - these module-level names are just predefined instances for classes Empty, LineStart, etc., and can be replaced with in-place instantiation of their respective classes
    • upcaseTokens -> pyparsing_common.upcase_tokens
    • downcaseTokens -> pyparsing_common.downcase_tokens

  • other PEP-8 considerations (may be moot now that we are using Black for automated code formatting):

    • whitespace
      • spaces after opening '('s and before closing ')'s will be deleted
      • commas in argument and name lists will changed from a,b,c to a, b, c
    • blank lines
      • no special effort to add blank lines before classes or methods
    • line length
      • instead of PEP-8's 78-character line limit, pyparsing will use a 120-character limit
Clone this wiki locally