docstrfmt 2.0.2__tar.gz → 2.1.0__tar.gz

{docstrfmt-2.0.2 → docstrfmt-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstrfmt
-Version: 2.0.2
+Version: 2.1.0
 Summary: docstrfmt: A formatter for Sphinx flavored reStructuredText.
 Keywords: black,docutils,autoformatter,formatter,lint,restructuredtext,rst,sphinx
 Author-email: Joel Payne <lilspazjoekp@gmail.com>
@@ -32,9 +32,9 @@ Requires-Dist: libcst>=1
 Requires-Dist: platformdirs>=4
 Requires-Dist: roman
 Requires-Dist: sphinx>=7
-Requires-Dist: tabulate>=0.9
+Requires-Dist: tabulate>=0.10.0
 Requires-Dist: tomli>=0.10;python_version<'3.11'
-Requires-Dist: types-docutils==0.22.3.20251115
+Requires-Dist: types-docutils==0.22.3.20260518
 Requires-Dist: aiohttp ; extra == "d"
 Project-URL: Issue Tracker, https://github.com/LilSpazJoekp/docstrfmt/issues
 Project-URL: Source Code, https://github.com/LilSpazJoekp/docstrfmt

{docstrfmt-2.0.2 → docstrfmt-2.1.0}/docstrfmt/__init__.py

@@ -9,4 +9,4 @@ from .const import (
 )
 from .docstrfmt import Manager
 
-__version__ = "2.0.2"
+__version__ = "2.1.0"

{docstrfmt-2.0.2 → docstrfmt-2.1.0}/docstrfmt/docstrfmt.py

@@ -25,6 +25,7 @@ from docutils import nodes, utils
 from docutils.frontend import OptionParser
 from docutils.parsers import rst
 from docutils.parsers.rst import Directive, roles
+from docutils.statemachine import StringList
 from docutils.transforms import Transform
 from docutils.utils import new_document, unescape
 
@@ -167,7 +168,7 @@ class FormatContext:
         self.manager = manager
         self.black_config = black_config
         self.starting_width = width
-        self.bullet: str = ""
+        self.bullet: str = "-"
         self.column_widths = []
         self.current_ordinal = 0
         self.first_line_len: int = 0
@@ -338,6 +339,7 @@ class CodeFormatters:
 
         """
         manager = self.context.manager
+        manager.original_text = self.code
         try:
             document = manager.parse_string(
                 self.code, line_offset=manager.get_code_line(self.code) - 1
@@ -364,6 +366,8 @@ class Manager:
         *,
         current_file: Path | str,
         black_config: Mode | None = None,
+        center_section_titles: bool = True,
+        bullet_list_marker: str = "-",
         docstring_trailing_line: bool = True,
         format_python_code_blocks: bool = True,
         reporter: Reporter | utils.Reporter | logging.Logger,
@@ -374,6 +378,9 @@ class Manager:
         :param current_file: The current file being processed.
         :param reporter: utils.Reporter instance for logging.
         :param black_config: Black formatting configuration.
+        :param center_section_titles: Whether to center section titles with overlines
+            by adding a leading space.
+        :param bullet_list_marker: Bullet character to use for unordered lists.
         :param docstring_trailing_line: Whether to add trailing line to docstrings.
         :param format_python_code_blocks: Whether to format Python code blocks.
         :param section_adornments: Section adornment configuration.
@@ -382,6 +389,8 @@ class Manager:
         rst_extras.register()
         self.current_file = current_file
         self.black_config = black_config
+        self.center_section_titles = center_section_titles
+        self.bullet_list_marker = bullet_list_marker
         self.current_offset = 0
         self.error_count = 0
         self.reporter = reporter
@@ -901,7 +910,9 @@ class Formatters:
             - Third item
 
         """
-        yield from self._list(node, context.with_bullet("-"))
+        yield from self._list(
+            node, context.with_bullet(context.manager.bullet_list_marker)
+        )
 
     def comment(
         self,
@@ -1008,6 +1019,18 @@ class Formatters:
         directive = attributes["directive"]
         is_code_block = directive.name in ["code", "code-block", "sourcecode"]
         in_substitution = isinstance(node.parent, nodes.substitution_definition)
+        if (
+            directive.name
+            in ["deprecated", "versionadded", "versionchanged", "versionremoved"]
+            and len(directive.arguments) > 1
+        ):
+            # These directives have a required argument that we want to preserve, but
+            # the content is just a normal paragraph that we can format like usual.
+            # If there is more than 1 argument, then those need to be moved to the
+            # content attribute.
+            directive.content = StringList(directive.arguments[1:])
+            directive.arguments = directive.arguments[:1]
+
         parts = [
             f".. {'code-block' if is_code_block else directive.name}::",
             *directive.arguments,
@@ -1574,9 +1597,9 @@ class Formatters:
 
         """
         if not node.children:  # pragma: no cover
-            yield "-"  # no idea why this isn't covered anymore
+            yield context.bullet  # no idea why this isn't covered anymore
             return
-        if context.current_ordinal and context.bullet not in ["-", "*", "+"]:
+        if context.current_ordinal:
             context.bullet = make_enumerator(
                 context.current_ordinal, context.ordinal_format, ("", ".")
             )
@@ -1596,7 +1619,7 @@ class Formatters:
         node: nodes.literal,
         context: FormatContext,
     ) -> inline_iterator:
-        """Format a literal node.
+        r"""Format a literal node.
 
         Example:
 
@@ -1604,7 +1627,23 @@ class Formatters:
 
             This is ``literal`` text.
 
+        If the literal needs to end with a space:
+
+        .. code-block:: rst
+
+            This is a :literal:`literal with a trailing space \ ` that is not surrounded
+            with (``).
+
         """
+        if node.rawsource.startswith(":literal:") and node.rawsource.endswith(
+            (r"\ `", "\\\n`")
+        ):
+            # When the node ends with a backslash followed by a space or new line, don't
+            # remove the :literal: role and just return the node untouched. This is a
+            # workaround for specific edge cases in docutils.
+            yield inline_markup(node.rawsource)
+            return
+
         yield inline_markup(
             f"``{''.join(chain(self._format_children(node, context)))}``"
         )
@@ -2203,10 +2242,16 @@ class Formatters:
                 raise
 
         if overline:
-            # section headings with overline are centered
-            yield char * (2 + len(text))
-            yield " " + text
-            yield char * (2 + len(text))
+            if context.manager.center_section_titles:
+                # section headings with overline are centered
+                yield char * (2 + len(text))
+                yield " " + text
+                yield char * (2 + len(text))
+            else:
+                # section headings with overline are not centered
+                yield char * len(text)
+                yield text
+                yield char * len(text)
         else:
             # sections headings without overline are justified
             yield text

{docstrfmt-2.0.2 → docstrfmt-2.1.0}/docstrfmt/main.py

@@ -66,6 +66,8 @@ def _format_file(
     section_adornments: list[tuple[str, bool]] | None,
     raw_output: bool,
     lock: Lock | None,
+    bullet_list_marker: str = "-",
+    center_section_titles: bool = True,
 ):
     """Format a single file with the given parameters.
 
@@ -80,6 +82,8 @@ def _format_file(
     :param section_adornments: Section adornment configuration.
     :param raw_output: Whether to output raw formatted text.
     :param lock: Lock for thread safety.
+    :param bullet_list_marker: Bullet character to use for unordered lists.
+    :param center_section_titles: Whether to center section titles with overlines.
 
     :returns: A tuple containing a boolean indicating if the file was misformatted and
         the number of errors.
@@ -89,6 +93,8 @@ def _format_file(
     manager = Manager(
         current_file=file.name,
         black_config=mode,
+        bullet_list_marker=bullet_list_marker,
+        center_section_titles=center_section_titles,
         docstring_trailing_line=docstring_trailing_line,
         format_python_code_blocks=format_python_code_blocks,
         reporter=reporter,
@@ -181,14 +187,14 @@ def _parse_pyproject_config(
                 config_value = config.get(key)
                 if config_value is not None and not isinstance(config_value, list):
                     raise click.BadOptionUsage(key, f"Config key {key} must be a list")
-            params = {}
+            # Expose config values through the default map only; writing them
+            # directly into context.params conflicts with how click >=8.4
+            # arbitrates which parameter owns a value slot.
+            default_map = {}
             if context.default_map is not None:  # pragma: no cover
-                params.update(context.default_map)
-            if context.params is not None:
-                params.update(context.params)
-            params.update(config)
-            context.params = params
-            context.default_map = params
+                default_map.update(context.default_map)
+            default_map.update(config)
+            context.default_map = default_map
 
         black_config = parse_pyproject_toml(value)
         black_config.pop("exclude", None)
@@ -215,11 +221,21 @@ def _parse_sources(context: click.Context, _: click.Parameter, value: list[str]
     :returns: List of resolved file paths to format.
 
     """
-    sources = value or context.params.get("files", [])
-    exclude = list(context.params.get("exclude", DEFAULT_EXCLUDE))
-    extend_exclude = list(context.params.get("extend_exclude", []))
+    default_map = context.default_map or {}
+
+    def lookup(name: str, fallback: Any) -> Any:
+        # Sibling parameters may not be processed yet when this callback runs,
+        # so fall back to the default map, which _parse_pyproject_config fills
+        # with pyproject.toml values.
+        if name in context.params:
+            return context.params[name]
+        return default_map.get(name, fallback)
+
+    sources = value or lookup("files", [])
+    exclude = list(lookup("exclude", DEFAULT_EXCLUDE))
+    extend_exclude = list(lookup("extend_exclude", []))
     exclude.extend(extend_exclude)
-    include_txt = context.params.get("include_txt", False)
+    include_txt = lookup("include_txt", False)
     files_to_format = set()
     extensions = [".py", ".rst"] + ([".txt"] if include_txt else [])
     for source in sources:
@@ -243,10 +259,7 @@ def _parse_sources(context: click.Context, _: click.Parameter, value: list[str]
             if file.parent.match(exclusion) or file.match(exclusion):
                 files_to_format.discard(abspath(file))
                 break
-    sorted_files = sorted(files_to_format)
-    if context.params.get("files", []):
-        context.params["files"] = sorted_files
-    return sorted_files
+    return sorted(files_to_format)
 
 
 def _process_python(
@@ -359,20 +372,6 @@ def _process_rst(
     return misformatted, error_count
 
 
-def _resolve_length(context: click.Context, _: click.Parameter, value: int | None):
-    """Resolve line length from command line or pyproject.toml.
-
-    :param context: Click context containing command parameters.
-    :param _: Unused parameter.
-    :param value: Line length from command line.
-
-    :returns: Resolved line length value.
-
-    """
-    pyproject_line_length = context.params.pop("line_length", None)
-    return value or pyproject_line_length
-
-
 def _validate_adornments(
     context: click.Context, _: click.Parameter, value: str | None
 ) -> list[tuple[str, bool]] | None:
@@ -380,14 +379,14 @@ def _validate_adornments(
 
     :param context: Click context containing command parameters.
     :param _: Unused parameter.
-    :param value: Section adornments string from command line.
+    :param value: Section adornments string from the command line or pyproject.toml.
 
     :returns: List of tuples containing (character, has_overline) for each adornment.
 
     :raises click.BadParameter: If adornments are not unique.
 
     """
-    actual_value = context.params.pop("section_adornments", value)
+    actual_value = SECTION_CHARS if value is None else value
 
     if len(actual_value) != len(set(actual_value)):
         msg = "Section adornments must be unique"
@@ -418,6 +417,8 @@ async def _run_formatter(
     cache: FileCache,
     loop: asyncio.AbstractEventLoop,
     executor: ProcessPoolExecutor | ThreadPoolExecutor,
+    bullet_list_marker: str = "-",
+    center_section_titles: bool = True,
 ):
     """Run the formatter on multiple files asynchronously.
 
@@ -434,6 +435,8 @@ async def _run_formatter(
     :param cache: File cache for tracking changes.
     :param loop: Event loop for async operations.
     :param executor: Process or thread pool executor.
+    :param bullet_list_marker: Bullet character to use for unordered lists.
+    :param center_section_titles: Whether to center section titles with overlines.
 
     :returns: Tuple of (misformatted_files, total_error_count).
 
@@ -461,6 +464,8 @@ async def _run_formatter(
                 section_adornments,
                 raw_output,
                 lock,
+                bullet_list_marker,
+                center_section_titles,
             )
         ): file
         for file in sorted(todo)
@@ -489,8 +494,13 @@ async def _run_formatter(
                 if misformatted:
                     misformatted_files.add(file)
                 if (
-                    not (misformatted and raw_output) or (check and not misformatted)
-                ) and errors == 0:
+                    file.name != "-"  # stdin cannot be cached
+                    and (
+                        not (misformatted and raw_output)
+                        or (check and not misformatted)
+                    )
+                    and errors == 0
+                ):
                     files_to_cache.append(file)
     if cancelled:  # pragma: no cover
         await asyncio.gather(*cancelled, return_exceptions=True)
@@ -839,6 +849,23 @@ class Visitor(CSTTransformer):
 
 # noinspection PyUnusedLocal
 @click.command(context_settings={"help_option_names": ["-h", "--help"]})
+@click.option(
+    "-b",
+    "--bullet-list-marker",
+    default="-",
+    help="Bullet character to use for unordered lists.",
+    show_default=True,
+    type=click.Choice(["-", "*", "+"], case_sensitive=False),
+)
+@click.option(
+    "--center-section-titles/--no-center-section-titles",
+    default=True,
+    help=(
+        "Whether to center section titles with overlines by adding a leading space."
+        " When disabled, section titles with overlines will not have a leading space"
+        " and the adornment will match the exact length of the title text."
+    ),
+)
 @click.option(
     "-c",
     "--check",
@@ -909,7 +936,6 @@ class Visitor(CSTTransformer):
         " 'line-length' set in pyproject.toml if set. Defaults to the length provided"
         " to black if not set."
     ),
-    callback=_resolve_length,
 )
 @click.option(
     "-pA",
@@ -987,6 +1013,8 @@ class Visitor(CSTTransformer):
 @click.pass_context
 def main(
     context: Context,
+    bullet_list_marker: str,
+    center_section_titles: bool,
     check: bool,
     docstring_trailing_line: bool,
     exclude: list[str],
@@ -1008,6 +1036,8 @@ def main(
     """Format reStructuredText and Python files.
 
     :param context: Click context containing command parameters.
+    :param bullet_list_marker: Bullet character to use for unordered lists.
+    :param center_section_titles: Whether to center section titles with overlines.
     :param check: Whether to check formatting without modifying files.
     :param docstring_trailing_line: Whether to add trailing line to docstrings.
     :param exclude: List of paths to exclude from formatting.
@@ -1050,6 +1080,8 @@ def main(
         manager = Manager(
             current_file=file,
             black_config=mode,
+            bullet_list_marker=bullet_list_marker,
+            center_section_titles=center_section_titles,
             docstring_trailing_line=docstring_trailing_line,
             format_python_code_blocks=format_python_code_blocks,
             reporter=reporter,
@@ -1077,10 +1109,18 @@ def main(
 
     cache = FileCache(context, ignore_cache)
     if len(files) < 2:
-        for file in files:
+        if raw_output:
+            # Raw output must always be emitted, even for cached files.
+            todo = {Path(file).resolve() for file in files}
+        else:
+            todo, _already_done = cache.gen_todo_list(files)
+        files_to_cache = []
+        for file in (Path(f) for f in files):
+            if file.resolve() not in todo:
+                continue
             misformatted, error_count = _format_file(
                 check,
-                Path(file),
+                file,
                 file_type,
                 include_txt,
                 line_length,
@@ -1090,9 +1130,20 @@ def main(
                 section_adornments,
                 raw_output,
                 None,
+                bullet_list_marker,
+                center_section_titles,
             )
             if misformatted:
                 misformatted_files.add(file)
+            if (
+                file.name != "-"  # stdin cannot be cached
+                and not raw_output  # raw output does not modify the file
+                and not (check and misformatted)  # the file remains misformatted
+                and error_count == 0
+            ):
+                files_to_cache.append(file)
+        if files_to_cache:
+            cache.write_cache(files_to_cache)
 
     else:
         # This code is heavily based on that of psf/black
@@ -1126,6 +1177,8 @@ def main(
                     cache,
                     loop,
                     executor,
+                    bullet_list_marker,
+                    center_section_titles,
                 )
             )
         finally:

{docstrfmt-2.0.2 → docstrfmt-2.1.0}/docstrfmt/util.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import hashlib
 import pickle
 import tempfile
 from collections import defaultdict
@@ -59,6 +60,23 @@ def make_enumerator(ordinal: int, sequence: str, fmt: tuple[str, str]) -> str:
 class FileCache:
     """A class to manage the cache of files."""
 
+    # Parameters that do not affect how a given file is formatted and therefore
+    # must not influence the cache key.
+    _NON_FORMATTING_PARAMS = frozenset(
+        [
+            "check",
+            "exclude",
+            "extend_exclude",
+            "files",
+            "ignore_cache",
+            "mode",
+            "quiet",
+            "raw_input",
+            "raw_output",
+            "verbose",
+        ]
+    )
+
     @staticmethod
     def _get_file_info(file: Path) -> tuple[float, int]:
         """Get the file info.
@@ -88,20 +106,22 @@ class FileCache:
     def _get_cache_filename(self) -> Path:
         """Get the cache filename.
 
+        The filename incorporates every parameter that affects formatting output
+        (e.g., ``section_adornments``, ``bullet_list_marker``) so that changing any
+        of them invalidates previously cached results.
+
         :returns: Path to the cache file.
 
         """
-        docstring_trailing_line = str(self.context.params["docstring_trailing_line"])
-        format_python_code_blocks = str(
-            self.context.params["format_python_code_blocks"]
-        )
-        line_length = str(self.context.params["line_length"])
-        mode = self.context.params["mode"].get_cache_key()
-        include_txt = str(self.context.params["include_txt"])
-        return (
-            self.cache_dir
-            / f"cache.{f'{docstring_trailing_line}_{format_python_code_blocks}_{include_txt}_{line_length}_{mode}'}.pickle"
-        )
+        params = self.context.params
+        parts = [
+            f"{name}={params[name]!r}"
+            for name in sorted(params)
+            if name not in self._NON_FORMATTING_PARAMS
+        ]
+        parts.append(f"mode={params['mode'].get_cache_key()}")
+        key = hashlib.sha256("|".join(parts).encode("utf-8")).hexdigest()
+        return self.cache_dir / f"cache.{key}.pickle"
 
     def _read_cache(self) -> dict[str, tuple[float, int]]:
         """Read the cache file.
@@ -134,8 +154,9 @@ class FileCache:
         todo, done = set(), set()
         for file in (Path(f).resolve() for f in files):
             if (
-                self.cache.get(str(file)) != self._get_file_info(file)
+                file.name == "-"  # stdin cannot be cached
                 or self.ignore_cache
+                or self.cache.get(str(file)) != self._get_file_info(file)
             ):
                 todo.add(file)
             else:

{docstrfmt-2.0.2 → docstrfmt-2.1.0}/pyproject.toml

@@ -11,7 +11,7 @@ dev = [
 lint = [
   "pre-commit",
   "pyright>=1.1.406",
-  "ruff>=0.0.292"
+  "ruff>=0.15.10"
 ]
 test = [
   "aiohttp",
@@ -52,9 +52,9 @@ dependencies = [
   "platformdirs>=4",
   "roman",
   "sphinx>=7",
-  "tabulate>=0.9",
+  "tabulate>=0.10.0",
   "tomli>=0.10;python_version<'3.11'",
-  "types-docutils==0.22.3.20251115"
+  "types-docutils==0.22.3.20260518"
 ]
 dynamic = ["version", "description"]
 keywords = ["black", "docutils", "autoformatter", "formatter", "lint", "restructuredtext", "rst", "sphinx"]