firecrown.fctools.ast_utils

AST utilities for fctools.

This module provides utilities for parsing Python source code using the Abstract Syntax Tree (AST) module, extracting docstrings, and analyzing code structure.

Functions

get_module_docstring(file_path)	Extract the module-level docstring from a Python file.
get_class_definition(source, class_name)	Find a class definition node in Python source code.
format_docstring_summary(docstring[, max_length])	Extract a brief summary from a docstring.
extract_class_attributes(class_def)	Extract class-level attribute names from a ClassDef node.
format_class_docstring(class_def)	Extract and format the docstring from a ClassDef node.
get_function_names(class_def)	Extract names of methods defined in a class.

Module Contents

firecrown.fctools.ast_utils.get_module_docstring(file_path)

Extract the module-level docstring from a Python file.

Parameters:

file_path (pathlib.Path) – Path to the Python source file

Returns:

The module docstring if present, None otherwise

Raises:

• OSError – If the file cannot be read

• SyntaxError – If the file contains invalid Python syntax

• UnicodeDecodeError – If the file encoding is invalid

Return type:

str | None

firecrown.fctools.ast_utils.get_class_definition(source, class_name)

Find a class definition node in Python source code.

Parameters:

• source (str) – Python source code as a string

• class_name (str) – Name of the class to find

Returns:

The ClassDef AST node if found, None otherwise

Raises:

SyntaxError – If the source contains invalid Python syntax

Return type:

ast.ClassDef | None

firecrown.fctools.ast_utils.format_docstring_summary(docstring, max_length=80)

Extract a brief summary from a docstring.

Takes the first meaningful (non-empty, non-marker) line from the docstring. If the line is longer than max_length, it will be truncated with ‘…’.

Parameters:

• docstring (str | None) – The docstring to summarize (may be None)

• max_length (int) – Maximum length for the summary (default: 80)

Returns:

A brief summary string, or a default message if no docstring

Return type:

str

Example usage:

>>> format_docstring_summary("This is a tool.\\n\\nMore details.")
'This is a tool.'
>>> format_docstring_summary(None)
'No description available'

firecrown.fctools.ast_utils.extract_class_attributes(class_def)

Extract class-level attribute names from a ClassDef node.

Parameters:

class_def (ast.ClassDef) – An AST ClassDef node

Returns:

List of attribute names defined at class level

Return type:

list[str]

Note

This extracts simple assignments like name: type or name = value at the class body level, not instance attributes defined in __init__.

firecrown.fctools.ast_utils.format_class_docstring(class_def)

Extract and format the docstring from a ClassDef node.

Parameters:

class_def (ast.ClassDef) – An AST ClassDef node

Returns:

List of formatted docstring lines (empty list if no docstring)

Return type:

list[str]

firecrown.fctools.ast_utils.get_function_names(class_def)

Extract names of methods defined in a class.

Parameters:

class_def (ast.ClassDef) – An AST ClassDef node

Returns:

List of method names defined in the class

Return type:

list[str]

Note

This only returns methods defined directly in the class, not inherited methods.