Add error D303 when an f-string is used as a docstring

Author: lordmauve

docs/release_notes.rst

@@ -15,6 +15,8 @@ Major Updates
 New Features
 
 * Add flag to disable `# noqa` comment processing in API (#485).
+* New error code D303 is emitted when an f-string is found in place of a
+  docstring.
 
 Bug Fixes
 

src/pydocstyle/checker.py

@@ -46,6 +46,24 @@ def decorator(f):
     return decorator
 
 
+
+FSTRING_RE = re(r'^[rR]?[fF]')
+
+
+def is_fstring(docstring):
+    r"""Return True if docstring is an f-string.
+
+    >>> is_fstring('rf"abc"')
+    True
+    >>> is_fstring('F"abc"')
+    True
+    >>> is_fstring("u'''abc'''")
+    False
+    """
+    return FSTRING_RE.match(str(docstring))
+
+
+
 class ConventionChecker:
     """Checker for PEP 257, NumPy and Google conventions.
 
@@ -180,6 +198,17 @@ def checks(self):
         ]
         return sorted(all, key=lambda this_check: not this_check._terminal)
 
+    @check_for(Definition, terminal=True)
+    def check_docstring_fstring(self, definition, docstring):
+        """D303: Docstrings may not be f-strings.
+
+        f-strings are not treated as string literals, but they look similar
+        and users may attempt to use them as docstrings. This is an
+        outright mistake so we issue a specific error code.
+        """
+        if is_fstring(docstring):
+            return violations.D303()
+
     @check_for(Definition, terminal=True)
     def check_docstring_missing(self, definition, docstring):
         """D10{0,1,2,3}: Public definitions should have docstrings.
@@ -194,6 +223,9 @@ def check_docstring_missing(self, definition, docstring):
               with a single underscore.
 
         """
+        if is_fstring(docstring):
+            return  # checked above in check_docstring_fstring
+
         if (
             not docstring
             and definition.is_public

src/pydocstyle/violations.py

@@ -312,6 +312,7 @@ def to_rst(cls) -> str:
     'D302',
     'Deprecated: Use u""" for Unicode docstrings',
 )
+D303 = D3xx.create_error('D303', 'f-strings are not valid as docstrings')
 
 D4xx = ErrorRegistry.create_group('D4', 'Docstring Content Issues')
 D400 = D4xx.create_error(

src/tests/test_cases/fstrings.py

@@ -0,0 +1,11 @@
+"""Test for warning about f-strings as docstrings."""
+
+from .expected import Expectation
+
+expectation = Expectation()
+expect = expectation.expect
+
+
+@expect("D303: f-strings are not valid as docstrings")
+def fstring():
+    f"""Toggle the gizmo."""

src/tests/test_definitions.py

@@ -1,5 +1,6 @@
 """Old parser tests."""
 
+import sys
 import os
 import re
 import pytest
@@ -24,7 +25,21 @@
     'canonical_numpy_examples',
     'canonical_pep257_examples',
 ])
-def test_complex_file(test_case):
+def test_all_interpreters(test_case):
+    """Complex test cases that run under all interpreters."""
+    run_case(test_case)
+
+
+@pytest.mark.skipif(
+    sys.version_info < (3, 6),
+    reason="f-string support needed"
+)
+def test_fstrings():
+    """Run the f-string test case under Python 3.6+ only."""
+    run_case('fstrings')
+
+
+def run_case(test_case):
     """Run domain-specific tests from test.py file."""
     case_module = __import__(f'test_cases.{test_case}',
                              globals=globals(),