Skip to content

Python Analysis

This page documents the Python-related APIs in the CLDK library.

Use the table of contents to navigate classes, functions, and submodules exposed under the Python analysis and schema packages.

Analysis#

Python analysis utilities and workflows.

Python analysis utilities.

Provides a high-level API to query modules, classes, functions, and methods from Python projects or single-source inputs using Treesitter.

PythonAnalysis #

Analysis façade for Python code.

Parameters:

Name Type Description Default
project_dir str | Path | None

Directory path of the project.

required
source_code str | None

Source text for single-file analysis.

required
Source code in cldk/analysis/python/python_analysis.py
class PythonAnalysis:
    """Analysis façade for Python code.

    Args:
        project_dir (str | Path | None): Directory path of the project.
        source_code (str | None): Source text for single-file analysis.
    """

    def __init__(
        self,
        project_dir: str | Path | None,
        source_code: str | None,
    ) -> None:
        self.project_dir = project_dir
        self.source_code = source_code
        self.analysis_backend: TreesitterPython = TreesitterPython()

    def get_methods(self) -> List[PyMethod]:
        """Return all methods.

        Returns:
            list[PyMethod]: Methods discovered in the source code.

        Examples:
            >>> src = 'class C: def f(self): pass def g(self): pass'
            >>> pa = PythonAnalysis(project_dir=None, source_code=src)  # doctest: +SKIP
            >>> len(pa.get_methods())  # doctest: +SKIP
            2
        """
        return self.analysis_backend.get_all_methods(self.source_code)

    def get_functions(self) -> List[PyMethod]:
        """Return all functions.

        Returns:
            list[PyMethod]: Functions discovered in the source code.

        Examples:
            >>> src = 'def f(): return 1'
            >>> pa = PythonAnalysis(project_dir=None, source_code=src)
            >>> [m.full_signature for m in pa.get_functions()]
            ['f()']
        """
        return self.analysis_backend.get_all_functions(self.source_code)

    def get_modules(self) -> List[PyModule]:
        """Return all modules in the project directory.

        Returns:
            list[PyModule]: Modules discovered under project_dir.

        Examples:
            Create a temporary project and discover modules:

            >>> import os, tempfile
            >>> d = tempfile.mkdtemp()
            >>> _ = open(os.path.join(d, 'a.py'), 'w').write('print(1)')
            >>> _ = open(os.path.join(d, 'b.py'), 'w').write('print(2)')
            >>> pa = PythonAnalysis(project_dir=d, source_code=None)
            >>> len(pa.get_modules()) >= 2
            True
        """
        return self.analysis_backend.get_all_modules(self.project_dir)

    def get_method_details(self, method_signature: str) -> PyMethod:
        """Return details for a given method signature.

        Args:
            method_signature (str): Method signature to look up.

        Returns:
            PyMethod: Method details.

        Examples:
            >>> src = 'class C: def add(self, a, b): return a+b'
            >>> pa = PythonAnalysis(project_dir=None, source_code=src)  # doctest: +SKIP
            >>> pa.get_method_details('add(self, a, b)').full_signature  # doctest: +SKIP
            'add(self, a, b)'
        """
        return self.analysis_backend.get_method_details(self.source_code, method_signature)

    def is_parsable(self, source_code: str) -> bool:
        """Check if the source code is parsable.

        Args:
            source_code (str): Source code to parse.

        Returns:
            bool: True if parsable, False otherwise.

        Examples:
            >>> PythonAnalysis(None, None).is_parsable('def f(): pass')
            True
            >>> PythonAnalysis(None, None).is_parsable('def f(): pass if')
            False
        """
        return TreesitterPython().is_parsable(source_code)

    def get_raw_ast(self, source_code: str) -> str:
        """Parse and return the raw AST.

        Args:
            source_code (str): Source code to parse.

        Returns:
            str: Raw AST representation.

        Examples:
            >>> ast = PythonAnalysis(None, None).get_raw_ast('def f(): pass')
            >>> isinstance(ast, str)
            True
        """
        return TreesitterPython().get_raw_ast(source_code)

    def get_imports(self) -> List[PyImport]:
        """Return all import statements.

        Returns:
            list[PyImport]: Imports discovered in the source code.

        Examples:
            >>> src = 'import os; from math import sqrt; from x import *'
            >>> pa = PythonAnalysis(project_dir=None, source_code=src)
            >>> len(pa.get_imports())
            3
        """
        return self.analysis_backend.get_all_imports_details(self.source_code)

    def get_variables(self, **kwargs):
        """Return all variables discovered in the source code.

        Raises:
            NotImplementedError: This functionality is not implemented yet.

        Examples:
            >>> pa = PythonAnalysis(project_dir=None, source_code='x=1')
            >>> pa.get_variables()  # doctest: +IGNORE_EXCEPTION_DETAIL
            Traceback (most recent call last):
            NotImplementedError: Support for this functionality has not been implemented yet.
        """
        raise NotImplementedError("Support for this functionality has not been implemented yet.")

    def get_classes(self) -> List[PyClass]:
        """Return all classes.

        Returns:
            list[PyClass]: Classes discovered in the source code.

        Examples:
            >>> src = 'class A: pass'
            >>> pa = PythonAnalysis(project_dir=None, source_code=src)
            >>> [c.class_name for c in pa.get_classes()]
            ['A']
        """
        return self.analysis_backend.get_all_classes(self.source_code)

    def get_classes_by_criteria(self, **kwargs):
        """Return classes filtered by inclusion/exclusion criteria.

        Raises:
            NotImplementedError: This functionality is not implemented yet.

        Examples:
            >>> pa = PythonAnalysis(project_dir=None, source_code='class A: pass')
            >>> pa.get_classes_by_criteria()  # doctest: +IGNORE_EXCEPTION_DETAIL
            Traceback (most recent call last):
            NotImplementedError: Support for this functionality has not been implemented yet.
        """
        raise NotImplementedError("Support for this functionality has not been implemented yet.")

    def get_sub_classes(self, **kwargs):
        """Return all subclasses.

        Raises:
            NotImplementedError: This functionality is not implemented yet.

        Examples:
            >>> pa = PythonAnalysis(project_dir=None, source_code='class A: pass')
            >>> pa.get_sub_classes()  # doctest: +IGNORE_EXCEPTION_DETAIL
            Traceback (most recent call last):
            NotImplementedError: Support for this functionality has not been implemented yet.
        """
        raise NotImplementedError("Support for this functionality has not been implemented yet.")

    def get_nested_classes(self, **kwargs):
        """Return all nested classes.

        Raises:
            NotImplementedError: This functionality is not implemented yet.

        Examples:
            >>> pa = PythonAnalysis(project_dir=None, source_code='class A: class B: pass')
            >>> pa.get_nested_classes()  # doctest: +IGNORE_EXCEPTION_DETAIL
            Traceback (most recent call last):
            NotImplementedError: Support for this functionality has not been implemented yet.
        """
        raise NotImplementedError("Support for this functionality has not been implemented yet.")

    def get_constructors(self, **kwargs):
        """Return all constructors.

        Raises:
            NotImplementedError: This functionality is not implemented yet.

        Examples:
            >>> pa = PythonAnalysis(project_dir=None, source_code='class A: def __init__(self): pass')
            >>> pa.get_constructors()  # doctest: +IGNORE_EXCEPTION_DETAIL
            Traceback (most recent call last):
            NotImplementedError: Support for this functionality has not been implemented yet.
        """
        raise NotImplementedError("Support for this functionality has not been implemented yet.")

    def get_methods_in_class(self, **kwargs):
        """Return all methods within a given class.

        Raises:
            NotImplementedError: This functionality is not implemented yet.

        Examples:
            >>> pa = PythonAnalysis(project_dir=None, source_code='class A: def f(self): pass')
            >>> pa.get_methods_in_class()  # doctest: +IGNORE_EXCEPTION_DETAIL
            Traceback (most recent call last):
            NotImplementedError: Support for this functionality has not been implemented yet.
        """
        raise NotImplementedError("Support for this functionality has not been implemented yet.")

    def get_fields(self, **kwargs):
        """Return all fields.

        Raises:
            NotImplementedError: This functionality is not implemented yet.

        Examples:
            >>> pa = PythonAnalysis(project_dir=None, source_code='class A: x=1')
            >>> pa.get_fields()  # doctest: +IGNORE_EXCEPTION_DETAIL
            Traceback (most recent call last):
            NotImplementedError: Support for this functionality has not been implemented yet.
        """
        raise NotImplementedError("Support for this functionality has not been implemented yet.")

