Cheat sheet

A single-page reference for the common CLDK calls. Build one analysis object with a per-language factory. Then query it. For background and walkthroughs, see What is CLDK?, Core concepts, and the Quickstart.

Install

pip install cldk

Reachability queries use networkx. pip install cldk installs it as a dependency. If your own code imports networkx directly, install it explicitly too:

pip install cldk networkx

Construct

Use the per-language factory for the language you want: CLDK.java(...), CLDK.python(...), or CLDK.typescript(...). The analysis level controls how much CLDK computes.

Java

from cldk import CLDK
from cldk.analysis import AnalysisLevel

# Default level is symbol_table. Use call_graph for callers/callees/reachability.
analysis = CLDK.java(
    project_path="commons-cli",
    analysis_level=AnalysisLevel.call_graph,
)
print(len(analysis.get_classes()), "classes")  # -> 23 classes

Python

from cldk import CLDK
from cldk.analysis import AnalysisLevel

analysis = CLDK.python(
    project_path="my_pkg",
    analysis_level=AnalysisLevel.call_graph,
)
print(len(analysis.get_classes()), "classes")

TypeScript

from cldk import CLDK
from cldk.analysis import AnalysisLevel

analysis = CLDK.typescript(
    project_path="my_app",
    analysis_level=AnalysisLevel.call_graph,
)
print(len(analysis.get_classes()), "classes")

Deprecated constructor form

The CLDK(language="java").analysis(project_path=...) form is deprecated. It forwards to the factories above. Use CLDK.java(...), CLDK.python(...), or CLDK.typescript(...) instead. from cldk import CLDK does not change.

Argument	Value	Notes
factory	CLDK.java / CLDK.python / CLDK.typescript	Selects the language facade.
project_path	path to checkout	The project to analyze.
analysis_level	symbol_table (default) / call_graph / program_dependency_graph / system_dependency_graph	Call graph, callers, and callees need call_graph. Dataflow and taint need level 3 or 4.
target_files	list of paths (optional)	Restrict analysis to these files.
eager	bool (default False)	Force regeneration of cached analysis.
backend	config object (optional)	Selects the backend by type (see below). Omit for the default codeanalyzer backend.

Select a backend

The type of the backend= configuration object selects the backend. Import these types from cldk.analysis.commons.backend_config. Omit backend= for the default in-process codeanalyzer backend. cache_dir and use_ray live inside these configuration objects.

from cldk import CLDK
from cldk.analysis.commons.backend_config import (
    CodeAnalyzerConfig,
    PyCodeAnalyzerConfig,
    Neo4jConnectionConfig,
)

# Default codeanalyzer backend, with an explicit cache root (optional).
analysis = CLDK.java(
    project_path="commons-cli",
    backend=CodeAnalyzerConfig(cache_dir="/tmp/cache"),
)

# Python codeanalyzer backend with call-graph knobs.
analysis = CLDK.python(
    project_path="my_pkg",
    backend=PyCodeAnalyzerConfig(use_ray=True),
)

# Read-only Neo4j backend (Java / Python / TypeScript); the graph is populated out of band.
analysis = CLDK.typescript(
    backend=Neo4jConnectionConfig(uri="bolt://localhost:7687", username="neo4j", password="neo4j", application_name="my_project"),
)

Config type	Backend	Notes
(omit) / CodeAnalyzerConfig	In-process codeanalyzer	Default for Java/TypeScript. cache_dir only.
PyCodeAnalyzerConfig	In-process codeanalyzer (Python)	Default for Python. Adds use_ray.
Neo4jConnectionConfig(uri=...)	Read-only Neo4j/Cypher	Java, Python, and TypeScript. project_path is optional. The graph is loaded out of band. See Analysis at scale.

Caching and the cache root

Caching is on by default for Java, Python, and TypeScript. Artifacts live under one language-keyed cache_dir. The default is <project>/.codeanalyzer, with each language under <cache_dir>/<language>/.

The factories have no analysis_backend_path argument. The binary ships inside the packaged codeanalyzer-*. For the TypeScript backend, set the binary with the $CODEANALYZER_TS_BIN environment variable. The factories have no analysis_json_path argument. cache_dir sets the cache root.

Symbol table

The symbol table is available at every analysis level. It holds every class, method, and field, typed and queryable.

Method	Returns	Description
get_symbol_table()	Dict[str, JCompilationUnit | PyModule | TSModule]	The entire project, indexed by file.
get_classes()	Dict[str, JType | PyClass | TSClass]	Every class or type, keyed by qualified name.
get_methods()	Dict[str, Dict]	Every method, keyed by class and then by method.
get_method(qualified_class_name, qualified_method_name)	JCallable | PyCallable | TSCallable | None	One method. .code holds its source body.

