format-docstring 0.4.0__tar.gz → 0.4.2__tar.gz

{format_docstring-0.4.0 → format_docstring-0.4.2}/AGENTS.md

@@ -46,6 +46,13 @@ oriented before making changes.
   mirroring tuple element splits when the docstring already enumerates them.
 - `Raises` section entries are treated like signature lines in the NumPy
   wrapper so exception names stay untouched while descriptions wrap.
+- Every prose wrapper goes through
+  `line_wrap_utils.wrap_keeping_inline_literals`, which masks every whitespace
+  character inside rST inline literals (``` ``...`` ```) with a private-use
+  placeholder so each literal wraps as one unbreakable word; breaking inside
+  one would drop significant spaces. `_find_google_signature_colon` likewise
+  skips colons inside inline literals so a literal at the start of a prose line
+  is not mistaken for a signature.
 - Wrapping honors NumPy section heuristics, rST constructs, code fences,
   `Examples` prompts, and literal blocks introduced by `::`.
 - `_normalize_signature_segment` flattens multiline annotations via

{format_docstring-0.4.0 → format_docstring-0.4.2}/CHANGELOG.md

@@ -6,6 +6,38 @@ The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.2] - 2026-10-04
+
+- Fixed
+  - Line wrapping no longer breaks inside rST inline literals
+    (``` ``...`` ```). Breaking there dropped the whitespace at the break, so a
+    literal such as ``` ``'  '`` ``` lost its spaces. Each inline literal now
+    wraps as one unbreakable word, overflowing like other long words when it is
+    longer than the line. Re-running the formatter rejoins literals that
+    earlier versions split across lines. Tabs and other Unicode whitespace
+    inside a literal are preserved as well, instead of being expanded or
+    collapsed.
+  - Google-style compact first lines no longer collapse runs of spaces inside
+    inline literals.
+  - Google-style prose lines that start with an inline literal containing a
+    colon (such as ``` ``key:value`` ```) are no longer mistaken for signature
+    lines, which rewrote the literal's content on a second pass.
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.4.1...0.4.2
+
+## [0.4.1] - 2026-06-30
+
+- Fixed
+  - Google-style compact docstring wrapping now reserves the opening literal
+    width from the source, so plain triple-quoted summaries keep the correct
+    first-line budget while raw and Unicode prefixes still account for their
+    extra prefix column.
+  - One-character quoted docstring literals and adjacent string-token
+    docstrings are skipped as unsupported formatter targets, so long strings
+    are not wrapped into invalid multi-line source.
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.4.0...0.4.1
+
 ## [0.4.0] - 2026-06-29
 
 - Added