get_methods() #

Return all methods.

Returns:

Type Description
List[PyMethod]

list[PyMethod]: Methods discovered in the source code.

Examples:

>>> src = 'class C: def f(self): pass def g(self): pass'
>>> pa = PythonAnalysis(project_dir=None, source_code=src)
>>> len(pa.get_methods())
2
Source code in cldk/analysis/python/python_analysis.py
def get_methods(self) -> List[PyMethod]:
    """Return all methods.

    Returns:
        list[PyMethod]: Methods discovered in the source code.

    Examples:
        >>> src = 'class C: def f(self): pass def g(self): pass'
        >>> pa = PythonAnalysis(project_dir=None, source_code=src)  # doctest: +SKIP
        >>> len(pa.get_methods())  # doctest: +SKIP
        2
    """
    return self.analysis_backend.get_all_methods(self.source_code)

get_functions() #

Return all functions.

Returns:

Type Description
List[PyMethod]

list[PyMethod]: Functions discovered in the source code.

Examples:

>>> src = 'def f(): return 1'
>>> pa = PythonAnalysis(project_dir=None, source_code=src)
>>> [m.full_signature for m in pa.get_functions()]
['f()']
Source code in cldk/analysis/python/python_analysis.py
def get_functions(self) -> List[PyMethod]:
    """Return all functions.

    Returns:
        list[PyMethod]: Functions discovered in the source code.

    Examples:
        >>> src = 'def f(): return 1'
        >>> pa = PythonAnalysis(project_dir=None, source_code=src)
        >>> [m.full_signature for m in pa.get_functions()]
        ['f()']
    """
    return self.analysis_backend.get_all_functions(self.source_code)

