docstrfmt 1.5.1.dev0__tar.gz → 1.6.0__tar.gz

{docstrfmt-1.5.1.dev0 → docstrfmt-1.6.0}/CHANGES.rst

@@ -1,10 +1,39 @@
 Change Log
 ==========
 
-Unreleased
-----------
+1.6.0 (2023/12/10)
+------------------
+
+**Added**
+
+- Added more missing roles.
+- Added support for Python 3.11.
+- Added support for Python 3.12.
+
+**Changed**
+
+- Improved field sorting and formatting.
+- Improved handling of ``:param:`` and ``:type:`` fields.
+- Bumped ``black``, ``docutils``, ``libcst``, ``platformdirs``, and ``sphinx`` to latest
+  versions.
+
+**Fixed**
+
+- Fix ``:raises:`` field not supporting types.
+
+**Removed**
+
+- Removed support for Python 3.6.
+- Removed support for Python 3.7.
+
+1.5.1 (2022/09/01)
+------------------
+
+**Fixed**
+
+- Fix ``ImportError`` when importing from black. Pinned black to 22.8.*.
 
-1.5.0 (2022/05/31)
+1.5.0 (2022/07/19)
 ------------------
 
 **Added**

{docstrfmt-1.5.1.dev0 → docstrfmt-1.6.0}/PKG-INFO

@@ -1,34 +1,56 @@
 Metadata-Version: 2.1
 Name: docstrfmt
-Version: 1.5.1.dev0
+Version: 1.6.0
 Summary: A formatter for Sphinx flavored reStructuredText.
 Home-page: https://github.com/LilSpazJoekp/docstrfmt
 Author: Joel Payne
 Author-email: lilspazjoekp@gmail.com
 License: MIT
-Platform: UNKNOWN
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.6
-Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python
 Classifier: Topic :: Documentation
 Classifier: Topic :: Documentation :: Sphinx
 Classifier: Topic :: Software Development :: Documentation
 Classifier: Topic :: Utilities
-Requires-Python: ~=3.6
+Requires-Python: ~=3.8
+License-File: LICENSE.txt
+License-File: AUTHORS.rst
+Requires-Dist: black==23.*
+Requires-Dist: click==8.*
+Requires-Dist: docutils==0.20.*
+Requires-Dist: libcst==1.*
+Requires-Dist: platformdirs==4.*
+Requires-Dist: sphinx==7.*
+Requires-Dist: tabulate==0.9.*
+Requires-Dist: toml==0.10.*
+Provides-Extra: ci
+Requires-Dist: coveralls; extra == "ci"
 Provides-Extra: d
+Requires-Dist: aiohttp==3.*; extra == "d"
 Provides-Extra: dev
+Requires-Dist: packaging; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-aiohttp; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: flynt; extra == "dev"
+Requires-Dist: isort; extra == "dev"
 Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-aiohttp; extra == "test"
 Provides-Extra: lint
-License-File: LICENSE.txt
-License-File: AUTHORS.rst
+Requires-Dist: flake8; extra == "lint"
+Requires-Dist: flynt; extra == "lint"
+Requires-Dist: isort; extra == "lint"
 
 docstrfmt: a formatter for Sphinx flavored reStructuredText
 ===========================================================
@@ -167,7 +189,7 @@ Instructions derived from `black documentation
 
     Note that if you are using a virtual environment detected by PyCharm, this is an
     unneeded step. In this case the path to `docstrfmt` is
-    `$PyInterpreterDirectory$/docstrfmt`.
+    ``$PyInterpreterDirectory$/docstrfmt``.
 
 3. Open External tools in PyCharm.
 
@@ -184,7 +206,7 @@ Instructions derived from `black documentation
    - Name: docstrfmt
    - Description:
    - Program: <install_location_from_step_2>
-   - Arguments: `"$FilePath$"`
+   - Arguments: ``"$FilePath$"``
 
 5. Format the currently opened file by selecting `Tools -> External Tools -> docstrfmt`.
 
