print_schema: handle descriptions that are non-printable as block strings

Replicates graphql/graphql-js@be12613

Author: Cito

docs/modules/utilities.rst

@@ -48,7 +48,6 @@ Print a GraphQLSchema to GraphQL Schema language:
 .. autofunction:: print_introspection_schema
 .. autofunction:: print_schema
 .. autofunction:: print_type
-.. autofunction:: print_value
 
 Create a GraphQLType from a GraphQL language AST:
 

src/graphql/language/block_string.py

@@ -1,80 +1,105 @@
+from typing import Collection, List
+from sys import maxsize
+
 __all__ = [
-    "dedent_block_string_value",
+    "dedent_block_string_lines",
+    "is_printable_as_block_string",
     "print_block_string",
-    "get_block_string_indentation",
 ]
 
 
-def dedent_block_string_value(raw_string: str) -> str:
+def dedent_block_string_lines(lines: Collection[str]) -> List[str]:
     """Produce the value of a block string from its parsed raw value.
 
-    Similar to CoffeeScript's block string, Python's docstring trim or Ruby's
-    strip_heredoc.
+    This function works similar to CoffeeScript's block string,
+    Python's docstring trim or Ruby's strip_heredoc.
 
-    This implements the GraphQL spec's BlockStringValue() static algorithm.
+    It implements the GraphQL spec's BlockStringValue() static algorithm.
 
     Note that this is very similar to Python's inspect.cleandoc() function.
-    The differences is that the latter also expands tabs to spaces and
+    The difference is that the latter also expands tabs to spaces and
     removes whitespace at the beginning of the first line. Python also has
     textwrap.dedent() which uses a completely different algorithm.
 
     For internal use only.
     """
-    # Expand a block string's raw value into independent lines.
-    lines = raw_string.splitlines()
+    common_indent = maxsize
+    first_non_empty_line = None
+    last_non_empty_line = -1
+
+    for i, line in enumerate(lines):
+        indent = leading_white_space(line)
+
+        if indent == len(line):
+            continue  # skip empty lines
 
-    # Remove common indentation from all lines but first.
-    common_indent = get_block_string_indentation(raw_string)
+        if first_non_empty_line is None:
+            first_non_empty_line = i
+        last_non_empty_line = i
 
-    if common_indent:
-        lines[1:] = [line[common_indent:] for line in lines[1:]]
+        if i and indent < common_indent:
+            common_indent = indent
 
-    # Remove leading and trailing blank lines.
-    start_line = 0
-    end_line = len(lines)
-    while start_line < end_line and is_blank(lines[start_line]):
-        start_line += 1
-    while end_line > start_line and is_blank(lines[end_line - 1]):
-        end_line -= 1
+    if first_non_empty_line is None:
+        first_non_empty_line = 0
 
-    # Return a string of the lines joined with U+000A.
-    return "\n".join(lines[start_line:end_line])
+    return [  # Remove common indentation from all lines but first.
+        line[common_indent:] if i else line for i, line in enumerate(lines)
+    ][  # Remove leading and trailing blank lines.
+        first_non_empty_line : last_non_empty_line + 1
+    ]
 
 
-def is_blank(s: str) -> bool:
-    """Check whether string contains only space or tab characters."""
-    return all(c == " " or c == "\t" for c in s)
+def leading_white_space(s: str) -> int:
+    i = 0
+    for c in s:
+        if c not in " \t":
+            return i
+        i += 1
+    return i
 
 
-def get_block_string_indentation(value: str) -> int:
-    """Get the amount of indentation for the given block string.
+def is_printable_as_block_string(value: str) -> bool:
+    """Check whether the given string is printable as a block string.
 
     For internal use only.
     """
-    is_first_line = is_empty_line = True
-    indent = 0
-    common_indent = None
+    if not isinstance(value, str):
+        value = str(value)  # resolve lazy string proxy object
+
+    if not value:
+        return True  # emtpy string is printable
+
+    is_empty_line = True
+    has_indent = False
+    has_common_indent = True
+    seen_non_empty_line = False
 
     for c in value:
-        if c in "\r\n":
-            is_first_line = False
+        if c == "\n":
+            if is_empty_line and not seen_non_empty_line:
+                return False  # has leading new line
+            seen_non_empty_line = True
             is_empty_line = True
-            indent = 0
-        elif c in "\t ":
-            indent += 1
+            has_indent = False
+        elif c in " \t":
+            has_indent = has_indent or is_empty_line
+        elif c <= "\x0f":
+            return False
         else:
-            if (
-                is_empty_line
-                and not is_first_line
-                and (common_indent is None or indent < common_indent)
-            ):
-                common_indent = indent
+            has_common_indent = has_common_indent and has_indent
             is_empty_line = False
 
-    return common_indent or 0
+    if is_empty_line:
+        return False  # has trailing empty lines
 
+    if has_common_indent and seen_non_empty_line:
+        return False  # has internal indent
 
-def print_block_string(value: str, prefer_multiple_lines: bool = False) -> str:
+    return True
+
+
+def print_block_string(value: str, minimize: bool = False) -> str:
     """Print a block string in the indented block form.
 
     Prints a block string in the indented block form by adding a leading and
