symbex 0.2__py3-none-any.whl → 0.3__py3-none-any.whl

symbex/cli.py

@@ -8,7 +8,12 @@ from .lib import code_for_node, find_symbol_nodes
 @click.version_option()
 @click.argument("symbols", nargs=-1)
 @click.option(
-    "files", "-f", "--file", type=click.File("r"), multiple=True, help="Files to search"
+    "files",
+    "-f",
+    "--file",
+    type=click.Path(file_okay=True, dir_okay=False),
+    multiple=True,
+    help="Files to search",
 )
 @click.option(
     "directories",
@@ -18,7 +23,18 @@ from .lib import code_for_node, find_symbol_nodes
     multiple=True,
     help="Directories to search",
 )
-def cli(symbols, files, directories):
+@click.option(
+    "-s",
+    "--signatures",
+    is_flag=True,
+    help="Show just function and class signatures",
+)
+@click.option(
+    "--silent",
+    is_flag=True,
+    help="Silently ignore Python files with parse errors",
+)
+def cli(symbols, files, directories, signatures, silent):
     """
     Find symbols in Python code and print the code for them.
 
@@ -30,6 +46,15 @@ def cli(symbols, files, directories):
     \b
         # Search using a wildcard
         symbex 'test_*'
+
+    \b
+        # Find a specific class method
+        symbex 'MyClass.my_method'
+
+    \b
+        # Find class methods using wildcards
+        symbex '*View.handle_*'
+
     \b
         # Search a specific file
         symbex MyClass -f my_file.py
@@ -37,24 +62,42 @@ def cli(symbols, files, directories):
         # Search within a specific directory and its subdirectories
         symbex Database -d ~/projects/datasette
 
+    \b
+        # View signatures for all symbols in current directory and subdirectories
+        symbex -s
+
+    \b
+        # View signatures for all test functions
+        symbex 'test_*' -s
     """
+    if signatures and not symbols:
+        symbols = ["*"]
     if not files and not directories:
         directories = ["."]
-    files = list(files)
+    files = [pathlib.Path(f) for f in files]
     for directory in directories:
         files.extend(pathlib.Path(directory).rglob("*.py"))
     pwd = pathlib.Path(".").resolve()
     for file in files:
         code = file.read_text("utf-8") if hasattr(file, "read_text") else file.read()
-        nodes = find_symbol_nodes(code, symbols)
-        for node in nodes:
+        try:
+            nodes = find_symbol_nodes(code, symbols)
+        except SyntaxError as ex:
+            if not silent:
+                click.secho(f"# Syntax error in {file}: {ex}", err=True, fg="yellow")
+            continue
+        for node, class_name in nodes:
             # If file is within pwd, print relative path
             # else print absolute path
             if pwd in file.resolve().parents:
                 path = file.resolve().relative_to(pwd)
             else:
                 path = file.resolve()
-            snippet, line_no = code_for_node(code, node)
-            print("# File:", path, "Line:", line_no)
+            snippet, line_no = code_for_node(code, node, class_name, signatures)
+            bits = ["# File:", path]
+            if class_name:
+                bits.extend(["Class:", class_name])
+            bits.extend(["Line:", line_no])
+            print(*bits)
             print(snippet)
             print()

symbex/lib.py

@@ -1,41 +1,181 @@
 import fnmatch
-from ast import parse, AST
-from typing import Iterable, Tuple
+from ast import literal_eval, parse, AST, FunctionDef, ClassDef
+from itertools import zip_longest
+import textwrap
+from typing import Iterable, List, Optional, Tuple
 
 
-def find_symbol_nodes(code: str, symbols: Iterable[str]) -> Iterable[AST]:
+def find_symbol_nodes(
+    code: str, symbols: Iterable[str]
+) -> List[Tuple[AST, Optional[str]]]:
     "Returns ast Nodes matching symbols"
+    # list of (AST, None-or-class-name)
     matches = []
     module = parse(code)
     for node in module.body:
