hbllmutils.meta.code.object

This module provides utilities for inspecting Python objects and retrieving their source code information.

It includes functionality to extract source file paths, line numbers, and source code for various Python objects such as functions, classes, and methods. The module is particularly useful for code analysis, documentation generation, and debugging purposes.

ObjectInspect

class hbllmutils.meta.code.object.ObjectInspect(object: Any, source_file: str | None, start_line: int | None, end_line: int | None, source_lines: List[str] | None)[source]

A dataclass that encapsulates inspection information about a Python object.

This class stores metadata about a Python object including its source file location, line numbers, and source code. It provides convenient properties to access and manipulate this information.

Parameters:

object (Any) – The Python object being inspected.
source_file (Optional[str]) – The absolute path to the source file containing the object, or None if unavailable.
start_line (Optional[int]) – The starting line number of the object in the source file, or None if unavailable.
end_line (Optional[int]) – The ending line number of the object in the source file, or None if unavailable.
source_lines (Optional[List[str]]) – A list of source code lines for the object, or None if unavailable.

__post_init__()[source]

Normalize and convert the source file path to an absolute path after initialization.

This method is automatically called after the dataclass is initialized. It ensures that the source_file path is normalized, case-normalized, and converted to an absolute path for consistency across different platforms.

property has_source: bool

Check whether source code lines are available for the inspected object.

Returns:: True if source lines are available, False otherwise.
Return type:: bool

Example::

>>> info = get_object_info(print)  # Built-in function
>>> info.has_source
False
>>> def custom_func():
...     pass
>>> info = get_object_info(custom_func)
>>> info.has_source
True

property name: str | None

Get the name of the inspected object.

Returns:: The name of the object if it has a ‘__name__’ attribute, otherwise None.
Return type:: Optional[str]

Example::

>>> def example_func():
...     pass
>>> info = get_object_info(example_func)
>>> info.name
'example_func'

property package_name: str | None

Get the package name containing the inspected object.

This property retrieves the package name by analyzing the source file path. It relies on the get_package_name function from the module utility.

Returns:: The package name if the source file is available, otherwise None.
Return type:: Optional[str]

Example::

>>> # Assuming the object is from package 'mypackage'
>>> info = get_object_info(some_function)
>>> info.package_name
'mypackage'

property source_code: str | None

Get the source code of the inspected object.

Returns:: The complete source code as a string if available, otherwise None.
Return type:: Optional[str]

Example::

>>> def example_func():
...     return 42
>>> info = get_object_info(example_func)
>>> print(info.source_code)
def example_func():
    return 42

property source_file_code: str | None

Get the complete source code of the file containing the inspected object.

Returns:: The entire file content as a string if the source file is available, otherwise None.
Return type:: Optional[str]

Example::

>>> info = get_object_info(some_function)
>>> file_content = info.source_file_code  # Gets entire file content

get_object_info

hbllmutils.meta.code.object.get_object_info(obj: Any) → ObjectInspect[source]

Retrieve comprehensive inspection information about a Python object.

This function attempts to extract source file location, line numbers, and source code for the given object. If any information is unavailable (e.g., for built-in objects), the corresponding fields will be set to None.

Parameters:: obj (Any) – The Python object to inspect (function, class, method, etc.).
Returns:: An ObjectInspect instance containing all available inspection information.
Return type:: ObjectInspect

Example::

>>> def example_function():
...     '''A simple example function.'''
...     return "Hello, World!"
>>> info = get_object_info(example_function)
>>> info.name
'example_function'
>>> info.has_source
True
>>> print(info.source_code)  
def example_function():
    '''A simple example function.'''
    return "Hello, World!"

>>> # Built-in objects have limited information
>>> info = get_object_info(print)
>>> info.has_source
False
>>> info.source_file is None
True