hbllmutils.meta.code.pypi

Python module metadata and PyPI package information utilities.

This module provides comprehensive functionality for analyzing Python modules and determining their origin, type, and PyPI package information. It can distinguish between built-in modules, standard library modules, and third-party packages, and retrieve associated metadata such as package names and versions.

The module contains the following main components:

PyPIModuleInfo - Data class containing module metadata and type information
get_module_info() - Main function to retrieve comprehensive module information
is_standard_library() - Utility to determine if a module is from the standard library
get_pypi_info() - Utility to extract PyPI package name and version information

Note

This module uses multiple fallback mechanisms to ensure robust package detection across different Python versions and installation methods.

Warning

Module analysis may fail for dynamically loaded modules or modules with non-standard installation paths.

Example:

>>> from hbllmutils.meta.code.pypi import get_module_info
>>>
>>> # Analyze a built-in module
>>> info = get_module_info('sys')
>>> print(f"Type: {info.type}, Module: {info.module_name}")
Type: builtin, Module: sys
>>>
>>> # Analyze a third-party package
>>> info = get_module_info('requests')
>>> if info and info.is_third_party:
...     print(f"PyPI: {info.pypi_name}, Version: {info.version}")
PyPI: requests, Version: 2.28.0

pkg_resources

hbllmutils.meta.code.pypi.pkg_resources = None

PyPIModuleInfo

class hbllmutils.meta.code.pypi.PyPIModuleInfo(type: Literal['builtin', 'standard', 'third_party'], module_name: str, pypi_name: str | None, location: str | None, version: str | None)[source]

Data class containing comprehensive information about a Python module.

This class encapsulates all relevant metadata about a Python module including its type (builtin, standard library, or third-party), location, and PyPI package information if applicable.

Parameters:

type (Literal['builtin', 'standard', 'third_party']) – Classification of the module type
module_name (str) – The import name of the module
pypi_name (Optional[str]) – The PyPI package name if it’s a third-party module, None otherwise
location (Optional[str]) – File system path to the module, None for built-in modules
version (Optional[str]) – Version string of the package, None if not available

Variables:

type (Literal['builtin', 'standard', 'third_party']) – Module classification type
module_name (str) – Module import name
pypi_name (Optional[str]) – PyPI package name
location (Optional[str]) – Module file path
version (Optional[str]) – Package version

Example:

>>> info = PyPIModuleInfo(
...     type='third_party',
...     module_name='requests',
...     pypi_name='requests',
...     location='/usr/lib/python3.10/site-packages/requests/__init__.py',
...     version='2.28.0'
... )
>>> print(info.is_third_party)
True

property is_third_party: bool

Check if the module is a third-party package.

Returns:: True if the module is a third-party package, False otherwise
Return type:: bool

Example:

>>> info = PyPIModuleInfo(type='third_party', module_name='numpy',
...                       pypi_name='numpy', location=None, version='1.21.0')
>>> info.is_third_party
True
>>>
>>> builtin_info = PyPIModuleInfo(type='builtin', module_name='sys',
...                               pypi_name=None, location=None, version=None)
>>> builtin_info.is_third_party
False

get_module_info

hbllmutils.meta.code.pypi.get_module_info(module_name: str) → PyPIModuleInfo | None[source]

Get detailed information about a module including its type and PyPI package name.

This function analyzes a Python module to determine its classification (builtin, standard library, or third-party), location, and associated PyPI package information. It handles various edge cases and uses multiple fallback mechanisms for robust detection.

Parameters:: module_name (str) – The name of the module to analyze
Returns:: Module information object containing all metadata, or None if analysis fails
Return type:: Optional[PyPIModuleInfo]

Note

The function first checks if the module is built-in, then attempts to import it to determine its location and type. For third-party packages, it retrieves PyPI metadata using multiple detection methods.

Warning

If the module cannot be imported or analyzed, a warning is issued and None is returned.

Example:

>>> # Analyze a standard library module
>>> info = get_module_info('json')
>>> print(f"Type: {info.type}")
Type: standard
>>>
>>> # Analyze a third-party module
>>> info = get_module_info('numpy')
>>> if info:
...     print(f"PyPI: {info.pypi_name}, Version: {info.version}")
PyPI: numpy, Version: 1.21.0
>>>
>>> # Handle non-existent module
>>> info = get_module_info('nonexistent_module')
>>> print(info)
None

is_standard_library

hbllmutils.meta.code.pypi.is_standard_library(module_path: str | Path) → bool[source]

Check if a module is part of the Python standard library.

This function determines whether a given module path belongs to the Python standard library by comparing it against known standard library locations. It handles both Unix-like and Windows systems, and excludes site-packages directories to avoid false positives.

Parameters:: module_path (Path) – Resolved file system path to the module
Returns:: True if the module is part of the standard library, False otherwise
Return type:: bool

Note

The function checks multiple potential standard library locations including both sys.prefix and sys.base_prefix to handle virtual environments correctly.

Warning

Modules in site-packages directories are explicitly excluded even if they reside within standard library paths.

Example:

>>> from pathlib import Path
>>> import json
>>>
>>> # Check a standard library module
>>> json_path = Path(json.__file__).resolve()
>>> is_standard_library(json_path)
True
>>>
>>> # Check a third-party module
>>> import requests
>>> requests_path = Path(requests.__file__).resolve()
>>> is_standard_library(requests_path)
False

get_pypi_info

hbllmutils.meta.code.pypi.get_pypi_info(module_name: str) → Tuple[str | None, str | None][source]

Get PyPI package name and version for a third-party module.

This function attempts to retrieve the PyPI package name and version for a given module using multiple detection strategies. It tries pkg_resources first, then falls back to importlib.metadata (Python 3.8+), and finally attempts to read the __version__ attribute from the module itself.

Parameters:: module_name (str) – The name of the module to look up
Returns:: Tuple containing (pypi_name, version), where either or both may be None
Return type:: tuple[Optional[str], Optional[str]]

Note

The function uses multiple fallback mechanisms to maximize compatibility across different Python versions and package installation methods.

Warning

Some packages may not be detected if they don’t follow standard naming conventions or lack proper metadata.

Example:

>>> # Get info for a well-known package
>>> pypi_name, version = get_pypi_info('requests')
>>> print(f"Package: {pypi_name}, Version: {version}")
Package: requests, Version: 2.28.0
>>>
>>> # Handle package with different module name
>>> pypi_name, version = get_pypi_info('PIL')
>>> print(f"Package: {pypi_name}")
Package: Pillow
>>>
>>> # Handle unknown package
>>> pypi_name, version = get_pypi_info('unknown_module')
>>> print(f"Package: {pypi_name}, Version: {version}")
Package: None, Version: None