hbllmutils.meta.code.module

This module provides utilities for extracting Python module paths from source files.

It analyzes the file system structure to determine the appropriate PYTHONPATH and module import path for a given Python source file by traversing up the directory tree to find the package root (identified by the absence of __init__.py).

The module contains functions to: - Determine the package root directory (PYTHONPATH) for a given source file - Convert file paths to Python module import paths - Resolve relative and absolute imports to their full module names

get_package_name

hbllmutils.meta.code.module.get_package_name(source_file: str, pythonpath_dir: str | None = None) → str[source]

Convert a source file path to its corresponding Python module name.

This function calculates the relative path from the PYTHONPATH directory to the source file, removes the file extension, and converts the path separators to dots to form a valid Python module import path. If the file is named __init__.py, it represents the package itself, so the last segment is removed.

Parameters:

source_file (str) – The absolute or relative path to the Python source file.
pythonpath_dir (Optional[str]) – The PYTHONPATH directory (package root) to calculate relative path from. If not provided, it will be automatically determined.

Returns:

The Python module import path (e.g., ‘package.subpackage.module’).

Return type:

str

Example::

>>> get_package_name('/path/to/project/package/module.py', '/path/to/project')
'package.module'

>>> get_package_name('/path/to/project/package/__init__.py', '/path/to/project')
'package'

>>> get_package_name('C:\project\pkg\subpkg\file.py', 'C:\project')
'pkg.subpkg.file'

get_pythonpath_of_source_file

hbllmutils.meta.code.module.get_pythonpath_of_source_file(source_file: str) → Tuple[str, str][source]

Get the PYTHONPATH directory and module import path for a given Python source file.

This function traverses up the directory tree from the source file location until it finds a directory without an __init__.py file, which is considered the package root. It then calculates the relative module path that can be used for imports.

Parameters:: source_file (str) – The path to the Python source file.
Returns:: A tuple containing the module directory (PYTHONPATH) and the module import path.
Return type:: Tuple[str, str]

Example::

>>> get_pythonpath_of_source_file('/path/to/project/package/subpackage/module.py')
('/path/to/project', 'package.subpackage.module')

>>> get_pythonpath_of_source_file('/path/to/standalone_script.py')
('/path/to', 'standalone_script')

get_package_from_import

hbllmutils.meta.code.module.get_package_from_import(source_file: str, import_: str) → str[source]

Resolve an import statement to its full module name, handling both absolute and relative imports.

This function takes a source file path and an import string, and resolves it to the full absolute module path. For absolute imports (not starting with a dot), it returns the import string as-is. For relative imports (starting with one or more dots), it resolves the import relative to the source file’s package location.

Parameters:

source_file (str) – The path to the Python source file where the import occurs.
import (str) – The import string to resolve (e.g., ‘.module’, ‘..package.module’, ‘absolute.module’).

Returns:

The fully resolved absolute module import path.

Return type:

str

Example::

>>> get_package_from_import('/path/to/project/pkg/subpkg/file.py', 'external.module')
'external.module'

>>> get_package_from_import('/path/to/project/pkg/subpkg/file.py', '.sibling')
'pkg.subpkg.sibling'

>>> get_package_from_import('/path/to/project/pkg/subpkg/__init__.py', '.sibling')
'pkg.subpkg.sibling'

>>> get_package_from_import('/path/to/project/pkg/subpkg/file.py', '..parent_module')
'pkg.parent_module'