get_modules() #

Return all modules in the project directory.

Returns:

Type Description
List[PyModule]

list[PyModule]: Modules discovered under project_dir.

Examples:

Create a temporary project and discover modules:

>>> import os, tempfile
>>> d = tempfile.mkdtemp()
>>> _ = open(os.path.join(d, 'a.py'), 'w').write('print(1)')
>>> _ = open(os.path.join(d, 'b.py'), 'w').write('print(2)')
>>> pa = PythonAnalysis(project_dir=d, source_code=None)
>>> len(pa.get_modules()) >= 2
True
Source code in cldk/analysis/python/python_analysis.py
def get_modules(self) -> List[PyModule]:
    """Return all modules in the project directory.

    Returns:
        list[PyModule]: Modules discovered under project_dir.

    Examples:
        Create a temporary project and discover modules:

        >>> import os, tempfile
        >>> d = tempfile.mkdtemp()
        >>> _ = open(os.path.join(d, 'a.py'), 'w').write('print(1)')
        >>> _ = open(os.path.join(d, 'b.py'), 'w').write('print(2)')
        >>> pa = PythonAnalysis(project_dir=d, source_code=None)
        >>> len(pa.get_modules()) >= 2
        True
    """
    return self.analysis_backend.get_all_modules(self.project_dir)