+        if not isinstance(node, (ClassDef, FunctionDef)):
+            continue
         name = getattr(node, "name", None)
         if match(name, symbols):
-            matches.append(node)
+            matches.append((node, None))
+        # If it's a class search its methods too
+        if isinstance(node, ClassDef):
+            for child in node.body:
+                if isinstance(child, FunctionDef):
+                    qualified_name = f"{name}.{child.name}"
+                    if match(qualified_name, symbols):
+                        matches.append((child, name))
+
     return matches
 
 
-def code_for_node(code: str, node: AST) -> Tuple[str, int]:
+def code_for_node(
+    code: str, node: AST, class_name: str, signatures: bool
+) -> Tuple[str, int]:
     "Returns the code for a given node"
     lines = code.split("\n")
-    # If the node has decorator_list, include those too
-    if getattr(node, "decorator_list", None):
-        start = node.decorator_list[0].lineno - 1
+    start = None
+    end = None
+    if signatures:
+        if isinstance(node, FunctionDef):
+            definition, lineno = function_definition(node), node.lineno
+            if class_name:
+                definition = "    " + definition
+            return definition, lineno
+        elif isinstance(node, ClassDef):
+            return class_definition(node), node.lineno
+        else:
+            # Not a function or class, fall back on just the line
+            start = node.lineno - 1
+            end = node.lineno
     else:
-        start = node.lineno - 1
-    end = node.end_lineno
-    return "\n".join(lines[start:end]), start + 1
+        # If the node has decorator_list, include those too
+        if getattr(node, "decorator_list", None):
+            start = node.decorator_list[0].lineno - 1
+        else:
+            start = node.lineno - 1
+        end = node.end_lineno
+    output = "\n".join(lines[start:end])
+    # If it's in a class, indent it 4 spaces
+    return output, start + 1
 
 
 def match(name: str, symbols: Iterable[str]) -> bool:
     "Returns True if name matches any of the symbols, resolving wildcards"
     if name is None:
         return False
-    for symbol in symbols:
-        if "*" not in symbol:
-            if name == symbol:
+    for search in symbols:
+        if "*" not in search:
+            # Exact matches only
+            if name == search:
                 return True
+        elif search.count(".") == 1:
+            # wildcards are supported either side of the dot
+            if "." in name:
+                class_match, method_match = search.split(".")
+                class_name, method_name = name.split(".")
+                if fnmatch.fnmatch(class_name, class_match) and fnmatch.fnmatch(
+                    method_name, method_match
+                ):
+                    return True
         else:
-            if fnmatch.fnmatch(name, symbol):
+            if fnmatch.fnmatch(name, search) and "." not in name:
                 return True
 
     return False
