hbllmutils.meta.code.source

This module provides functionality for analyzing Python source files and their import statements.

It extracts information about imports, source code structure, and object inspection details from Python source files. The module can parse import statements, resolve imported objects, and provide comprehensive metadata about the source file and its dependencies.

Main components:

• ImportSource: Dataclass containing import statement and object inspection information

• SourceInfo: Dataclass containing comprehensive source file information

• get_source_info: Function to analyze and extract information from a Python source file

ImportSource

class hbllmutils.meta.code.source.ImportSource(statement: FromImportStatement | ImportStatement, inspect: ObjectInspect)

Represents an import statement along with its corresponding object inspection information.

This dataclass pairs an import statement (either a from-import or regular import) with the inspection details of the imported object, providing a complete view of both the import syntax and the actual imported object’s metadata.

Parameters:

• statement (Union[FromImportStatement, ImportStatement]) – The import statement (either FromImportStatement or ImportStatement).

• inspect (ObjectInspect) – The inspection information of the imported object.

Example::

>>> stmt = FromImportStatement(module='os', name='path', level=0)
>>> obj_info = get_object_info(os.path)
>>> import_src = ImportSource(statement=stmt, inspect=obj_info)
>>> print(import_src.statement)
from os import path
>>> print(import_src.inspect.name)
'path'

SourceInfo

class hbllmutils.meta.code.source.SourceInfo(source_file: str, source_lines: List[str], imports: List[ImportSource])

Contains comprehensive information about a Python source file.

This dataclass stores the source file path, its content as lines, and information about all imports found in the file. It provides a complete snapshot of a Python source file’s structure and dependencies.

Parameters:

• source_file (str) – The path to the source file.

• source_lines (List[str]) – List of source code lines from the file.

• imports (List[ImportSource]) – List of import sources found in the file.

Example::

>>> info = SourceInfo(
...     source_file='/path/to/module.py',
...     source_lines=['import os\n', 'from typing import List\n'],
...     imports=[]
... )
>>> print(info.source_file)
'/path/to/module.py'
>>> print(info.source_code)
import os
from typing import List

__post_init__()

Post-initialization processing to normalize the source file path.

Converts the source file path to an absolute, normalized, and case-normalized path to ensure consistency across different platforms and path representations. This is automatically called after the dataclass is initialized.

Example::

>>> info = SourceInfo(source_file='./relative/path.py', source_lines=[], imports=[])
>>> # source_file is now normalized to absolute path
>>> os.path.isabs(info.source_file)
True

property package_name: str

Get the package name of the source file.

This property derives the Python package name from the source file’s path by analyzing its location relative to the Python path root.

Returns:

The package name derived from the source file path.

Return type:

str

Example::

>>> # For a file at /project/mypackage/submodule/file.py
>>> info = SourceInfo(source_file='/project/mypackage/submodule/file.py', 
...                   source_lines=[], imports=[])
>>> info.package_name
'mypackage.submodule.file'

property source_code: str

Get the complete source code as a single string.

This property concatenates all source lines into a single string, preserving the original line endings and formatting.

Returns:

The concatenated source code from all lines.

Return type:

str

Example::

>>> info = SourceInfo(
...     source_file='test.py',
...     source_lines=['import os\n', 'print("hello")\n'],
...     imports=[]
... )
>>> print(info.source_code)
import os
print("hello")

get_source_info

hbllmutils.meta.code.source.get_source_info(source_file: str, skip_when_error: bool = False) → SourceInfo

Analyze a Python source file and extract comprehensive information about it.

This function reads the source file, parses its import statements, and attempts to inspect the imported objects. It returns a SourceInfo object containing all the extracted information including source code, imports, and object metadata.

The function works by:

1. Reading the source file content

2. Parsing import statements using AST analysis

3. Determining the Python path and package name

4. Dynamically importing and inspecting each imported object

5. Collecting all information into a SourceInfo object

Parameters:

• source_file (str) – The path to the Python source file to analyze.

• skip_when_error (bool) – If True, skip imports that fail to load and issue warnings instead of raising exceptions. Defaults to False.

Returns:

A SourceInfo object containing the source file information and imports.

Return type:

SourceInfo

Raises:

Exception – If an import fails to load and skip_when_error is False.

Warns ImportWarning:

If an import fails to load and skip_when_error is True.

Example::

>>> # Analyze a simple module
>>> info = get_source_info('mymodule.py')
>>> print(info.package_name)
'mypackage.mymodule'
>>> print(len(info.imports))
5
>>> print(info.source_code[:50])
'import os\nimport sys\nfrom typing import List\n...'

>>> # Skip errors when analyzing problematic imports
>>> info = get_source_info('module_with_issues.py', skip_when_error=True)
>>> # Warnings will be issued for failed imports, but processing continues