unvendor docstring_parser

Author: RobertBlackhart

.coveragerc

@@ -1,6 +1,3 @@
 [run]
 branch = true
-omit =
-    # don't measure our vendored packages
-    */vendor/*
 

.github/workflows/on_pull_request.yml

@@ -31,4 +31,4 @@ jobs:
         env:
           REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          poetry run pylint -j 0 --ignore=vendor recline | reviewdog -reporter=github-pr-check -diff="git diff main" -efm="%f:%l:%c: %m"
+          poetry run pylint -j 0 recline | reviewdog -reporter=github-pr-check -diff="git diff main" -efm="%f:%l:%c: %m"

CONTRIBUTING.md

@@ -34,6 +34,11 @@ $ poetry run python examples/cake.py
 $ poetry run pytest --cov=recline tests
 ```
 
+### Running the linter
+```
+$ poetry run ruff check
+```
+
 ### Building the package
 
 ```

recline/vendor/__init__.py docs/_static/.gitkeeprecline/vendor/__init__.py renamed to docs/_static/.gitkeep

@@ -39,7 +39,6 @@
 
 apidoc_module_dir = '../recline'
 apidoc_output_dir = 'api_reference'
-apidoc_excluded_paths = ['vendor']
 apidoc_separate_modules = True
 apidoc_extra_args = ["-H", "API Reference"]
 

docs/conf.py

@@ -22,6 +22,7 @@ packages = [
 
 [tool.poetry.dependencies]
 argcomplete = ">=3"
+docstring_parser = ">=0.16"
 python = ">=3.10.0,<4"
 windows-curses = {version = "^2.3.3", markers = "sys_platform == 'win32'"}
 pyreadline3 = {version = "^3.4.1", markers = "sys_platform == 'win32'"}
@@ -40,6 +41,4 @@ importlib-metadata = "^9.0.0"
 requires = ["poetry-core>=2.0.0,<3.0.0"]
 build-backend = "poetry.core.masonry.api"
 
-[tool.ruff]
-exclude = ["recline/vendor"]
 

poetry.lock

@@ -4,12 +4,12 @@
 This package contains the various custom type definitions for CLI command parameters.
 If you are defining a CLI command function that takes input with restrictions,
 you may want to use a type annotation to allow recline to do the checking for you
-before your function ever gets invoked. For example:
+before your function ever gets invoked. For example::
 
-from recline.arg_types import Choices
+    from recline.arg_types import Choices
 
-@recline.command
-def commit(branch: Choices.define(['dev', 'beta', 'stable'])) -> None:
-    # the function can now assume that branch has already been validated to be
-    # one of the options above before we got here
+    @recline.command
+    def commit(branch: Choices.define(['dev', 'beta', 'stable'])) -> None:
+        # the function can now assume that branch has already been validated to be
+        # one of the options above before we got here
 """

pyproject.toml

@@ -21,7 +21,7 @@
 from recline.arg_types.flag import Flag
 from recline.arg_types.remainder import Remainder
 from recline.formatters.output_formatter import OutputFormatter
-from recline.vendor import docstring_parser
+import docstring_parser
 
 
 LOGGER = logging.getLogger(__name__)

recline/arg_types/__init__.py

@@ -8,11 +8,45 @@
 
 import curses
 
+from docstring_parser.common import DocstringExample
+
 from recline.arg_types.positional import Positional
 from recline.arg_types.remainder import Remainder
 from recline.commands.cli_command import get_annotation_type
 
 
+def _iter_examples(docstring):
+    """Yield (name, description) tuples from a parsed docstring.
+
+    Handles two input forms:
+    - ``DocstringExample`` objects (google-style ``Examples:`` blocks), whose
+      ``description`` field contains lines like ``name:`` followed by indented
+      body lines.
+    - Generic ``DocstringMeta`` entries with ``args[0]`` in ``{"example",
+      "examples"}`` and the example name in ``args[1]`` (rest-style ``:example
+      name:`` entries).
+    """
+
+    for meta in docstring.meta:
+        if isinstance(meta, DocstringExample):
+            name = None
+            body_lines = []
+            for line in (meta.description or '').splitlines():
+                stripped = line.rstrip()
+                if stripped and not line[:1].isspace() and stripped.endswith(':'):
+                    if name is not None:
+                        yield name, '\n'.join(body_lines).strip('\n')
+                    name = stripped[:-1]
+                    body_lines = []
+                else:
+                    dedented = line[4:] if line.startswith('    ') else line
+                    body_lines.append(dedented)
+            if name is not None:
+                yield name, '\n'.join(body_lines).strip('\n')
+        elif meta.args and meta.args[0] in {'example', 'examples'} and len(meta.args) > 1:
+            yield meta.args[1], meta.description or ''
+
+
 def wrapped_string(text, screen_width, prefix=0):
     """This function will take a string and make sure it can fit within the
     given screen_width.
@@ -111,7 +145,7 @@ def generate_help_text(screen_width, command_class):
         help_text.append(('\n',))
 
     # each command parameter with description, constraints, and defaults
-    if command_class.docstring.params:
+    if command_class.required_args or command_class.optional_args:
         def print_arg(arg):
             meta = command_class.get_arg_metavar(arg)
             description = command_class.get_arg_description(arg, indent=None)
@@ -139,15 +173,16 @@ def print_arg(arg):
             print_arg(arg)
 
     # each command example
-    if command_class.docstring.examples:
+    examples = list(_iter_examples(command_class.docstring))
+    if examples:
         help_text.append(('EXAMPLES\n', curses.A_BOLD))
-        for example in command_class.docstring.examples:
+        for name, description in examples:
             prefix = indent + '  '
             help_text.append((indent,))
-            help_text.append((f'{example.name}:', curses.A_UNDERLINE))
+            help_text.append((f'{name}:', curses.A_UNDERLINE))
             help_text.append((f'\n{prefix}',))
             description = wrapped_string(
-                example.description, screen_width, prefix=len(prefix),
+                description, screen_width, prefix=len(prefix),
             )
             for line in description.split('\n'):
                 help_text.append((f'{line}\n',))