firecrown.fctools.ast_utils
===========================

.. py:module:: firecrown.fctools.ast_utils

.. autoapi-nested-parse::

   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
---------

.. autoapisummary::

   firecrown.fctools.ast_utils.get_module_docstring
   firecrown.fctools.ast_utils.get_class_definition
   firecrown.fctools.ast_utils.format_docstring_summary
   firecrown.fctools.ast_utils.extract_class_attributes
   firecrown.fctools.ast_utils.format_class_docstring
   firecrown.fctools.ast_utils.get_function_names


Module Contents
---------------

.. py:function:: get_module_docstring(file_path)

   Extract the module-level docstring from a Python file.

   :param file_path: Path to the Python source file
   :return: The module docstring if present, None otherwise
   :raises OSError: If the file cannot be read
   :raises SyntaxError: If the file contains invalid Python syntax
   :raises UnicodeDecodeError: If the file encoding is invalid


.. py:function:: get_class_definition(source, class_name)

   Find a class definition node in Python source code.

   :param source: Python source code as a string
   :param class_name: Name of the class to find
   :return: The ClassDef AST node if found, None otherwise
   :raises SyntaxError: If the source contains invalid Python syntax


.. py:function:: 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 '...'.

   :param docstring: The docstring to summarize (may be None)
   :param max_length: Maximum length for the summary (default: 80)
   :return: A brief summary string, or a default message if no docstring

   Example usage::

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


.. py:function:: extract_class_attributes(class_def)

   Extract class-level attribute names from a ClassDef node.

   :param class_def: An AST ClassDef node
   :return: List of attribute names defined at class level

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


.. py:function:: format_class_docstring(class_def)

   Extract and format the docstring from a ClassDef node.

   :param class_def: An AST ClassDef node
   :return: List of formatted docstring lines (empty list if no docstring)


.. py:function:: get_function_names(class_def)

   Extract names of methods defined in a class.

   :param class_def: An AST ClassDef node
   :return: List of method names defined in the class

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