kiarina-utils-common 1.37.0

Common utility functions for the kiarina namespace packages

kiarina-utils-common

Common utility functions for the kiarina namespace packages.

Installation

pip install kiarina-utils-common

Features

Dynamic Object Import

Import objects (classes, functions, constants) dynamically from import paths. Useful for plugin systems and dynamic loading scenarios.

from kiarina.utils.common import import_object

# Import a function
parse_fn = import_object("kiarina.utils.common:parse_config_string")
result = parse_fn("key=value")

# Import a class
MyClass = import_object("myapp.plugins:MyPlugin")
instance = MyClass()

# Import with type hints for better IDE support
from typing import Callable
parser: Callable = import_object("kiarina.utils.common:parse_config_string")

Configuration String Parser

Parse configuration strings into nested dictionaries with automatic type conversion.

from kiarina.utils.common import parse_config_string

# Basic usage
config = parse_config_string("cache.enabled=true&db.port=5432")
# Result: {"cache": {"enabled": True}, "db": {"port": 5432}}

# Flag support (no value)
config = parse_config_string("debug&verbose&cache.enabled=true")
# Result: {"debug": None, "verbose": None, "cache": {"enabled": True}}

# Array indices support
config = parse_config_string("items.0=first&items.1=second")
# Result: {"items": ["first", "second"]}

# Bracketed values (atomic, no type conversion)
config = parse_config_string("vad=(mock?sample_rate=16000&p.0=1.0)&top_k=3")
# Result: {"vad": "mock?sample_rate=16000&p.0=1.0", "top_k": 3}

# Custom separators
config = parse_config_string(
    "key1:val1;key2.sub:42",
    separator=";",
    key_value_separator=":",
)
# Result: {"key1": "val1", "key2": {"sub": 42}}

Type Conversion

Values are automatically converted to appropriate types:

• "true", "True" → bool(True)
• "false", "False" → bool(False)
• Numeric strings ("1", "0", "-5", "3.14") → int or float
• Other strings → str

Nested Keys

Use dot notation for nested structures:

config = parse_config_string("database.host=localhost&database.port=5432")
# Result: {"database": {"host": "localhost", "port": 5432}}

Array Indices

Use numeric keys for array structures:

config = parse_config_string("users.0.name=Alice&users.0.age=30&users.1.name=Bob")
# Result: {"users": [{"name": "Alice", "age": 30}, {"name": "Bob"}]}

API Reference

import_object(import_path)

Import and return an object from an import path.

Parameters:

• import_path (str): Import path in the format 'module_name:object_name'
  • Example: 'kiarina.utils.common:parse_config_string'

Returns:

• The imported object (class, function, or any other object)

Raises:

• ValueError: If import_path format is invalid
• ImportError: If the module cannot be imported
• AttributeError: If the object doesn't exist in the module

Examples:

# Import a function
parse_fn = import_object('kiarina.utils.common:parse_config_string')
result = parse_fn('key=value')

# Import a class
MyClass = import_object('myapp.plugins:MyPlugin')
instance = MyClass()

# Use with type hints
from typing import Callable
parser: Callable = import_object('kiarina.utils.common:parse_config_string')

parse_config_string(config_str, *, separator="&", key_value_separator="=", nested_separator=".", brackets="()")

Parse configuration string into nested dictionary.

Parameters:

• config_str (str): Configuration string to parse
• separator (str, optional): Item separator. Default: "&"
• key_value_separator (str, optional): Key-value separator. Default: "="
• nested_separator (str, optional): Nested key separator. Default: "."
• brackets (str, optional): Two-character open/close pair for quoting values that contain separator characters. Default: "()". Pass "" to disable.

Returns:

• dict[str, Any]: Parsed configuration dictionary

Examples:

# Basic usage
parse_config_string("key1=value1&key2=value2")
# {"key1": "value1", "key2": "value2"}

# Nested keys
parse_config_string("cache.enabled=true&db.port=5432")
# {"cache": {"enabled": True}, "db": {"port": 5432}}

# Flags (no value)
parse_config_string("debug&verbose")
# {"debug": None, "verbose": None}

# Bracketed values (verbatim, type-conversion suppressed)
parse_config_string("k=(a&b=c)&n=5")
# {"k": "a&b=c", "n": 5}

# Custom separators
parse_config_string("a:1;b:2", separator=";", key_value_separator=":")
# {"a": 1, "b": 2}

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

This is a personal project by kiarina. While issues and pull requests are welcome, please note that this is primarily developed for personal use.

Related Packages

• kiarina-utils-file: File operation utilities
• kiarina-llm: LLM-related utilities