@@ -202,9 +224,9 @@ Instructions derived from `black documentation
       - File type: Python
       - Scope: Project Files
       - Program: <install_location_from_step_2>
-      - Arguments: `$FilePath$`
-      - Output paths to refresh: `$FilePath$`
-      - Working directory: `$ProjectFileDir$`
+      - Arguments: ``$FilePath$``
+      - Output paths to refresh: ``$FilePath$``
+      - Working directory: ``$ProjectFileDir$``
 
    3. Uncheck "Auto-save edited files to trigger the watcher" in Advanced Options
 
@@ -236,5 +258,3 @@ With pre-commit
 .. _rstfmt: https://github.com/dzhu/rstfmt
 
 .. _rustfmt: https://github.com/rust-lang/rustfmt
-
-

{docstrfmt-1.5.1.dev0 → docstrfmt-1.6.0}/README.rst

@@ -135,7 +135,7 @@ Instructions derived from `black documentation
 
     Note that if you are using a virtual environment detected by PyCharm, this is an
     unneeded step. In this case the path to `docstrfmt` is
-    `$PyInterpreterDirectory$/docstrfmt`.
+    ``$PyInterpreterDirectory$/docstrfmt``.
 
 3. Open External tools in PyCharm.
 
@@ -152,7 +152,7 @@ Instructions derived from `black documentation
    - Name: docstrfmt
    - Description:
    - Program: <install_location_from_step_2>
-   - Arguments: `"$FilePath$"`
+   - Arguments: ``"$FilePath$"``
 
 5. Format the currently opened file by selecting `Tools -> External Tools -> docstrfmt`.
 
@@ -170,9 +170,9 @@ Instructions derived from `black documentation
       - File type: Python
       - Scope: Project Files
       - Program: <install_location_from_step_2>
-      - Arguments: `$FilePath$`
-      - Output paths to refresh: `$FilePath$`
-      - Working directory: `$ProjectFileDir$`
+      - Arguments: ``$FilePath$``
+      - Output paths to refresh: ``$FilePath$``
+      - Working directory: ``$ProjectFileDir$``
 
    3. Uncheck "Auto-save edited files to trigger the watcher" in Advanced Options
 

docstrfmt-1.6.0/docstrfmt/const.py

@@ -0,0 +1,2 @@
+# pragma: no cover
+__version__ = "1.6.0"

{docstrfmt-1.5.1.dev0 → docstrfmt-1.6.0}/docstrfmt/debug.py

@@ -16,5 +16,5 @@ def _dump_lines(node: docutils.nodes.Node) -> Iterator[Tuple[int, str]]:
         body = str({k: v for k, v in node.attributes.items() if v})
     yield 0, f"{head} {body}"
     for c in node.children:
-        for n, l in _dump_lines(c):
-            yield n + 1, l
+        for n, line in _dump_lines(c):
+            yield n + 1, line

{docstrfmt-1.5.1.dev0 → docstrfmt-1.6.0}/docstrfmt/docstrfmt.py

@@ -126,14 +126,12 @@ class CodeFormatters:
                 compile(code, context.current_file, mode="exec")
             except SyntaxError as syntax_error:
                 context.manager.error_count += 1
-                with open(context.current_file, encoding="utf-8") as f:
-                    source = f.read()
-                current_line = get_code_line(source, code)
+                current_line = get_code_line(context.current_file, code, strict=True)
                 if context.manager.reporter:
                     context.manager.reporter.error(
                         f"SyntaxError: {syntax_error.msg}:\n\nFile"
                         f' "{context.current_file}", line'
-                        f' {current_line}:\n{syntax_error.text}{" " * (syntax_error.offset-1)}^'
+                        f' {current_line}:\n{syntax_error.text}{" " * (syntax_error.offset - 1)}^'
                     )
         return code
 
@@ -422,8 +420,8 @@ class Formatters:
             sub_doc = self.manager.parse_string(
                 context.current_file, "\n".join(directive.content)
             )