get_method_details(method_signature) #

Return details for a given method signature.

Parameters:

Name Type Description Default
method_signature str

Method signature to look up.

required

Returns:

Name Type Description
PyMethod PyMethod

Method details.

Examples:

>>> src = 'class C: def add(self, a, b): return a+b'
>>> pa = PythonAnalysis(project_dir=None, source_code=src)
>>> pa.get_method_details('add(self, a, b)').full_signature
'add(self, a, b)'
Source code in cldk/analysis/python/python_analysis.py
def get_method_details(self, method_signature: str) -> PyMethod:
    """Return details for a given method signature.

    Args:
        method_signature (str): Method signature to look up.

    Returns:
        PyMethod: Method details.

    Examples:
        >>> src = 'class C: def add(self, a, b): return a+b'
        >>> pa = PythonAnalysis(project_dir=None, source_code=src)  # doctest: +SKIP
        >>> pa.get_method_details('add(self, a, b)').full_signature  # doctest: +SKIP
        'add(self, a, b)'
    """
    return self.analysis_backend.get_method_details(self.source_code, method_signature)

is_parsable(source_code) #

Check if the source code is parsable.

Parameters:

Name Type Description Default
source_code str

Source code to parse.

required

Returns:

Name Type Description
bool bool

True if parsable, False otherwise.

Examples:

>>> PythonAnalysis(None, None).is_parsable('def f(): pass')
True
>>> PythonAnalysis(None, None).is_parsable('def f(): pass if')
False
Source code in cldk/analysis/python/python_analysis.py
def is_parsable(self, source_code: str) -> bool:
    """Check if the source code is parsable.

    Args:
        source_code (str): Source code to parse.

    Returns:
        bool: True if parsable, False otherwise.

    Examples:
        >>> PythonAnalysis(None, None).is_parsable('def f(): pass')
        True
        >>> PythonAnalysis(None, None).is_parsable('def f(): pass if')
        False
    """
    return TreesitterPython().is_parsable(source_code)

get_raw_ast(source_code) #

Parse and return the raw AST.

Parameters:

Name Type Description Default
source_code str

Source code to parse.

required

Returns:

Name Type Description
str str

Raw AST representation.

Examples:

>>> ast = PythonAnalysis(None, None).get_raw_ast('def f(): pass')
>>> isinstance(ast, str)
True
Source code in cldk/analysis/python/python_analysis.py
def get_raw_ast(self, source_code: str) -> str:
    """Parse and return the raw AST.

    Args:
        source_code (str): Source code to parse.

    Returns:
        str: Raw AST representation.

    Examples:
        >>> ast = PythonAnalysis(None, None).get_raw_ast('def f(): pass')
        >>> isinstance(ast, str)
        True
    """
    return TreesitterPython().get_raw_ast(source_code)

get_imports() #

Return all import statements.

Returns:

Type Description
List[PyImport]

list[PyImport]: Imports discovered in the source code.

Examples:

>>> src = 'import os; from math import sqrt; from x import *'
>>> pa = PythonAnalysis(project_dir=None, source_code=src)
>>> len(pa.get_imports())
3
Source code in cldk/analysis/python/python_analysis.py
def get_imports(self) -> List[PyImport]:
    """Return all import statements.

    Returns:
        list[PyImport]: Imports discovered in the source code.

    Examples:
        >>> src = 'import os; from math import sqrt; from x import *'
        >>> pa = PythonAnalysis(project_dir=None, source_code=src)
        >>> len(pa.get_imports())
        3
    """
    return self.analysis_backend.get_all_imports_details(self.source_code)

get_variables(**kwargs) #

Return all variables discovered in the source code.

Raises:

Type Description
NotImplementedError

This functionality is not implemented yet.

Examples:

>>> pa = PythonAnalysis(project_dir=None, source_code='x=1')
>>> pa.get_variables()
Traceback (most recent call last):
NotImplementedError: Support for this functionality has not been implemented yet.
Source code in cldk/analysis/python/python_analysis.py
def get_variables(self, **kwargs):
    """Return all variables discovered in the source code.

    Raises:
        NotImplementedError: This functionality is not implemented yet.

    Examples:
        >>> pa = PythonAnalysis(project_dir=None, source_code='x=1')
        >>> pa.get_variables()  # doctest: +IGNORE_EXCEPTION_DETAIL
        Traceback (most recent call last):
        NotImplementedError: Support for this functionality has not been implemented yet.
    """
    raise NotImplementedError("Support for this functionality has not been implemented yet.")

get_classes() #

Return all classes.

Returns:

Type Description
List[PyClass]

list[PyClass]: Classes discovered in the source code.

Examples:

>>> src = 'class A: pass'
>>> pa = PythonAnalysis(project_dir=None, source_code=src)
>>> [c.class_name for c in pa.get_classes()]
['A']
Source code in cldk/analysis/python/python_analysis.py
def get_classes(self) -> List[PyClass]:
    """Return all classes.

    Returns:
        list[PyClass]: Classes discovered in the source code.

    Examples:
        >>> src = 'class A: pass'
        >>> pa = PythonAnalysis(project_dir=None, source_code=src)
        >>> [c.class_name for c in pa.get_classes()]
        ['A']
    """
    return self.analysis_backend.get_all_classes(self.source_code)

get_classes_by_criteria(**kwargs) #

Return classes filtered by inclusion/exclusion criteria.

Raises:

Type Description
NotImplementedError

This functionality is not implemented yet.

Examples:

>>> pa = PythonAnalysis(project_dir=None, source_code='class A: pass')
>>> pa.get_classes_by_criteria()
Traceback (most recent call last):
NotImplementedError: Support for this functionality has not been implemented yet.
Source code in cldk/analysis/python/python_analysis.py
def get_classes_by_criteria(self, **kwargs):
    """Return classes filtered by inclusion/exclusion criteria.

    Raises:
        NotImplementedError: This functionality is not implemented yet.

    Examples:
        >>> pa = PythonAnalysis(project_dir=None, source_code='class A: pass')
        >>> pa.get_classes_by_criteria()  # doctest: +IGNORE_EXCEPTION_DETAIL
        Traceback (most recent call last):
        NotImplementedError: Support for this functionality has not been implemented yet.
    """
    raise NotImplementedError("Support for this functionality has not been implemented yet.")

get_sub_classes(**kwargs) #

Return all subclasses.

Raises:

Type Description
NotImplementedError

This functionality is not implemented yet.

Examples:

>>> pa = PythonAnalysis(project_dir=None, source_code='class A: pass')
>>> pa.get_sub_classes()
Traceback (most recent call last):
NotImplementedError: Support for this functionality has not been implemented yet.
Source code in cldk/analysis/python/python_analysis.py
def get_sub_classes(self, **kwargs):
    """Return all subclasses.

    Raises:
        NotImplementedError: This functionality is not implemented yet.

    Examples:
        >>> pa = PythonAnalysis(project_dir=None, source_code='class A: pass')
        >>> pa.get_sub_classes()  # doctest: +IGNORE_EXCEPTION_DETAIL
        Traceback (most recent call last):
        NotImplementedError: Support for this functionality has not been implemented yet.
    """
    raise NotImplementedError("Support for this functionality has not been implemented yet.")

get_nested_classes(**kwargs) #

Return all nested classes.

Raises:

Type Description
NotImplementedError

This functionality is not implemented yet.

Examples:

>>> pa = PythonAnalysis(project_dir=None, source_code='class A: class B: pass')
>>> pa.get_nested_classes()
Traceback (most recent call last):
NotImplementedError: Support for this functionality has not been implemented yet.
Source code in cldk/analysis/python/python_analysis.py
def get_nested_classes(self, **kwargs):
    """Return all nested classes.

    Raises:
        NotImplementedError: This functionality is not implemented yet.

    Examples:
        >>> pa = PythonAnalysis(project_dir=None, source_code='class A: class B: pass')
        >>> pa.get_nested_classes()  # doctest: +IGNORE_EXCEPTION_DETAIL
        Traceback (most recent call last):
        NotImplementedError: Support for this functionality has not been implemented yet.
    """
    raise NotImplementedError("Support for this functionality has not been implemented yet.")

get_constructors(**kwargs) #

Return all constructors.

Raises:

Type Description
NotImplementedError

This functionality is not implemented yet.

Examples:

>>> pa = PythonAnalysis(project_dir=None, source_code='class A: def __init__(self): pass')
>>> pa.get_constructors()
Traceback (most recent call last):
NotImplementedError: Support for this functionality has not been implemented yet.
Source code in cldk/analysis/python/python_analysis.py
def get_constructors(self, **kwargs):
    """Return all constructors.

    Raises:
        NotImplementedError: This functionality is not implemented yet.

    Examples:
        >>> pa = PythonAnalysis(project_dir=None, source_code='class A: def __init__(self): pass')
        >>> pa.get_constructors()  # doctest: +IGNORE_EXCEPTION_DETAIL
        Traceback (most recent call last):
        NotImplementedError: Support for this functionality has not been implemented yet.
    """
    raise NotImplementedError("Support for this functionality has not been implemented yet.")

get_methods_in_class(**kwargs) #

Return all methods within a given class.

Raises:

Type Description
NotImplementedError

This functionality is not implemented yet.

Examples:

>>> pa = PythonAnalysis(project_dir=None, source_code='class A: def f(self): pass')
>>> pa.get_methods_in_class()
Traceback (most recent call last):
NotImplementedError: Support for this functionality has not been implemented yet.
Source code in cldk/analysis/python/python_analysis.py
def get_methods_in_class(self, **kwargs):
    """Return all methods within a given class.

    Raises:
        NotImplementedError: This functionality is not implemented yet.

    Examples:
        >>> pa = PythonAnalysis(project_dir=None, source_code='class A: def f(self): pass')
        >>> pa.get_methods_in_class()  # doctest: +IGNORE_EXCEPTION_DETAIL
        Traceback (most recent call last):
        NotImplementedError: Support for this functionality has not been implemented yet.
    """
    raise NotImplementedError("Support for this functionality has not been implemented yet.")

get_fields(**kwargs) #

Return all fields.

Raises:

Type Description
NotImplementedError

This functionality is not implemented yet.

Examples:

>>> pa = PythonAnalysis(project_dir=None, source_code='class A: x=1')
>>> pa.get_fields()
Traceback (most recent call last):
NotImplementedError: Support for this functionality has not been implemented yet.
Source code in cldk/analysis/python/python_analysis.py
def get_fields(self, **kwargs):
    """Return all fields.

    Raises:
        NotImplementedError: This functionality is not implemented yet.

    Examples:
        >>> pa = PythonAnalysis(project_dir=None, source_code='class A: x=1')
        >>> pa.get_fields()  # doctest: +IGNORE_EXCEPTION_DETAIL
        Traceback (most recent call last):
        NotImplementedError: Support for this functionality has not been implemented yet.
    """
    raise NotImplementedError("Support for this functionality has not been implemented yet.")

Schema#

Data models used by the Python analyzers.

Models module

PyBuildAttributes #

Bases: BaseModel

Handles all the project build tool (requirements.txt/poetry/setup.py) attributes

Source code in cldk/models/python/models.py
class PyBuildAttributes(BaseModel):
    """Handles all the project build tool (requirements.txt/poetry/setup.py) attributes"""

PyConfig #

Bases: BaseModel

Application configuration information

Source code in cldk/models/python/models.py
class PyConfig(BaseModel):
    """Application configuration information"""