+
+
+def function_definition(function_node: AST):
+    function_name = function_node.name
+
+    all_args = [
+        *function_node.args.posonlyargs,
+        *function_node.args.args,
+        *function_node.args.kwonlyargs,
+    ]
+
+    # For position only args like "def foo(a, /, b, c)"
+    # we can look at the length of args.posonlyargs to see
+    # if any are set and, if so, at what index the `/` should go
+    position_of_slash = len(function_node.args.posonlyargs)
+
+    # For func_keyword_only_args(a, *, b, c) the length of
+    # the kwonlyargs tells us how many spaces back from the
+    # end the star should be displayed
+    position_of_star = len(all_args) - len(function_node.args.kwonlyargs)
+
+    # function_node.args.defaults may have defaults
+    # corresponding to function_node.args.args - but
+    # if defaults has 2 and args has 3 then those
+    # defaults correspond to the last two args
+    defaults = [None] * (len(all_args) - len(function_node.args.defaults))
+    defaults.extend(literal_eval(default) for default in function_node.args.defaults)
+
+    arguments = []
+
+    for i, (arg, default) in enumerate(zip_longest(all_args, defaults)):
+        if position_of_slash and i == position_of_slash:
+            arguments.append("/")
+        if position_of_star and i == position_of_star:
+            arguments.append("*")
+        if getattr(arg.annotation, "id", None):
+            arg_str = f"{arg.arg}: {arg.annotation.id}"
+        else:
+            arg_str = arg.arg
+
+        if default:
+            arg_str = f"{arg_str}={default}"
+
+        arguments.append(arg_str)
+
+    if function_node.args.vararg:
+        arguments.append(f"*{function_node.args.vararg.arg}")
+
+    if function_node.args.kwarg:
+        arguments.append(f"**{function_node.args.kwarg.arg}")
+
+    arguments_str = ", ".join(arguments)
+
+    return_annotation = ""
+    if function_node.returns:
+        if hasattr(function_node.returns, "id"):
+            return_annotation = f" -> {function_node.returns.id}"
+        elif function_node.returns.value is None:
+            # None shows as returns.value is None
+            return_annotation = " -> None"
+
+    return f"def {function_name}({arguments_str}){return_annotation}"
+
+
+def class_definition(class_def):
+    # Base classes
+    base_classes = []
+    for base in class_def.bases:
+        if getattr(base, "id", None):
+            base_classes.append(base.id)
+    base_classes_str = ", ".join(base_classes)
+
+    # Keywords (including metaclass)
+    keywords = {k.arg: getattr(k.value, "id", str(k.value)) for k in class_def.keywords}
+    metaclass = keywords.pop("metaclass", None)
+    keyword_str = ", ".join([f"{k}=..." for k in keywords])
+
+    if base_classes_str and keyword_str:
+        signature = f"{base_classes_str}, {keyword_str}"
+    elif base_classes_str:
+        signature = base_classes_str
+    elif keyword_str:
+        signature = keyword_str
+    else:
+        signature = ""
+
+    if metaclass:
+        sep = ", " if signature else ""
+        signature = f"{signature}{sep}metaclass={metaclass}"
+
+    if signature:
+        signature = f"({signature})"
+
+    class_definition = f"class {class_def.name}{signature}"
+
+    return class_definition