m = analysis.get_method(
    "org.apache.commons.cli.OptionBuilder", "create(java.lang.String)"
)
print(m.code)  # -> source body of OptionBuilder.create(java.lang.String)

Java also gives you class-relationship queries: get_sub_classes(cls), get_extended_classes(cls), and get_implemented_interfaces(cls). It also gives you get_all_comments().

Call graph and reachability

Build at the right level

These methods need analysis_level=AnalysisLevel.call_graph. The default symbol_table level does not populate call edges.

Method	Returns	Notes
get_call_graph()	networkx.DiGraph	Edges point caller → callee.
get_call_graph_json()	str	Same graph, serialized.
get_callers(target_class_name, target_method_declaration)	Dict	Methods that call this method.
get_callees(source_class_name, source_method_declaration)	Dict	Methods that this method calls.
get_class_call_graph(qualified_class_name, method_signature=None)	List[Tuple]	Call-graph edges reachable from one class or method.

cg = analysis.get_call_graph()          # -> networkx.DiGraph
callers = analysis.get_callers(
    "org.apache.commons.cli.Options", "addOption(org.apache.commons.cli.Option)"
)  # -> Dict of call sites

Reachability is a networkx query over the call graph:

import networkx as nx

cg = analysis.get_call_graph()
print(nx.has_path(cg, src, sink))                 # reachable? -> True / False
# nx.shortest_path(cg, src, sink)                 # one path
# list(nx.all_simple_paths(cg, src, sink))        # every path

Dataflow and taint New in 2.0

CLDK 2.0 adds levels 3 and 4, and the methods over them. Version 2.0 is a release candidate, so install it with pip install --pre cldk. Java, Python, and TypeScript all expose this surface.

Method	Returns	Notes
get_cfg(callable, ...)	EdgePage[CfgEdge]	Control-flow edges. Page with next_cursor.
get_cdg(callable, ...)	EdgePage[CdgEdge]	Control-dependence edges.
get_ddg(callable, ...)	EdgePage[DdgEdge]	Data-dependence edges.
resolve_callable(name, ...)	SliceNode	Address a callable by name.
resolve_value(name, *, within)	SliceNode	Address a value inside a callable.
locate(path, line)	LocateResult	Go from a file and a line into the graph.
get_source(node_id)	str	The source text for a node.
slice_forward(src, *, within, ...)	Slice	Where does this value go?
slice_backward(src, *, within, ...)	Slice	What determined this value?
backward_cone(sinks, ...)	Slice	What feeds any of these sinks?
reaches(src, dst, ...)	bool	Does it reach it at all?
flows_to_call(src, callee, *, within, ...)	bool	Does it reach a call to this callee?
flows_to_argument(src, callee, arg, *, within, ...)	bool	Does it reach that argument?
paths_between(src, dst, *, src_within, dst_within, ...)	FlowPaths	The routes it takes.
taint(sources, sinks, sanitizers, ...)	TaintResult	m sources against n sinks in one traversal.

r = analysis.taint(
    sources=[("invoice_id", "PaymentPortal.invoice_transaction")],
    sinks=[("query", "AccountMove._execute")],
    sanitizers=["PaymentPortal._sanitize_id"],   # str cuts a callable
)                                                # (name, within) cuts a variable
r.paths        # witnesses
r.exhausted    # searched, nothing found  (empty whenever depth is set)
r.unresolved   # the ledger: read this before trusting exhausted

Provenance ranks ssa > reaching-defs > points-to. FlowPath.weakest is the hop that caps the claim. See Dataflow graphs and Taint analysis.

Models

The typed objects that each language analysis API returns.

Language	Models
Java	JType, JCallable, JCompilationUnit, JField, JComment
Python	PyModule, PyClass, PyCallable, PyImport, PyComment
TypeScript	TSModule, TSClass, TSCallable, TSInterface, TSEnum, TSTypeAlias, TSImport, TSComment

Gotchas

Common mistakes

• Call-graph level is required. get_call_graph, get_callers, get_callees, and reachability need analysis_level=AnalysisLevel.call_graph. The default symbol_table level does not have call edges.
• Analysis is project-based. Pass project_path=... to the factory, for example CLDK.java(project_path=...). Point it at the project root. The Neo4j backend is the exception. Its graph is populated out of band, so project_path is optional.

Next steps

Python API reference Every method on the Python SDK analysis APIs.