trulens.core.utils.imports¶

trulens.core.utils.imports ¶

Import utilities for required and optional imports.

Utilities for importing python modules and optional importing.

Attributes¶

required_packages `module-attribute` ¶

required_packages: Dict[str, Requirement] = (
    _requirements_of_trulens_core_file(
        "utils/requirements.txt"
    )
)

Mapping of required package names to the requirement object with info about that requirement including version constraints.

optional_packages `module-attribute` ¶

optional_packages: Dict[str, Requirement] = (
    _requirements_of_trulens_core_file(
        "utils/requirements.optional.txt"
    )
)

Mapping of optional package names to the requirement object with info about that requirement including version constraints.

all_packages `module-attribute` ¶

all_packages: Dict[str, Requirement] = {
    None: required_packages,
    None: optional_packages,
}

Mapping of optional and required package names to the requirement object with info about that requirement including version constraints.

Classes¶

VersionConflict ¶

Bases: Exception

Exception to raise when a version conflict is found in a required package.

ImportErrorMessages `dataclass` ¶

Container for messages to show when an optional package is not found or has some other import error.

Attributes¶

module_not_found `instance-attribute` ¶

module_not_found: str

Message to show or raise when a package is not found.

import_error `instance-attribute` ¶

import_error: str

Message to show or raise when a package may be installed but some import error occurred trying to import it or something from it.

Dummy ¶

Bases: type

Class to pretend to be a module or some other imported object.

Will raise an error if accessed in some dynamic way. Accesses that are "static-ish" will try not to raise the exception so things like defining subclasses of a missing class should not raise exception. Dynamic uses are things like calls, use in expressions. Looking up an attribute is static-ish so we don't throw the error at that point but instead make more dummies.

Warning

While dummies can be used as types, they return false to all isinstance and issubclass checks. Further, the use of a dummy in subclassing produces unreliable results with some of the debugging information such as original_exception may be inaccessible.

Functions¶

instancecheck ¶

__instancecheck__(__instance: Any) -> bool

Nothing is an instance of this dummy.

Warning

This is to make sure that if something optional gets imported as a dummy and is a class to be instrumented, it will not automatically make the instrumentation class check succeed on all objects.

subclasscheck ¶

__subclasscheck__(__subclass: type) -> bool

Nothing is a subclass of this dummy.

OptionalImports ¶

Helper context manager for doing multiple imports from an optional modules

Example

    messages = ImportErrorMessages(
        module_not_found="install llama_index first",
        import_error="install llama_index==0.1.0"
    )
    with OptionalImports(messages=messages):
        import llama_index
        from llama_index import query_engine

The above python block will not raise any errors but once anything else about llama_index or query_engine gets accessed, an error is raised with the specified message (unless llama_index is installed of course).

Functions¶

assert_installed ¶

assert_installed(mods: Union[Any, Iterable[Any]])

Check that the given modules mods are not dummies. If any is, show the optional requirement message.

Returns self for chaining convenience.

init ¶

__init__(messages: ImportErrorMessages, fail: bool = False)

Create an optional imports context manager class. Will keep module not found or import errors quiet inside context unless fail is True.

enter ¶

__enter__()

Handle entering the WithOptionalImports context block.

We override the builtins.import function to catch any import errors.

exit ¶

__exit__(exc_type, exc_value, exc_tb)

Handle exiting from the WithOptionalImports context block.

We should not get any exceptions here if dummies were produced by the overwritten import but if an import of a module that exists failed becomes some component of that module did not, we will not be able to catch it to produce dummy and have to process the exception here in which case we add our informative message to the exception and re-raise it.

Functions¶

safe_importlib_package_name ¶

safe_importlib_package_name(package_name: str) -> str

Convert a package name that may have periods in it to one that uses hyphens for periods but only if the python version is old.

static_resource ¶

static_resource(
    namespace: str, filepath: Union[Path, str]
) -> Path

Get the path to a static resource file in the trulens package.

By static here we mean something that exists in the filesystem already and not in some temporary folder. We use the importlib.resources context managers to get this but if the resource is temporary, the result might not exist by the time we return or is not expected to survive long.

parse_version ¶

parse_version(version_string: str) -> Version

Parse the version string into a packaging version object.

get_package_version ¶

get_package_version(name: str) -> Optional[Version]

Get the version of a package by its name.

Returns None if given package is not installed.

is_package_installed ¶

is_package_installed(name: str) -> bool

Check if a package is installed.

check_imports ¶

check_imports(ignore_version_mismatch: bool = False)

Check required and optional package versions. Args: ignore_version_mismatch: If set, will not raise an error if a version mismatch is found in a required package. Regardless of this setting, mismatch in an optional package is a warning. Raises: VersionConflict: If a version mismatch is found in a required package and ignore_version_mismatch is not set.

pin_spec ¶

pin_spec(r: Requirement) -> Requirement

Pin the requirement to the version assuming it is lower bounded by a version.

format_import_errors ¶

format_import_errors(
    packages: Union[str, Sequence[str]],
    purpose: Optional[str] = None,
    throw: Union[bool, Exception] = False,
) -> ImportErrorMessages

Format two messages for missing optional package or bad import from an optional package.

Throws an ImportError with the formatted message if throw flag is set. If throw is already an exception, throws that instead after printing the message.

is_dummy ¶

is_dummy(obj: Any) -> bool

Check if the given object is an instance of Dummy.

This is necessary as isisintance and issubclass checks might fail if the ones defined in Dummy get used; they always return False by design.

trulens.core.utils.imports¶