-            if sub_doc.children:  # pragma: no cover
-                yield ""  # no idea how to cover this
+            if sub_doc.children:
+                yield ""
                 yield from self._with_spaces(
                     4, self.manager.perform_format(sub_doc, context.indent(4))
                 )
@@ -456,20 +454,19 @@ class Formatters:
         try:
             first_line = next(children)
         except StopIteration:
-            with open(context.current_file, encoding="utf-8") as f:
-                source = f.read()
-            line = get_code_line(source, f":{node.astext().strip()}:")
             raise InvalidRstError(
                 context.current_file,
                 "ERROR",
-                line,
+                get_code_line(
+                    context.current_file, f":{node.astext().strip()}:", strict=True
+                ),
                 f"Empty `:{node.astext().strip()}:` field. Please add a field body or"
-                " omit completely",
+                " omit completely.",
             )
         children = list(children)
         children_processed = []
         for i, child in enumerate(children):
-            if child.startswith(("..",)):
+            if child.startswith(".."):
                 blocks_in_child = [child]
                 for block in children[i + 1 :]:
                     if block.startswith("    "):
@@ -485,11 +482,6 @@ class Formatters:
             else:
                 children_processed.append(child)
         children = children_processed
-        if field_name in [":raises:", ":returns:"]:
-            if node.parent.index(node):
-                previous = node.parent.children[node.parent.children.index(node) - 1]
-                if previous.tagname == "field":
-                    yield ""
         yield f"{field_name} {first_line}"
         yield from self._with_spaces(4, children)
 
@@ -505,16 +497,119 @@ class Formatters:
         )
 
     def field_list(self, node: docutils.nodes.field_list, context) -> line_iterator:
-        yield from chain(self._format_children(node, context))
+        param_types = {}
+        param_fields = []
+        returns_fields = []
+        rtype_fields = []
+        raises_fields = []
+        other_fields = []
+        field_types_mapping = {
+            "param": param_fields,
+            "arg": param_fields,
+            "argument": param_fields,
+            "return": returns_fields,
+            "returns": returns_fields,
+            "rtype": rtype_fields,
+            "raise": raises_fields,
+            "raises": raises_fields,
+        }
+        already_typed = []
+        children = node.children
+        for child in children[:]:
+            field_body = child.children[0].children[0]
+            field_typing = None
+            try:
+                field_kind, *field_typing, field_name = field_body.split(" ")
+            except ValueError:
+                field_name = None
+                field_kind = field_body
+            child.children[0].setdefault("name", field_name)
+            if field_kind == "type":
+                field_type = child.children[1].children[0].astext()
+                if "\n" in field_type:
+                    raise InvalidRstError(
+                        context.current_file,
+                        "ERROR",
+                        get_code_line(context.current_file, field_type),
+                        "Multi-line type hints are not supported.",
+                    )
+                param_types[field_name] = field_type
+                node.remove(child)
+                continue
+            if field_typing:
+                already_typed.append(field_name)
+            if field_kind in field_types_mapping:
+                if field_kind.startswith("return") and returns_fields:
+                    raise InvalidRstError(
+                        context.current_file,
+                        "ERROR",
+                        get_code_line(context.current_file, child.astext()),
+                        "Multiple `:return:` fields are not allowed. Please"
+                        " combine them into one.",
+                    )
+                field_types_mapping[field_kind].append(child)
+            else:
+                other_fields.append(child)
+        for field in param_fields:
+            field_name = field.children[0].get("name")
+            if field_name in already_typed and field_name in param_types:
+                raise InvalidRstError(
+                    context.current_file,
+                    "ERROR",
+                    get_code_line(context.current_file, field.astext()),
+                    "Type hint is specified both in the field body and in the"
+                    " `:type:` field. Please remove one of them.",
+                )
+            else:
+                field_typing = param_types.get(field_name, None)
+                if field_typing:
+                    field.children[0].replace_self(
+                        docutils.nodes.field_name(
+                            "", f"param {field_typing} {field_name}"
+                        )
+                    )
+        yield from chain(
+            self.manager.perform_format(child, context) for child in param_fields
+        )
+        yield from self._prepend_if_any(
+            "",
+            chain(
+                self.manager.perform_format(child, context)
+                for child in returns_fields + rtype_fields
+            ),
+        )
+        yield from self._prepend_if_any(
+            "",
+            chain(
+                self.manager.perform_format(child, context) for child in raises_fields
+            ),
+        )
+        if (
+            other_fields
+            and param_fields + returns_fields + rtype_fields + raises_fields
+        ):
+            yield ""
+        yield from chain(
+            self.manager.perform_format(child, context) for child in other_fields
+        )
 
     def field_name(self, node: docutils.nodes.field_name, context) -> line_iterator:
         text = " ".join(chain(self._format_children(node, context)))
