Docstring Parsing

class NumpyDocString(Mapping):
    """
    Base docstring parser with dictionary-like interface.
    
    Parses NumPy-style docstrings into structured sections like Parameters,
    Returns, Examples, etc. Provides dictionary-like access to sections.
    
    Parameters
    ----------
    docstring : str
        Raw docstring to parse
    config : dict, optional
        Configuration options for parsing behavior
        
    Attributes
    ----------
    sections : dict
        Dictionary mapping section names to parsed content
    """
    
    def __getitem__(self, key: str) -> List[str]:
        """
        Access docstring sections by name.
        
        Parameters
        ---------- 
        key : str
            Section name ('Parameters', 'Returns', 'Examples', etc.)
            
        Returns
        -------
        list of str
            Lines comprising the requested section
        """
    
    def __setitem__(self, key: str, val):
        """
        Set docstring section content.
        
        Parameters
        ----------
        key : str
            Section name ('Parameters', 'Returns', 'Examples', etc.)
        val
            Section content to set
        """
    
    def __contains__(self, key: str) -> bool:
        """Check if section exists in docstring."""
    
    def __iter__(self):
        """Iterate over section names."""
        
    def __len__(self) -> int:
        """Number of sections in docstring."""
        
    def keys(self):
        """Return section names."""
        
    def values(self):
        """Return section contents."""
        
    def items(self):
        """Return (section_name, section_content) pairs."""

class FunctionDoc(NumpyDocString):
    """
    Function-specific docstring parser.
    
    Extends NumpyDocString with function-specific parsing logic,
    handling Parameters, Returns, Yields, and Raises sections with
    proper type annotation support.
    
    Parameters
    ----------
    func : callable
        Function object to parse docstring from
    role : str, optional  
        Sphinx role for cross-references ('func', 'meth', etc.)
    doc : str, optional
        Override docstring (uses func.__doc__ if None)
    config : dict, optional
        Configuration options
    """

class ClassDoc(NumpyDocString):
    """
    Class-specific docstring parser.
    
    Handles class docstrings with support for Attributes sections
    and proper inheritance of docstring sections from parent classes.
    
    Parameters
    ----------
    cls : type
        Class object to parse docstring from
    doc : str, optional
        Override docstring (uses cls.__doc__ if None)  
    modulename : str, optional
        Module name for cross-references
    config : dict, optional
        Configuration options
    """

class ObjDoc(NumpyDocString):
    """
    Generic object docstring parser.
    
    Fallback parser for objects that don't fit function or class
    categories. Handles basic docstring structure without specialized
    section processing.
    
    Parameters
    ----------
    obj : object
        Python object to parse docstring from
    doc : str, optional
        Override docstring (uses obj.__doc__ if None)
    config : dict, optional
        Configuration options
    """

def get_doc_object(obj, what=None, doc=None, config=None, **kwargs):
    """
    Factory function for creating appropriate docstring parsers.
    
    Automatically selects the appropriate parser class based on the
    object type and creates a configured parser instance.
    
    Parameters
    ----------
    obj : object
        Python object to create parser for
    what : str, optional
        Type hint ('function', 'class', 'method', 'module', etc.)
        If None, type is inferred from obj
    doc : str, optional  
        Override docstring (uses obj.__doc__ if None)
    config : dict, optional
        Configuration options to pass to parser
    **kwargs
        Additional arguments passed to parser constructor
        
    Returns
    -------
    NumpyDocString
        Appropriate parser instance (FunctionDoc, ClassDoc, or ObjDoc)
        
    Examples
    --------
    >>> import numpy as np
    >>> doc = get_doc_object(np.array)
    >>> 'Parameters' in doc
    True
    >>> doc['Summary']
    ['Create an array.']
    """

class Reader:
    """
    Line-based string reader for docstring parsing.
    
    Provides file-like interface for reading docstring content
    line by line with support for peeking, seeking, and position tracking.
    
    Parameters
    ----------
    data : str or list of str
        Input data as string or list of lines
        
    Attributes
    ----------
    _l : list of str
        Internal list of lines
    _i : int
        Current position index
    """
    
    def __init__(self, data):
        """Initialize reader with string or line data."""
        
    def __getitem__(self, n: int) -> str:
        """Get line at position n."""
        
    def reset(self):
        """Reset reader position to beginning."""
        
    def read(self) -> str:
        """
        Read and return next line.
        
        Returns
        -------
        str
            Next line or empty string if at end
        """
        
    def seek_next_non_empty_line(self):
        """Advance position to next non-empty line."""
        
    def eof(self) -> bool:
        """Check if at end of input."""
        
    def read_to_condition(self, condition_func):
        """
        Read lines until condition function returns True.
        
        Parameters
        ----------
        condition_func : callable
            Function that takes a line and returns boolean
            
        Returns
        -------
        list of str
            Lines read before condition was met
        """
        
    def read_to_next_empty_line(self) -> List[str]:
        """Read lines until next empty line."""
        
    def read_to_next_unindented_line(self) -> List[str]:
        """Read lines until next unindented line."""

