symbex 0.4

Find the Python code for specified symbols

symbex

Find the Python code for specified symbols

Installation

Install this tool using pip:

pip install symbex

Usage

symbex can search for names of functions and classes that occur at the top level of a Python file.

To search every .py file in your current directory and all subdirectories, run like this:

symbex my_function

You can search for more than one symbol at a time:

symbex my_function MyClass

Wildcards are supported - to search for every test_ function run this (note the single quotes to avoid the shell interpreting the * as a wildcard):

symbex 'test_*'

To search for methods within classes, use class.method notation:

symbex Entry.get_absolute_url

Wildcards are supported here as well:

symbex 'Entry.*'
symbex '*.get_absolute_url'
symbex '*.get_*'

Or to view every method of every class:

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.

symbex MyClass -f my_file.py

To search within a specific directory and all of its subdirectories, use the -d option:

symbex Database -d ~/projects/datasette

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:

symbex MyClass --silent

Example output

In a fresh checkout of Datasette I ran this command:

symbex MessagesDebugView get_long_description

Here's the output of the command:

# File: setup.py Line: 5
def get_long_description():
    with open(
        os.path.join(os.path.dirname(os.path.abspath(__file__)), "README.md"),
        encoding="utf8",
    ) as fp:
        return fp.read()

# File: datasette/views/special.py Line: 60
class PatternPortfolioView(View):
    async def get(self, request, datasette):
        await datasette.ensure_permissions(request.actor, ["view-instance"])
        return Response.html(
            await datasette.render_template(
                "patterns.html",
                request=request,
                view_name="patterns",
            )
        )

Just the signatures

The -s/--signatures option will list just the signatures of the functions and classes, for example:

symbex -s -d symbex

# File: symbex/cli.py Line: 37
def cli(symbols, files, directories, signatures, silent)

# File: symbex/lib.py Line: 10
def find_symbol_nodes(code: str, filename: str, symbols: Iterable[str]) -> List[Tuple[(AST, Optional[str])]]

# File: symbex/lib.py Line: 158
def class_definition(class_def)

# File: symbex/lib.py Line: 192
def annotation_definition(annotation: AST) -> str

# File: symbex/lib.py Line: 210
def read_file(path)

# File: symbex/lib.py Line: 34
def code_for_node(code: str, node: AST, class_name: str, signatures: bool) -> Tuple[(str, int)]

# File: symbex/lib.py Line: 65
def match(name: str, symbols: Iterable[str]) -> bool

# File: symbex/lib.py Line: 90
def function_definition(function_node: AST)

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

This tool is primarily designed to be used with LLM, a CLI tool for working with Large Language Models.

symbex makes it easy to grab a specific class or function and pass it to the llm command.

For example, I ran this in the Datasette repository root:

symbex Response | llm --system 'Explain this code, succinctly'

And got back this:

This code defines a custom Response class with methods for returning HTTP responses. It includes methods for setting cookies, returning HTML, text, and JSON responses, and redirecting to a different URL. The asgi_send method sends the response to the client using the ASGI (Asynchronous Server Gateway Interface) protocol.

Similar tools

• pyastgrep by Luke Plant offers advanced capabilities for viewing and searching through Python ASTs using XPath.
• cq is a tool thet lets you "extract code snippets using CSS-like selectors", built using Tree-sitter and primarily targetting JavaScript and TypeScript.

Development

To contribute to this tool, first checkout the code. Then create a new virtual environment:

cd symbex
python -m venv venv
source venv/bin/activate

Now install the dependencies and test dependencies:

pip install -e '.[test]'

To run the tests:

pytest

just

You can also install just and use it to run the tests and linters like this:

just

Or to list commands:

just -l

Available recipes:
    black         # Apply Black
    cog           # Rebuild docs with cog
    default       # Run tests and linters
    lint          # Run linters
    test *options # Run pytest with supplied options