Common tasks

This page is a task index. Each section states a codebase question, then shows the corresponding CLDK call and the shape of its result: the call appears first, and the output follows as a trailing comment. Java examples use Apache Commons CLI (project_path="commons-cli"); Python examples use a generic my_pkg.

Build once, query many times

Construct the analysis object once and reuse it. The default analysis level is symbol_table; any query that touches the call graph (callers, callees) requires analysis_level=AnalysisLevel.call_graph. See Concepts for what each level populates.

List all methods in a class

Enumerate every method declared on a class.

Python

from cldk import CLDK

analysis = CLDK.python(project_path="my_pkg")

pyclass = analysis.get_classes()["my_pkg.options.Options"]
for method in pyclass.methods.values():
    print(method.signature)
# add_option(self, option)
# get_option(self, name)
# has_option(self, name)
# ...

Java

from cldk import CLDK

analysis = CLDK.java(project_path="commons-cli")

klass = "org.apache.commons.cli.Options"
methods = analysis.get_methods()[klass]
for signature in methods:
    print(signature)
# Parameter types in each signature are fully qualified:
# addOption(org.apache.commons.cli.Option)
# addOption(java.lang.String, boolean, java.lang.String)
# getOption(java.lang.String)
# hasOption(java.lang.String)
# ...

Get a method’s source body

Retrieve the exact source of a single method by its qualified class name and signature, without reading files or tracking line ranges.

Python

method = analysis.get_method(
    "my_pkg.options.Options",
    "add_option",
)
print(method.code)
# def add_option(self, option):
#     self._options[option.name] = option
#     return self

Java

method = analysis.get_method(
    "org.apache.commons.cli.Options",
    "addOption(org.apache.commons.cli.Option)",
)
print(method.code)
# public Options addOption(Option opt) {
#     String key = opt.getKey();
#     ...
#     return this;
# }

Note

get_method(...) returns None if the method is not found, so guard with if method: before reading .code. The returned object is a JCallable (Java) or PyCallable (Python).

Build a call graph

The call graph is a networkx.DiGraph whose edges point from caller to callee. It underpins the callers and callees queries and therefore requires the call_graph analysis level.

Python

from cldk import CLDK
from cldk.analysis import AnalysisLevel

analysis = CLDK.python(
    project_path="my_pkg",
    analysis_level=AnalysisLevel.call_graph,  # required for call edges
)

cg = analysis.get_call_graph()
print(cg.number_of_nodes(), "methods,", cg.number_of_edges(), "edges")
# 87 methods, 113 edges

Java

from cldk import CLDK
from cldk.analysis import AnalysisLevel

analysis = CLDK.java(
    project_path="commons-cli",
    analysis_level=AnalysisLevel.call_graph,  # required for call edges
)

cg = analysis.get_call_graph()
print(cg.number_of_nodes(), "methods,", cg.number_of_edges(), "edges")
# 421 methods, 638 edges

Find who calls a method

Impact analysis. get_callers returns the set of methods that invoke the target.

Python

callers = analysis.get_callers(
    "my_pkg.options.Options",
    "add_option",
)
print(list(callers))
# ['my_pkg.cli.build_options', 'my_pkg.options.Options.add_required', ...]

Java

callers = analysis.get_callers(
    "org.apache.commons.cli.Options",
    "addOption(org.apache.commons.cli.Option)",
)
print(list(callers))
# ['org.apache.commons.cli.Options.addOption(java.lang.String, boolean, java.lang.String)',
#  'org.apache.commons.cli.DefaultParser.handleOption(...)', ...]

Inspect the shape once

get_callers/get_callees return dictionaries whose exact keys depend on your CLDK and backend version. Print one result with print(callers) (or import json; print(json.dumps(callers, default=str, indent=2))) the first time you wire this up, then index the fields your version returns.

Find what a method calls

The dependency view. get_callees is the inverse of get_callers, returning the methods that the target invokes.

Python

callees = analysis.get_callees(
    "my_pkg.parser.DefaultParser",
    "parse",
)
print(list(callees))
# ['my_pkg.options.Options.get_option', 'my_pkg.cli.CommandLine.add_option', ...]

Java

callees = analysis.get_callees(
    "org.apache.commons.cli.DefaultParser",
    "parse(org.apache.commons.cli.Options, java.lang.String[])",
)
print(list(callees))
# ['org.apache.commons.cli.Options.getOption(java.lang.String)',
#  'org.apache.commons.cli.CommandLine.addOption(org.apache.commons.cli.Option)', ...]

Map the class hierarchy

In Java, walk class relationships with get_sub_classes, get_extended_classes, and get_implemented_interfaces.

Python

# Python analysis does not expose get_class_hierarchy / get_sub_classes.
# Recover base classes from the model: each PyClass records its bases.
pyclass = analysis.get_classes()["my_pkg.parser.DefaultParser"]
print(pyclass.base_classes)
# ['my_pkg.parser.Parser']

Java

parser = "org.apache.commons.cli.Parser"
print(analysis.get_sub_classes(parser))
# {'org.apache.commons.cli.BasicParser', 'org.apache.commons.cli.GnuParser', ...}

print(analysis.get_implemented_interfaces("org.apache.commons.cli.DefaultParser"))
# {'org.apache.commons.cli.CommandLineParser'}

Note

Class-relationship helpers (get_sub_classes, get_extended_classes, get_implemented_interfaces) are part of the Java API. For Python, read base classes off the PyClass model instead, as shown above.

Find data-access / CRUD operations

Locate where the code reads or writes persistent data. This is useful for security triage and data-flow analysis, and is a Java-only capability.

Python

# Not available. CRUD-operation extraction (get_all_crud_operations)
# is part of the Java analysis API only.

Java

crud = analysis.get_all_crud_operations()
for entry in crud:
    print(entry)
# JCRUDOperation(operation_type='READ',  ...)
# JCRUDOperation(operation_type='CREATE', ...)
# ...

Where to go next

cocoa Build a Code Context Agent plugin on these calls.

Core concepts Analysis levels and call graphs explained.

Java API reference Every method on the Java analysis API.

Python API reference The Python analysis API in full.