def strip_blank_lines(l: List[str]) -> List[str]:
    """
    Remove blank lines from beginning and end of list.
    
    Parameters
    ----------
    l : list of str
        Input list of lines
        
    Returns
    -------
    list of str
        List with leading/trailing blank lines removed
    """

def dedent_lines(lines: List[str]) -> List[str]:
    """
    Remove common indentation from all lines.
    
    Similar to textwrap.dedent but operates on list of lines
    and preserves relative indentation.
    
    Parameters
    ----------
    lines : list of str
        Input lines with potentially common indentation
        
    Returns
    -------
    list of str
        Lines with common indentation removed
    """

class SphinxDocString(NumpyDocString):
    """
    Sphinx-specific docstring parser.
    
    Extends base parser with Sphinx-specific functionality including
    cross-reference generation, plot directive processing, and
    integration with Sphinx's documentation build system.
    
    Parameters
    ----------
    docstring : str
        Raw docstring to parse
    config : dict, optional
        Sphinx configuration options
    app : sphinx.application.Sphinx, optional
        Sphinx application instance
    what : str, optional
        Object type for Sphinx autodoc  
    name : str, optional
        Fully qualified object name
    obj : object, optional
        The actual Python object
    options : dict, optional
        Sphinx autodoc options
    """

class SphinxFunctionDoc(SphinxDocString, FunctionDoc):
    """
    Sphinx function parser combining Sphinx and function-specific features.
    
    Provides complete function docstring parsing with Sphinx integration
    for cross-references, type linking, and documentation generation.
    """

class SphinxClassDoc(SphinxDocString, ClassDoc):
    """
    Sphinx class parser combining Sphinx and class-specific features.
    
    Handles class docstrings with Sphinx integration including
    member documentation, inheritance handling, and cross-references.
    """

class SphinxObjDoc(SphinxDocString, ObjDoc):
    """
    Sphinx generic object parser with Sphinx integration features.
    
    Fallback parser for objects with Sphinx-specific functionality
    like cross-reference generation and documentation formatting.
    """

def get_doc_object(obj, what=None, doc=None, config=None, builder=None):
    """
    Sphinx-specific factory for creating docstring parsers.
    
    Similar to docscrape.get_doc_object but with Sphinx integration
    and builder-specific configuration handling.
    
    Parameters
    ----------
    obj : object
        Python object to create parser for
    what : str, optional
        Object type hint for Sphinx autodoc
    doc : str, optional
        Override docstring
    config : dict, optional
        Sphinx configuration  
    builder : sphinx.builders.Builder, optional
        Sphinx builder instance
        
    Returns
    -------
    SphinxDocString
        Appropriate Sphinx parser instance
    """

IMPORT_MATPLOTLIB_RE: Pattern[str]
"""Regular expression for detecting matplotlib import statements in examples."""

class ParseError(Exception):
    """
    Exception raised when docstring parsing fails.
    
    Indicates malformed docstring structure or content that
    cannot be properly parsed according to NumPy format rules.
    
    Parameters
    ----------
    msg : str
        Error message describing the parsing failure
    """

from numpydoc.docscrape import NumpyDocString, get_doc_object

# Parse docstring directly
docstring = '''
Summary line.

Parameters
----------  
x : array_like
    Input array
y : float
    Scale factor
    
Returns
-------
ndarray
    Scaled array
'''

doc = NumpyDocString(docstring)
print(doc['Summary'])     # ['Summary line.']
print('Parameters' in doc)  # True

import numpy as np
from numpydoc.docscrape import get_doc_object

# Parse function docstring
doc = get_doc_object(np.array)
print(doc['Parameters'])  # Parsed parameter information
print(doc['Returns'])     # Return value documentation

# Parse class docstring  
doc = get_doc_object(np.ndarray)
print(doc['Attributes'])  # Class attribute documentation

from numpydoc.docscrape_sphinx import get_doc_object

# Create Sphinx-aware parser
config = {'numpydoc_use_plots': True}
doc = get_doc_object(np.fft.fft, config=config)

# Access processed sections ready for Sphinx
sections = doc['Examples']  # Processed with plot directives

from numpydoc.docscrape import Reader

content = '''
Line 1
Line 2

Line 4
'''

reader = Reader(content)
while not reader.eof():
    line = reader.read()
    print(f"Read: {line}")

# Seek operations
reader.reset()
reader.seek_next_non_empty_line()
remaining = reader.read_to_next_empty_line()