Querying Your Project

code_monkey exposes a chaining query DSL for searching your project’s codebase. Specifically, it has a class called NodeQuery that acts as a wrapper around a set of nodes. You can call filtering methods on NodeQueries to narrow your search, or index into them like a list to grab individual nodes and inspect them.

Here’s an example:

from code_monkey.node_query import project_query

#this is a single-element query containing just a "Project" node
project = project_query('path/to/my/project')

#this is a query containing every node in your project
#(this includes packages, modules, function definitions, classes,
#import statements, and variable assignments)
everything = project.flatten()

#this query contains a node for every class in your project
just_classes = everything.classes()

#this is only classes that have 'tests.' in their Python dotpath
just_test_classes = just_classes.path_contains('tests.')

#this is only methods of said test classes
#(i.e., function nodes that are direct children of a class)
test_methods = just_test_classes.children().functions()

#this is the first FunctionNode in the above query, representing a
#single method
single_method = test_methods[0]

Chaining query methods creates new instances of NodeQuery, rather than modifying old ones, so you can keep old queries around and use them to perform new searches.

Here’s a detailed breakdown of the search functionality available to you:

code_monkey.node_query.project_query(project_path)

Take a filesystem path project_path, and return a NodeQuery containing a ProjectNode representing the Python project at that path.

When working with a new project, this is usually the first thing you should use.

class code_monkey.node_query.NodeQuery(matches=set([]))

A set of nodes, which can be filtered down to select nodes that match certain criteria.

assignments()

Return a query containing only AssignmentNodes, which represent variable assignments.

children()

Return a new query encompassing all immediate children of matches

classes()

Return a query containing only ClassNodes.

constants()

Return a query containing only ConstantNodes.

descendents()

Return a flat query of all nodes descended from matches

filter_type(type_cls)

Return only the query elements of a certain type; i.e. ClassNode, FunctionNode, etc.

flatten()

Return a flat query of matches and all their descendents

functions()

Return a query containing only FunctionNodes, which may represent functions or methods.

has_child(find_me)

Match nodes who have an immediate child with the name find_me

imports()

Return a query containing only ImportNodes.

join(*other_queries)

Return a new query encompassing both this query and all parameter queries

modules()

Return a query containing only ModuleNodes.

Note that ModuleNodes represent ‘leaf’ modules only; while Python considers a package to be a type of module, code_monkey does not.

packages()

Return a query containing only PackageNodes.

path_contains(find_me)

Match nodes whose path contains the string find_me

source_contains(find_me)

Match nodes whose source contains any string in the list find_me. If find_me is a single string, it will be coerced to a list.

subclass_of_name(find_me)

Match nodes who are a direct subclass of a parent named find_me.