-        if text.startswith(("raise", "raises")):
-            yield ":raises:"
-        elif text.startswith(("return", "returns")):
-            yield ":returns:"
-        else:
-            yield f":{text}:"
+        body = ":"
+        field_kinds = [
+            ("param", "arg"),
+            "raise",
+            "return",
+        ]
+        for field_kind in field_kinds:
+            if text.startswith(field_kind):
+                field_kind, *_ = text.split(" ", maxsplit=1)
+                body += field_kind
+                text = text[len(field_kind) :]
+                break
+        body += text
+        body += ":"
+        yield body
 
     def footnote(self, node: docutils.nodes.footnote_reference, context):
         prefix = ".."
@@ -545,7 +640,7 @@ class Formatters:
 
         indent = 4 * context.line_block_depth
         context = context.indent(indent)
-        prefix1 = "|" + " " * (indent - 1)
+        prefix1 = f"|{' ' * (indent - 1)}"
         prefix2 = " " * indent
         for first, line in self._enum_first(
             self._wrap_text(
@@ -568,7 +663,7 @@ class Formatters:
                 )
                 context.current_ordinal += 1
         width = len(context.bullet) + 1
-        bullet = context.bullet + " "
+        bullet = f"{context.bullet} "
         spaces = " " * width
         context = context.indent(width)
         context.bullet = ""
@@ -658,40 +753,42 @@ class Formatters:
             yield inline_markup(title + anonymous_suffix(anonymous))
             return
 
-        # Handle references to external URIs. They can be either standalone hyperlinks, written as
-        # just the URI, or an explicit "`text <url>`_" or "`text <url>`__".
+        # Handle references to external URIs. They can be either standalone hyperlinks,
+        # written as just the URI, or an explicit "`text <url>`_" or "`text <url>`__".
         if "refuri" in attributes:
             uri = attributes["refuri"]
-            if uri == title or uri == "mailto:" + title:
+            if uri == title or uri == f"mailto:{title}":
                 yield inline_markup(title)
             else:
                 anonymous = "target" not in attributes
                 yield inline_markup(f"`{title} <{uri}>`{anonymous_suffix(anonymous)}")
             return
 
-        # Simple reference names can consist of "alphanumerics plus isolated (no two adjacent)
-        # internal hyphens, underscores, periods, colons and plus signs", according to
+        # Simple reference names can consist of "alphanumerics plus isolated (no two
+        # adjacent) internal hyphens, underscores, periods, colons and plus signs",
+        # according to
         # https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#reference-names.
         is_single_word = re.match("^[-_.:+a-zA-Z0-9]+$", title) and not re.search(
             "[-_.:+][-_.:+]", title
         )
 
-        # "x__" is one of the few cases to trigger an explicit "anonymous" attribute (the other
-        # being the similar "|x|__", which is already handled above).
+        # "x__" is one of the few cases to trigger an explicit "anonymous" attribute
+        # (the other being the similar "|x|__", which is already handled above).
         if "anonymous" in attributes:
             if not is_single_word:
-                title = "`" + title + "`"
+                title = f"`{title}`"
             yield inline_markup(title + anonymous_suffix(True))
             return
 
         anonymous = "target" not in attributes
         ref = attributes["refname"]
-        # Check whether the reference name matches the text and can be made implicit. (Reference
-        # names are case-insensitive.)
+        # Check whether the reference name matches the text and can be made implicit.
+        # (Reference names are case-insensitive.)
         if anonymous and ref.lower() == title.lower():
             if not is_single_word:
-                title = "`" + title + "`"
-            # "x_" is equivalent to "`x <x_>`__"; it's anonymous despite having a single underscore.
+                title = f"`{title}`"
+            # "x_" is equivalent to "`x <x_>`__"; it's anonymous despite having a single
+            # underscore.
             yield inline_markup(title + anonymous_suffix(False))
         else:
             yield inline_markup(f"`{title} <{ref}_>`{anonymous_suffix(anonymous)}")
@@ -748,9 +845,9 @@ class Formatters:
 
     def table(self, node: docutils.nodes.table, context) -> line_iterator:
         rows = []
-        for row in node.traverse(docutils.nodes.row):
+        for row in node.findall(docutils.nodes.row):
             current_row = []
-            for column in row.traverse(docutils.nodes.entry):
+            for column in row.findall(docutils.nodes.entry):
                 if column.attributes.get("morerows", False) or column.attributes.get(
                     "morecols", False
                 ):
@@ -779,7 +876,7 @@ class Formatters:
             final_widths = [
                 max(
                     self._generate_table_matrix(context, rows, None, max_col_len),
-                    key=lambda l: l[i],
+                    key=lambda lengths: lengths[i],
                 )[i]
                 for i in range(column_count)
             ]
@@ -811,7 +908,7 @@ class Formatters:
             final_widths = [
                 max(
                     self._generate_table_matrix(context, rows, None, column_lengths),
-                    key=lambda l: l[i],
+                    key=lambda lengths: lengths[i],
                 )[i]
                 for i in range(column_count)
             ]
@@ -831,7 +928,11 @@ class Formatters:
         try:
             body = f" {node.attributes['refuri']}"
         except KeyError:
-            body = ""
+            body = (
+                f" {node.attributes['refname']}_"
+                if "refname" in node.attributes
+                else ""
+            )
 
         name = "_" if node.attributes.get("anonymous") else node.attributes["names"][0]
         yield f".. _{name}:{body}"
@@ -922,7 +1023,13 @@ class Manager:
         self.docstring_trailing_line = docstring_trailing_line
 
     def _pre_process(self, node: docutils.nodes.Node, source: str) -> None:
-        """Do some node preprocessing that is generic across node types and is therefore most convenient to do as a simple recursive function rather than as part of the big dispatcher class."""
+        """Preprocess nodes.
+
+        This does some preprocessing to all nodes that is generic across node types and
+        is therefore most convenient to do as a simple recursive function rather than as
+        part of the big dispatcher class.
+
+        """
         # Strip all system_message nodes. (Just formatting them with no markup isn't enough, since that
         # could lead to extra spaces or empty lines between other elements.)
         errors = [
@@ -975,21 +1082,19 @@ class Manager:
             self._pre_process(child, source)
 
     def format_node(self, width, node: docutils.nodes.Node, is_docstring=False) -> str:
-        return (
-            "\n".join(
-                self.perform_format(
-                    node,
-                    FormatContext(
-                        width,
-                        current_file=self.current_file,
-                        manager=self,
-                        black_config=self.black_config,
-                        is_docstring=is_docstring,
-                    ),
-                )
+        formatted_node = "\n".join(
+            self.perform_format(
+                node,
+                FormatContext(
+                    width,
+                    current_file=self.current_file,
+                    manager=self,
+                    black_config=self.black_config,
+                    is_docstring=is_docstring,
+                ),
             )
-            + "\n"
         )
+        return f"{formatted_node}\n"
 
     def parse_string(self, file_name: str, text: str) -> docutils.nodes.document:
         self.current_file = file_name