`--docstrings` option for returning signatures with docstrings

[simonw]

Can use ast.get_docstring(node) for this.

I'd like to show these as double quoted or triple-double-quoted strings.

[simonw]

Some ChatGPT research: https://chat.openai.com/share/f9b4f1d0-cedb-4576-a145-ad3eac345d27

Which helped me by writing this:

def convert_to_quoted(s):
    # Check if the string spans multiple lines
    if "\n" in s:
        # Escape triple double quotes
        s = s.replace('"""', '\\"\\"\\"')
        # Now wrap the whole string into triple double quotes
        return f'"""{s}"""'
    else:
        # Escape double quotes
        s = s.replace('"', '\\"')
        # Now wrap the whole string into double quotes
        return f'"{s}"'

[simonw]

Slight point of confusion: --docstrings causes the docstrings to be displayed, but it shows functions without docsstrings too.

It might be expected to act as a filter, showing only functions with docstrings - for consistency with --function and --class and --async and --untyped and so-on.

Now that I'm trying it out I find myself wanting a way to see "all functions with docstrings" and "all functions without docstrings".

I could do --documented and --undocumented for that.

[simonw]

git diff | llm --system 'describe this change' -m 3.5-16k

The diff command shows the changes made to the files README.md, symbex/cli.py, and symbex/lib.py. Here are the highlights of the changes:

In README.md:

• Added two new filtering options: --documented and --undocumented.
• Updated the description of the --signatures option to mention the new --docstrings option.
• Added an example command to include docstrings in function/class signatures.

In symbex/cli.py:

• Added a new --docstrings option as a flag.
• Added documented and undocumented as options to the cli function's signature.
• Updated the logic to handle the --docstrings option.
• Updated the filter function to filter based on documentation presence.
• Added an add_docstring function to add docstrings to function/class definitions.

In symbex/lib.py:

• Added the add_docstring function to add docstrings to function/class definitions.
• Updated the code_for_node function to use add_docstring.
• Added a new quoted_string function to escape quotes in docstrings.

In the tests:

• Added new tests to verify the --documented and --undocumented filters.
• Added a new test to verify the --docstrings option and the inclusion of docstrings in the output.

Overall, these changes enhance the functionality of the symbex tool by providing options to filter based on the presence or absence of docstrings and include docstrings in the function/class signatures.

[simonw]

Documentation at bottom of https://github.com/simonw/symbex/blob/495c377802b4b135ee219601d77a4e525014a4c9/README.md#just-the-signatures

[simonw]

Example:

symbex --docstrings --documented -f symbex/lib.py

# File: symbex/lib.py Line: 12
def find_symbol_nodes(code: str, filename: str, symbols: Iterable[str]) -> List[Tuple[(AST, Optional[str])]]
    "Returns ast Nodes matching symbols"

# File: symbex/lib.py Line: 36
def code_for_node(code: str, node: AST, class_name: str, signatures: bool, docstrings: bool) -> Tuple[(str, int)]
    "Returns the code for a given node"

# File: symbex/lib.py Line: 80
def match(name: str, symbols: Iterable[str]) -> bool
    "Returns True if name matches any of the symbols, resolving wildcards"