{symbex-0.2.dist-info → symbex-0.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: symbex
-Version: 0.2
+Version: 0.3
 Summary: Find the Python code for specified symbols
 Home-page: https://github.com/simonw/symbex
 Author: Simon Willison
@@ -15,6 +15,7 @@ Requires-Dist: click
 Provides-Extra: test
 Requires-Dist: pytest ; extra == 'test'
 Requires-Dist: pytest-icdiff ; extra == 'test'
+Requires-Dist: cogapp ; extra == 'test'
 
 # symbex
 
@@ -48,6 +49,20 @@ Wildcards are supported - to search for every `test_` function run this (note th
 ```bash
 symbex 'test_*'
 ```
+To search for methods within classes, use `class.method` notation:
+```bash
+symbex Entry.get_absolute_url
+```
+Wildcards are supported here as well:
+```bash
+symbex 'Entry.*'
+symbex '*.get_absolute_url'
+symbex '*.get_*'
+```
+Or to view every method of every class:
+```bash
+symbex '*.*'
+```
 To search within a specific file, pass that file using the `-f` option. You can pass this more than once to search multiple files.
 
 ```bash
@@ -57,8 +72,15 @@ To search within a specific directory and all of its subdirectories, use the `-d
 ```bash
 symbex Database -d ~/projects/datasette
 ```
-
-## Example output
+If `symbex` encounters any Python code that it cannot parse, it will print a warning message and continue searching:
+```
+# Syntax error in path/badcode.py: expected ':' (<unknown>, line 1)
+```
+Pass `--silent` to suppress these warnings:
+```bash
+symbex MyClass --silent
+```
+### Example output
 
 In a fresh checkout of [Datasette](https://github.com/simonw/datasette) I ran this command:
 
@@ -87,6 +109,50 @@ class PatternPortfolioView(View):
             )
         )
 ```
+### Just the signatures
+
+The `-s/--signatures` option will list just the signatures of the functions and classes, for example:
+```bash
+symbex -s -d symbex
+```
+
+<!-- [[[cog
+import cog
+from click.testing import CliRunner
+import pathlib
+from symbex.cli import cli
+
+path = pathlib.Path("symbex").resolve()
+runner = CliRunner()
+result = runner.invoke(cli, ["-s", "-d", str(path)])
+# Need a consistent sort order
+chunks = result.stdout.strip().split("\n\n")
+chunks.sort()
+cog.out(
+    "```\n{}\n```\n".format("\n\n".join(chunks))
+)
+]]] -->
+```
+# File: symbex/cli.py Line: 37
+def cli(symbols, files, directories, signatures, silent)
+
+# File: symbex/lib.py Line: 150
+def class_definition(class_def)
+
+# File: symbex/lib.py Line: 32
+def code_for_node(code: str, node: AST, class_name: str, signatures: bool)
+
+# File: symbex/lib.py Line: 63
+def match(name: str, symbols) -> bool
+
+# File: symbex/lib.py Line: 8
+def find_symbol_nodes(code: str, symbols)
+
+# File: symbex/lib.py Line: 88
+def function_definition(function_node: AST)
+```
+<!-- [[[end]]] -->
+This can be combined with other options, or you can run `symbex -s` to see every symbol in the current directory and its subdirectories.
 
 ## Using with LLM
 

symbex-0.3.dist-info/RECORD

@@ -0,0 +1,10 @@
+symbex/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+symbex/__main__.py,sha256=8hDtWlaFZK24KhfNq_ZKgtXqYHsDQDetukOCMlsbW0Q,59
+symbex/cli.py,sha256=tWzT49q-fPN34HQH2sEFHBV3MXFKy9J5eh2EzOo5_CA,2857
+symbex/lib.py,sha256=q8WhjbPLiXuGnbD3scwCvJrqVvs-RHAMbBEXIYyFqeI,6121
+symbex-0.3.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+symbex-0.3.dist-info/METADATA,sha256=Yn6vp7j1nWfTn_GYWXmeWhD7NFXHw2OxI3YnpMRVvew,5693
+symbex-0.3.dist-info/WHEEL,sha256=pkctZYzUS4AYVn6dJ-7367OJZivF2e8RA9b_ZBjif18,92
+symbex-0.3.dist-info/entry_points.txt,sha256=YgMSEfEGqNMHM9RysFObH8lkQKVZKyymKLnXbVue_Uk,42
+symbex-0.3.dist-info/top_level.txt,sha256=qwle8HjAaYgpdMIHlJcTcN4gaG4wmDqUvkt54beTBTs,7
+symbex-0.3.dist-info/RECORD,,

symbex-0.2.dist-info/RECORD

@@ -1,10 +0,0 @@
-symbex/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-symbex/__main__.py,sha256=8hDtWlaFZK24KhfNq_ZKgtXqYHsDQDetukOCMlsbW0Q,59
-symbex/cli.py,sha256=tJhsnbWEiIN9LSZGGcqrmpY5U9TgISvknXsMCpijlSs,1770
-symbex/lib.py,sha256=1YViD5fJ_NP1Y32LTFM7o8UCTzUiz3yTldVvJb8owgs,1190
-symbex-0.2.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-symbex-0.2.dist-info/METADATA,sha256=QMsejWdFVPSvRODCyd09SRl_mcH0dLvXk3tOX2GNbts,3917
-symbex-0.2.dist-info/WHEEL,sha256=pkctZYzUS4AYVn6dJ-7367OJZivF2e8RA9b_ZBjif18,92
-symbex-0.2.dist-info/entry_points.txt,sha256=YgMSEfEGqNMHM9RysFObH8lkQKVZKyymKLnXbVue_Uk,42
-symbex-0.2.dist-info/top_level.txt,sha256=qwle8HjAaYgpdMIHlJcTcN4gaG4wmDqUvkt54beTBTs,7
-symbex-0.2.dist-info/RECORD,,