Metadata-Version: 2.5
Name: lb
Version: 0.0.5
Summary: utils for ipython importing
Project-URL: Homepage, https://github.com/t-c-w/lb
Project-URL: Repository, https://github.com/t-c-w/lb
Author: t-c-w
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: import,importlib,ipython,modules,utils
Classifier: Framework :: IPython
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# lb
utils for ipython importing

To install:	```pip install lb```

## Overview
The `lb` package provides utility functions primarily aimed at simplifying the import process in Python, particularly useful in interactive environments like IPython. It includes functionality to handle environment variables, dynamically import modules from strings, and retrieve specific objects from modules using dot notation paths.

## Features

### Environment Variable Handling
- **`get_environment_variable(var, ignore=True)`**: Fetches the value of an environment variable. If the variable is not set and `ignore` is `True`, it issues a warning and returns a placeholder string. If `ignore` is `False`, it raises a `RuntimeError`.

### Dynamic Module Import
- **`module_import_from_string(import_path_string, params_file, verbose=False)`**: Imports a module based on a path to a Python file. This function is particularly useful when the module to be imported is not in the standard Python path. It allows for specifying the module dynamically by its path.

### Object Retrieval from Dot String
- **`import_from_dot_string(dot_string)`**: Allows importing a specific object from a module using a dot notation string. This is useful for accessing deeply nested objects without importing the entire module hierarchy.

## Usage Examples

### Getting Environment Variables
```python
from lb import get_environment_variable

# Attempt to get an environment variable that might not be set
db_host = get_environment_variable('DB_HOST')
print(db_host)  # Output depends on whether 'DB_HOST' is set or not
```

### Importing Modules Dynamically
```python
from lb import module_import_from_string

# Dynamically import a module from a specific file
module_path = '/path/to/your/module.py'
imported_module = module_import_from_string('your_package', module_path)
print(imported_module)  # The imported module object
```

### Importing Objects Using Dot Strings
```python
from lb import import_from_dot_string

# Import a specific object from a module
path_join = import_from_dot_string('os.path.join')
print(path_join)  # <function join at ...>

# You can also import submodules
path_module = import_from_dot_string('os.path')
print(path_module)  # <module 'posixpath' from ...>
```

## Function Documentation

### `get_environment_variable(var, ignore=True)`
Fetches and returns the value of the specified environment variable. If the variable is not set and `ignore` is `True`, it issues a warning and returns a message indicating the missing variable. If `ignore` is `False`, it raises a `RuntimeError` to signal the error more forcefully.

### `module_import_from_string(import_path_string, params_file, verbose=False)`
Imports a module given the path to its file. If the file ends with `.py`, it is treated as a Python script; otherwise, it assumes the file name without an extension and appends `.py` to it. If `verbose` is `True`, prints the paths being used for the import. This function handles import errors by adding the directory to `sys.path` and retrying the import.

### `import_from_dot_string(dot_string)`
Imports and returns an object specified by a dot notation string. This can be a module, a function, a class, or any other object within a module. The function splits the dot string, imports the relevant module, and then retrieves the specified object from that module. If the dot string refers to a module directly, it imports and returns the module.