@@ -86,24 +111,45 @@ def print_block_string(value: str, prefer_multiple_lines: bool = False) -> str:
     if not isinstance(value, str):
         value = str(value)  # resolve lazy string proxy object
 
-    is_single_line = "\n" not in value
-    has_leading_space = value.startswith(" ") or value.startswith("\t")
-    has_trailing_quote = value.endswith('"')
+    escaped_value = value.replace('"""', '\\"""')
+
+    # Expand a block string's raw value into independent lines.
+    lines = escaped_value.splitlines() or [""]
+    num_lines = len(lines)
+    is_single_line = num_lines == 1
+
+    # If common indentation is found,
+    # we can fix some of those cases by adding a leading new line.
+    force_leading_new_line = num_lines > 1 and all(
+        not line or line[0] in " \t" for line in lines[1:]
+    )
+
+    # Trailing triple quotes just looks confusing but doesn't force trailing new line.
+    has_trailing_triple_quotes = escaped_value.endswith('\\"""')
+
+    # Trailing quote (single or double) or slash forces trailing new line
+    has_trailing_quote = value.endswith('"') and not has_trailing_triple_quotes
     has_trailing_slash = value.endswith("\\")
-    print_as_multiple_lines = (
+    force_trailing_new_line = has_trailing_quote or has_trailing_slash
+
+    print_as_multiple_lines = not minimize and (
+        # add leading and trailing new lines only if it improves readability
         not is_single_line
-        or has_trailing_quote
-        or has_trailing_slash
-        or prefer_multiple_lines
+        or len(value) > 70
+        or force_trailing_new_line
+        or force_leading_new_line
+        or has_trailing_triple_quotes
     )
 
     # Format a multi-line block quote to account for leading space.
+    skip_leading_new_line = is_single_line and value and value[0] in " \t"
     before = (
         "\n"
-        if print_as_multiple_lines and not (is_single_line and has_leading_space)
+        if print_as_multiple_lines
+        and not skip_leading_new_line
+        or force_leading_new_line
         else ""
     )
-    after = "\n" if print_as_multiple_lines else ""
-    value = value.replace('"""', '\\"""')
+    after = "\n" if print_as_multiple_lines or force_trailing_new_line else ""
 
-    return f'"""{before}{value}{after}"""'
+    return f'"""{before}{escaped_value}{after}"""'

src/graphql/language/lexer.py

@@ -2,7 +2,7 @@
 
 from ..error import GraphQLSyntaxError
 from .ast import Token
-from .block_string import dedent_block_string_value
+from .block_string import dedent_block_string_lines
 from .character_classes import is_digit, is_name_start, is_name_continue
 from .source import Source
 from .token_kind import TokenKind
@@ -380,40 +380,49 @@ def read_block_string(self, start: int) -> Token:
         """Read a block string token from the source file."""
         body = self.source.body
         body_length = len(body)
-        start_line = self.line
-        start_column = 1 + start - self.line_start
+        line_start = self.line_start
 
         position = start + 3
         chunk_start = position
-        raw_value = []
+        current_line = ""
 
+        block_lines = []
         while position < body_length:
             char = body[position]
 
             if char == '"' and body[position + 1 : position + 3] == '""':
-                raw_value.append(body[chunk_start:position])
-                return Token(
+                current_line += body[chunk_start:position]
+                block_lines.append(current_line)
+
+                token = self.create_token(
                     TokenKind.BLOCK_STRING,
                     start,
                     position + 3,
-                    start_line,
-                    start_column,
-                    dedent_block_string_value("".join(raw_value)),
+                    # return a string of the lines joined with new lines
+                    "\n".join(dedent_block_string_lines(block_lines)),
                 )
 
+                self.line += len(block_lines) - 1
+                self.line_start = line_start
+                return token
+
             if char == "\\" and body[position + 1 : position + 4] == '"""':
-                raw_value.extend((body[chunk_start:position], '"""'))
+                current_line += body[chunk_start:position]
+                chunk_start = position + 1  # skip only slash
                 position += 4
-                chunk_start = position
                 continue
 
             if char in "\r\n":
+                current_line += body[chunk_start:position]
+                block_lines.append(current_line)
+
                 if char == "\r" and body[position + 1 : position + 2] == "\n":
                     position += 2
                 else:
                     position += 1
-                self.line += 1
-                self.line_start = position
+
+                current_line = ""
+                chunk_start = line_start = position
                 continue
 
             if is_unicode_scalar_value(char):

src/graphql/language/print_string.py

@@ -2,11 +2,13 @@
 
 
 def print_string(s: str) -> str:
-    """ "Print a string as a GraphQL StringValue literal.
+    """Print a string as a GraphQL StringValue literal.
 
     Replaces control characters and excluded characters (" U+0022 and \\ U+005C)
     with escape sequences.
     """
+    if not isinstance(s, str):
+        s = str(s)
     return f'"{s.translate(escape_sequences)}"'
 
 

src/graphql/utilities/__init__.py

@@ -33,7 +33,7 @@
     print_introspection_schema,
     print_schema,
     print_type,
-    print_value,
+    print_value,  # deprecated
 )
 
 # Create a GraphQLType from a GraphQL language AST.

src/graphql/utilities/print_schema.py

@@ -1,7 +1,7 @@
 from typing import Any, Callable, Dict, List, Optional, Union, cast
 
 from ..language import print_ast, StringValueNode
-from ..language.block_string import print_block_string
+from ..language.block_string import is_printable_as_block_string
 from ..pyutils import inspect
 from ..type import (
     DEFAULT_DEPRECATION_REASON,
@@ -282,8 +282,11 @@ def print_description(
     if description is None:
         return ""
 
-    prefer_multiple_lines = len(description) > 70
-    block_string = print_block_string(description, prefer_multiple_lines)
+    block_string = print_ast(
+        StringValueNode(
+            value=description, block=is_printable_as_block_string(description)
+        )
+    )
 
     prefix = "\n" + indentation if indentation and not first_in_block else indentation
 

src/graphql/utilities/strip_ignored_characters.py

@@ -2,12 +2,11 @@
 
 from ..language import Lexer, TokenKind
 from ..language.source import Source, is_source
-from ..language.block_string import (
-    dedent_block_string_value,
-    get_block_string_indentation,
-)
+from ..language.block_string import print_block_string
 from ..language.lexer import is_punctuator_token_kind
 
+__all__ = ["strip_ignored_characters"]
+
 
 def strip_ignored_characters(source: Union[str, Source]) -> str:
     """Strip characters that are ignored anyway.
@@ -86,25 +85,12 @@ def strip_ignored_characters(source: Union[str, Source]) -> str:
 
         token_body = body[current_token.start : current_token.end]
         if token_kind == TokenKind.BLOCK_STRING:
-            stripped_body += dedent_block_string(token_body)
+            stripped_body += print_block_string(
+                current_token.value or "", minimize=True
+            )
         else:
             stripped_body += token_body
 
         was_last_added_token_non_punctuator = is_non_punctuator
 
     return stripped_body
-
-
-def dedent_block_string(block_str: str) -> str:
-    """Skip leading and trailing triple quotations"""
-    raw_str = block_str[3:-3]
-    body = dedent_block_string_value(raw_str)
-
-    if get_block_string_indentation(body) > 0:
-        body = "\n" + body
-
-    has_trailing_quote = body.endswith('"') and not body.endswith('\\"""')
-    if has_trailing_quote or body.endswith("\\"):
-        body += "\n"
-
-    return '"""' + body + '"""'