{format_docstring-0.4.0 → format_docstring-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.4.0
+Version: 0.4.2
 Summary: A Python formatter to wrap/adjust docstring lines
 Author-email: jsh9 <25124332+jsh9@users.noreply.github.com>
 Maintainer-email: jsh9 <25124332+jsh9@users.noreply.github.com>
@@ -53,6 +53,7 @@ ______________________________________________________________________
   - [5.1. Command Line Interface](#51-command-line-interface)
   - [5.2. Pre-commit Hook](#52-pre-commit-hook)
   - [5.3. Opting Out of Formatting](#53-opting-out-of-formatting)
+  - [5.4. What Counts as a Docstring](#54-what-counts-as-a-docstring)
 - [6. Configuration](#6-configuration)
   - [6.1. Command-Line Options](#61-command-line-options)
   - [6.2. Usage Examples](#62-usage-examples)
@@ -327,6 +328,20 @@ records : list[dict[str, str]]
 """
 ```
 
+**Inline literals are never split.** Each ``` ``...`` ``` span wraps as one
+word, so spaces, tabs and other whitespace inside it are kept and the literal
+stays greppable. A literal longer than the line overflows instead of breaking.
+
+```diff
+"""
+Render a report as text.
+
+-By default, all the nested lines in the generated report are indented with ``'  '`` (two spaces) before they are written.
++By default, all the nested lines in the generated report are indented with
++``'  '`` (two spaces) before they are written.
+"""
+```
+
 **Known sections are parsed, and custom sections are kept.** Recognized section
 titles such as `Parameters`, `Returns`, `Yields`, `Raises`, `Examples`, and
 `Notes` are canonicalized. Unknown underlined sections remain custom sections,
@@ -420,6 +435,20 @@ Args:
 """
 ```
 
+**Inline literals are never split.** Each ``` ``...`` ``` span wraps as one
+word, so spaces, tabs and other whitespace inside it are kept and the literal
+stays greppable. A literal longer than the line overflows instead of breaking.
+
+```diff
+"""
+Render a report as text.
+
+-By default, all the nested lines in the generated report are indented with ``'  '`` (two spaces) before they are written.
++By default, all the nested lines in the generated report are indented with
++``'  '`` (two spaces) before they are written.
+"""
+```
+
 **Custom section boundaries are indentation-sensitive.** Known headers such as
 `Args:`, `Returns:`, `Raises:`, and `Examples:` are canonicalized. Unknown
 peer-level headers after summary content are treated as custom sections, so
@@ -562,6 +591,36 @@ first run `format-docstring`, accept the parts you like, revert the edits you
 dislike, and then add an inline `# no-format-docstring` comment so future runs
 leave that docstring untouched.
 
+### 5.4. What Counts as a Docstring
+
+`format-docstring` follows [Python's docstring rule][python-docstring] to find
+candidate docstrings: the first statement in a module, class, function, or
+method must be a string literal. It intentionally formats only one
+triple-quoted string token with a plain, raw, or Unicode prefix:
+
+```python
+"""Formatted."""
+r"""Formatted."""
+u"""Formatted."""
+```
+
+Single-quoted and double-quoted one-character delimiters can be Python
+docstrings, but they are outside formatter support and are left unchanged.
+Adjacent or implicitly concatenated string literals, formatted string literals,
+and bytes literals are also left unchanged:
+
+```python
+'Not formatted.'
+"Not formatted."
+"""Not formatted.""" "Still not formatted."
+f"""Not a docstring."""
+rf"""Not a docstring."""
+fr"""Not a docstring."""
+b"""Not a docstring."""
+rb"""Not a docstring."""
+br"""Not a docstring."""
+```
+
 ## 6. Configuration
 
 ### 6.1. Command-Line Options
@@ -690,4 +749,5 @@ use AI coding assistants to rewrite the docstrings first.
 [black]: https://github.com/psf/black
 [docformatter]: https://github.com/PyCQA/docformatter
 [pydocstringformatter]: https://github.com/DanielNoord/pydocstringformatter
+[python-docstring]: https://docs.python.org/3/glossary.html#term-docstring
 [ruff]: https://github.com/astral-sh/ruff

{format_docstring-0.4.0 → format_docstring-0.4.2}/README.md

@@ -21,6 +21,7 @@ ______________________________________________________________________
   - [5.1. Command Line Interface](#51-command-line-interface)
   - [5.2. Pre-commit Hook](#52-pre-commit-hook)
   - [5.3. Opting Out of Formatting](#53-opting-out-of-formatting)
+  - [5.4. What Counts as a Docstring](#54-what-counts-as-a-docstring)
 - [6. Configuration](#6-configuration)
   - [6.1. Command-Line Options](#61-command-line-options)
   - [6.2. Usage Examples](#62-usage-examples)
@@ -295,6 +296,20 @@ records : list[dict[str, str]]
 """
 ```
 
+**Inline literals are never split.** Each ``` ``...`` ``` span wraps as one
+word, so spaces, tabs and other whitespace inside it are kept and the literal
+stays greppable. A literal longer than the line overflows instead of breaking.
+
+```diff
+"""
+Render a report as text.
+
+-By default, all the nested lines in the generated report are indented with ``'  '`` (two spaces) before they are written.
++By default, all the nested lines in the generated report are indented with
++``'  '`` (two spaces) before they are written.
+"""
+```
+
 **Known sections are parsed, and custom sections are kept.** Recognized section
 titles such as `Parameters`, `Returns`, `Yields`, `Raises`, `Examples`, and
 `Notes` are canonicalized. Unknown underlined sections remain custom sections,
@@ -388,6 +403,20 @@ Args:
 """
 ```
 
+**Inline literals are never split.** Each ``` ``...`` ``` span wraps as one
+word, so spaces, tabs and other whitespace inside it are kept and the literal
+stays greppable. A literal longer than the line overflows instead of breaking.
+
+```diff
+"""
+Render a report as text.
+
+-By default, all the nested lines in the generated report are indented with ``'  '`` (two spaces) before they are written.
++By default, all the nested lines in the generated report are indented with
++``'  '`` (two spaces) before they are written.
+"""
+```
+
 **Custom section boundaries are indentation-sensitive.** Known headers such as
 `Args:`, `Returns:`, `Raises:`, and `Examples:` are canonicalized. Unknown
 peer-level headers after summary content are treated as custom sections, so
@@ -530,6 +559,36 @@ first run `format-docstring`, accept the parts you like, revert the edits you
 dislike, and then add an inline `# no-format-docstring` comment so future runs
 leave that docstring untouched.
 
+### 5.4. What Counts as a Docstring
+
+`format-docstring` follows [Python's docstring rule][python-docstring] to find
+candidate docstrings: the first statement in a module, class, function, or
+method must be a string literal. It intentionally formats only one
+triple-quoted string token with a plain, raw, or Unicode prefix:
+
+```python
+"""Formatted."""
+r"""Formatted."""
+u"""Formatted."""
+```
+
+Single-quoted and double-quoted one-character delimiters can be Python
+docstrings, but they are outside formatter support and are left unchanged.
+Adjacent or implicitly concatenated string literals, formatted string literals,
+and bytes literals are also left unchanged:
+
+```python
+'Not formatted.'
+"Not formatted."
+"""Not formatted.""" "Still not formatted."
+f"""Not a docstring."""
+rf"""Not a docstring."""
+fr"""Not a docstring."""
+b"""Not a docstring."""
+rb"""Not a docstring."""
+br"""Not a docstring."""
+```
+
 ## 6. Configuration
 
 ### 6.1. Command-Line Options
@@ -658,4 +717,5 @@ use AI coding assistants to rewrite the docstrings first.
 [black]: https://github.com/psf/black
 [docformatter]: https://github.com/PyCQA/docformatter
 [pydocstringformatter]: https://github.com/DanielNoord/pydocstringformatter
+[python-docstring]: https://docs.python.org/3/glossary.html#term-docstring
 [ruff]: https://github.com/astral-sh/ruff

{format_docstring-0.4.0 → format_docstring-0.4.2}/format_docstring/docstring_rewriter.py

@@ -7,7 +7,10 @@ import textwrap
 import tokenize
 from typing import TYPE_CHECKING, cast
 
-from format_docstring.line_wrap_google import wrap_docstring_google
+from format_docstring.line_wrap_google import (
+    GOOGLE_DEFAULT_OPENING_WIDTH,
+    wrap_docstring_google,
+)
 from format_docstring.line_wrap_numpy import (
     handle_single_line_docstring,
     wrap_docstring_numpy,
@@ -503,6 +506,13 @@ def build_replacement_docstring(
     )
     original_literal = source_code[start:end]
 
+    # Python accepts one-character quote delimiters as docstrings, but this
+    # formatter rebuilds literals by preserving the original delimiter. Skip
+    # non-triple-quoted literals so wrapping cannot produce invalid multi-line
+    # single-quoted or double-quoted source.
+    if not _is_triple_quoted_literal(original_literal):
+        return None
+
     if _has_inline_no_format_comment(source_code, end):
         return None
 
@@ -556,6 +566,10 @@ def build_replacement_docstring(
         if class_attr_metadata:
             attribute_metadata = class_attr_metadata
 
+    # Whole-source rewrites know the original source opener. Pass that width
+    # through so compact Google summaries charge raw/unicode prefixes one
+    # extra column while direct wrapper calls keep the bare triple-quote
+    # default.
     wrapped: str = wrap_docstring(
         doc,
         line_length=line_length,
@@ -570,6 +584,7 @@ def build_replacement_docstring(
         include_return_and_yield_types=include_return_and_yield_types,
         compact_google_docstring=True,
         append_google_closing_indent=True,
+        google_opening_width=_literal_opening_width(original_literal),
     )
 
     new_literal: str | None = rebuild_literal(original_literal, wrapped)
@@ -613,6 +628,9 @@ def find_docstring(node: ModuleClassOrFunc) -> ast.Expr | None:
         return None
 
     val = first.value
+    # AST rewrites only handle string-valued docstrings. F-strings parse as
+    # ``ast.JoinedStr`` and bytes literals as ``ast.Constant[bytes]``, so they
+    # stay untouched instead of being rebuilt as text.
     if isinstance(val, ast.Constant) and isinstance(val.value, str):
         return first
 
@@ -712,6 +730,63 @@ def rebuild_literal(original_literal: str, content: str) -> str | None:
     return f'{prefix}{delim}{content}{delim}'
 
 
+def _is_triple_quoted_literal(original_literal: str) -> bool:
+    """
+    Return True if the source slice is one triple-quoted string token.
+
+    This checks the formatter's supported source shape, not Python's broader
+    docstring definition. Adjacent string tokens can still become one AST
+    docstring value, but rebuilding them as one preserved-delimiter literal can
+    expose delimiter text that was safe only while split across tokens.
+    """
+    try:
+        string_tokens = [
+            tok.string
+            for tok in tokenize.generate_tokens(
+                io.StringIO(original_literal).readline
+            )
+            if tok.type == tokenize.STRING
+        ]
+    except tokenize.TokenError:
+        return False
+
+    if len(string_tokens) != 1:
+        return False
+
+    literal = string_tokens[0]
+    i = 0
+    n = len(literal)
+    while i < n and literal[i] in 'rRuUbBfF':
+        i += 1
+
+    return literal[i : i + 3] in {'"""', "'''"}
+
+
+def _literal_opening_width(original_literal: str) -> int:
+    """
+    Return the source opener width before the first content character.
+
+    Compact Google rewrites keep the first summary beside the opener, so pass
+    two must reserve the exact prefix plus quote delimiter columns from the
+    source slice. This helper is intentionally syntactic: it can measure
+    prefixes such as ``rf``/``rb`` even though docstring detection still
+    decides whether such literals are format targets. If parsing fails, use the
+    bare triple-quote default for direct-wrapper-style fallbacks.
+    """
+    i = 0
+    n = len(original_literal)
+    while i < n and original_literal[i] in 'rRuUbBfF':
+        i += 1
+
+    if original_literal[i : i + 3] in {'"""', "'''"}:
+        return i + 3
+
+    if i < n and original_literal[i] in {'"', "'"}:
+        return i + 1
+
+    return GOOGLE_DEFAULT_OPENING_WIDTH
+
+
 def wrap_docstring(
         docstring: str,
         line_length: int = 79,
@@ -727,6 +802,7 @@ def wrap_docstring(
         include_return_and_yield_types: bool = True,
         compact_google_docstring: bool = False,
         append_google_closing_indent: bool = False,
+        google_opening_width: int = GOOGLE_DEFAULT_OPENING_WIDTH,
 ) -> str:
     """
     Wrap a docstring to the given line length (stub).
@@ -768,6 +844,11 @@ def wrap_docstring(
     append_google_closing_indent : bool, default=False
         If True, Google-style wrapping appends the indentation needed before
         closing quotes in rebuilt docstring literals.
+    google_opening_width : int, default=GOOGLE_DEFAULT_OPENING_WIDTH
+        Visible width of the opening literal prefix plus quote delimiter for
+        compact Google docstrings. Whole-source rewrites pass the value
+        measured from the source literal; direct wrapper calls use the bare
+        triple-quote default because no literal prefix is available.
 
     Returns
     -------
@@ -817,6 +898,7 @@ def wrap_docstring(
             include_arg_defaults=include_arg_defaults,
             include_return_and_yield_types=include_return_and_yield_types,
             compact_first_line=compact_google_docstring,
+            opening_width=google_opening_width,
         )
     # Default to NumPy-style for unknown/unspecified styles to be permissive.
     return wrap_docstring_numpy(

{format_docstring-0.4.0 → format_docstring-0.4.2}/format_docstring/line_wrap_google.py

@@ -15,9 +15,12 @@ from format_docstring.line_wrap_utils import (
     is_code_fence,
     is_google_doctest_block,
     is_google_examples_code_block,
+    is_inside_inline_literal,
     merge_lines_and_strip,
+    protect_inline_literal_spaces,
     segment_lines_by_wrappability,
     validate_include_arg_defaults,
+    wrap_keeping_inline_literals,
 )
 from format_docstring.section_utils import (
     canonical_google_section_header,
@@ -30,10 +33,10 @@ from format_docstring.section_utils import (
     is_google_yields_section_header,
 )
 
-# Google docstrings can preserve string prefixes such as ``rf`` when rebuilt,
-# so first-line wrapping reserves two prefix characters plus opening quotes.
-GOOGLE_OPENING_QUOTES_WIDTH: Final[int] = 5
-GOOGLE_COMPACT_OPENING_QUOTES_WIDTH: Final[int] = 5
+# Direct wrapper calls receive docstring content without source quotes, so use
+# the bare triple-quote width. AST rewrites override this with the measured
+# source-literal opener to keep compact first-line budgets exact.
+GOOGLE_DEFAULT_OPENING_WIDTH: Final[int] = 3
 GOOGLE_MIN_SIGNATURE_DESC_WIDTH: Final[int] = 10
 GOOGLE_SIGNATURE_MAX_TOKENS: Final[int] = 2
 
@@ -101,7 +104,7 @@ class _GoogleWrapState:
     output: list[str]
     leading_indent: int
     line_length: int
-    compact_first_line: bool
+    opening_width: int
     opening_quotes_on_own_line: bool
     include_return_and_yield_types: bool
     is_first_line: bool = True
@@ -125,6 +128,7 @@ def wrap_docstring_google(
         include_arg_defaults: bool = True,
         include_return_and_yield_types: bool = True,
         compact_first_line: bool = False,
+        opening_width: int = GOOGLE_DEFAULT_OPENING_WIDTH,
 ) -> str:
     """
     Wrap Google-style docstrings.
@@ -133,6 +137,11 @@ def wrap_docstring_google(
     finally wraps them to the target line length. The backtick pass must run
     first because single backticks can expand to double backticks; doing that
     after wrapping can make the final output exceed ``line_length``.
+
+    ``opening_width`` affects first-line wrapping. AST rewrites pass the
+    measured source-literal opener so raw/unicode prefixes reduce the first
+    content budget; callers without source context keep the bare-triple-quote
+    default.
     """
     validate_include_arg_defaults(
         include_arg_types=include_arg_types,
@@ -170,8 +179,8 @@ def wrap_docstring_google(
         line_length=line_length,
         leading_indent=leading_indent,
         closing_indent=closing_indent,
-        compact_first_line=should_compact_first_line,
         opening_quotes_on_own_line=opening_quotes_on_own_line,
+        opening_width=opening_width,
         include_return_and_yield_types=include_return_and_yield_types,
     )
 
@@ -1047,8 +1056,8 @@ def _pass2_wrap_google_docstring(
         line_length: int,
         leading_indent: int | None = None,
         closing_indent: int | None = None,
-        compact_first_line: bool = False,
         opening_quotes_on_own_line: bool = False,
+        opening_width: int = GOOGLE_DEFAULT_OPENING_WIDTH,
         include_return_and_yield_types: bool = True,
 ) -> str:
     """
@@ -1062,7 +1071,7 @@ def _pass2_wrap_google_docstring(
         output=[],
         leading_indent=leading_indent or 0,
         line_length=line_length,
-        compact_first_line=compact_first_line,
+        opening_width=opening_width,
         opening_quotes_on_own_line=opening_quotes_on_own_line,
         include_return_and_yield_types=include_return_and_yield_types,
     )
@@ -1213,14 +1222,21 @@ def _google_effective_signature_indent(
         state: _GoogleWrapState,
         parts: _GoogleLineParts,
 ) -> int:
-    """Return indent used by pass-two signature context checks."""
+    """
+    Return first-line signature indent after accounting for opener width.
+
+    Compact first lines lose columns to the literal opener before content
+    starts. Signature context checks need that effective indent so a first-line
+    ``Args:`` item is classified the same way it would be on later physical
+    lines.
+    """
     if not state.is_first_line:
         return parts.indent_level
 
     if parts.indent_level < state.leading_indent:
-        return state.leading_indent + GOOGLE_OPENING_QUOTES_WIDTH
+        return state.leading_indent + state.opening_width
 
-    return parts.indent_level + GOOGLE_OPENING_QUOTES_WIDTH
+    return parts.indent_level + state.opening_width
 
 
 def _is_google_signature_line_in_context(
@@ -1286,15 +1302,16 @@ def _wrap_google_first_prose_line(
         state: _GoogleWrapState,
         parts: _GoogleLineParts,
 ) -> None:
-    """Wrap the first physical docstring line with opening-quote budget."""
-    opening_width = (
-        GOOGLE_COMPACT_OPENING_QUOTES_WIDTH
-        if state.compact_first_line
-        else GOOGLE_OPENING_QUOTES_WIDTH
-    )
+    """
+    Wrap the first physical docstring line with source-opener budget.
+
+    Compact Google output rebuilds the opener outside this content string, so
+    the wrapper must reserve those columns before deciding whether the first
+    summary fits.
+    """
     first_line_width = max(
         1,
-        state.line_length - state.leading_indent - opening_width,
+        state.line_length - state.leading_indent - state.opening_width,
     )
     state.output.extend(
         _wrap_first_line_shorter(
@@ -1319,15 +1336,19 @@ def _wrap_google_normal_prose_line(
     ):
         subsequent_indent = ' ' * state.leading_indent
 
-    wrapped = textwrap.fill(
-        parts.line.strip(),
-        width=state.line_length,
-        initial_indent=parts.indent_str,
-        subsequent_indent=subsequent_indent,
-        break_long_words=False,
-        break_on_hyphens=False,
+    state.output.extend(
+        wrap_keeping_inline_literals(
+            parts.line.strip(),
+            lambda text: textwrap.wrap(
+                text,
+                width=state.line_length,
+                initial_indent=parts.indent_str,
+                subsequent_indent=subsequent_indent,
+                break_long_words=False,
+                break_on_hyphens=False,
+            ),
+        )
     )
-    state.output.extend(wrapped.splitlines())
 
 
 def _wrap_google_signature_line(
@@ -1367,7 +1388,9 @@ def _wrap_google_signature_line(
 
     first_line_prefix = sig_part_stripped + ' '
     remaining_first = line_length - len(first_line_prefix)
-    first_word = desc_part.split()[0] if desc_part else ''
+    # Measure the first unbreakable word: a leading inline literal containing
+    # spaces must move to the continuation line as a whole when it can't fit.
+    first_word = protect_inline_literal_spaces(desc_part).split()[0]
     if (
         remaining_first < GOOGLE_MIN_SIGNATURE_DESC_WIDTH
         or len(first_word) > remaining_first
@@ -1381,15 +1404,17 @@ def _wrap_google_signature_line(
             ),
         ]
 
-    wrapped = textwrap.fill(
+    return wrap_keeping_inline_literals(
         desc_part,
-        width=line_length,
-        initial_indent=first_line_prefix,
-        subsequent_indent=subsequent_indent,
-        break_long_words=False,
-        break_on_hyphens=False,
+        lambda text: textwrap.wrap(
+            text,
+            width=line_length,
+            initial_indent=first_line_prefix,
+            subsequent_indent=subsequent_indent,
+            break_long_words=False,
+            break_on_hyphens=False,
+        ),
     )
-    return wrapped.splitlines()
 
 
 def _wrap_google_signature_description(
@@ -1399,15 +1424,17 @@ def _wrap_google_signature_description(
         subsequent_indent: str,
 ) -> list[str]:
     """Wrap a Google signature description on continuation lines."""
-    wrapped = textwrap.fill(
+    return wrap_keeping_inline_literals(
         description,
-        width=line_length,
-        initial_indent=subsequent_indent,
-        subsequent_indent=subsequent_indent,
-        break_long_words=False,
-        break_on_hyphens=False,
+        lambda text: textwrap.wrap(
+            text,
+            width=line_length,
+            initial_indent=subsequent_indent,
+            subsequent_indent=subsequent_indent,
+            break_long_words=False,
+            break_on_hyphens=False,
+        ),
     )
-    return wrapped.splitlines()
 
 
 def _wrap_first_line_shorter(
@@ -1437,6 +1464,32 @@ def _wrap_first_line_shorter(
     if not text.strip():
         return [initial_indent + text] if text else []
 
+    return wrap_keeping_inline_literals(
+        text,
+        lambda masked_text: _wrap_words_first_line_shorter(
+            masked_text,
+            first_line_width=first_line_width,
+            subsequent_width=subsequent_width,
+            initial_indent=initial_indent,
+            subsequent_indent=subsequent_indent,
+        ),
+    )
+
+
+def _wrap_words_first_line_shorter(
+        text: str,
+        *,
+        first_line_width: int,
+        subsequent_width: int,
+        initial_indent: str,
+        subsequent_indent: str,
+) -> list[str]:
+    """
+    Greedily fill whitespace-separated words for ``_wrap_first_line_shorter``.
+
+    Splitting on whitespace re-joins words with single spaces, so callers must
+    mask whitespace that is significant (e.g. inside inline literals) first.
+    """
     words = text.split()
     if not words:
         return []
@@ -1898,12 +1951,15 @@ def _rewrite_google_return_signature(line: str, annotation: str) -> str:
 
 def _find_google_signature_colon(line: str) -> int:
     """
-    Return the delimiter colon outside brackets and parentheses.
+    Return the delimiter colon outside brackets, parentheses and literals.
 
     Google signatures use that colon to separate the signature from the
     description. Skipping nested colons prevents rare type expressions from
     being split in the middle before signature spacing is normalized for
-    malformed Google signature fixtures.
+    malformed Google signature fixtures. Colons inside rST inline literals
+    (``` ``key:value`` ```) are skipped too: a prose line that starts with such
+    a literal is not a signature, and treating it as one would rewrite the
+    literal's content.
     """
     nesting = 0
     for idx, char in enumerate(line):
@@ -1911,7 +1967,11 @@ def _find_google_signature_colon(line: str) -> int:
             nesting += 1
         elif char in ')]}':
             nesting -= 1
-        elif char == ':' and nesting == 0:
+        elif (
+            char == ':'
+            and nesting == 0
+            and not is_inside_inline_literal(line, idx)
+        ):
             return idx
 
     return -1