kiarina-utils-common 1.35.0__tar.gz

kiarina_utils_common-1.35.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+dist/
+build/
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# uv
+.uv_cache/
+
+# Virtual environments & config
+.venv/
+.env
+
+# OS
+.DS_Store
+
+# Project specific
+*.log
+tmp/
+packages/*/test_settings.yaml
+
+# Test data
+tests/data/large/
+
+# mise tasks (always include)
+!mise-tasks/
+!mise-tasks/**

kiarina_utils_common-1.35.0/.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

kiarina_utils_common-1.35.0/CHANGELOG.md

@@ -0,0 +1,294 @@
+# Changelog
+
+All notable changes to the kiarina-utils-common package will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.35.0] - 2026-01-31
+
+### Changed
+- No changes
+
+## [1.34.0] - 2026-01-31
+
+### Changed
+- No changes
+
+## [1.33.1] - 2026-01-31
+
+### Changed
+- No changes
+
+## [1.33.0] - 2026-01-31
+
+### Changed
+- No changes
+
+## [1.32.0] - 2026-01-30
+
+### Changed
+- No changes
+
+## [1.31.1] - 2026-01-29
+
+### Changed
+- No changes
+
+## [1.31.0] - 2026-01-29
+
+### Changed
+- No changes
+
+## [1.30.0] - 2026-01-27
+
+### Changed
+- No changes
+
+## [1.29.0] - 2026-01-16
+
+### Changed
+- No changes
+
+## [1.28.0] - 2026-01-16
+
+### Changed
+- No changes
+
+## [1.27.0] - 2026-01-12
+
+### Changed
+- No changes
+
+## [1.26.0] - 2026-01-09
+
+### Changed
+- No changes
+
+## [1.25.1] - 2026-01-08
+
+### Changed
+- No changes
+
+## [1.25.0] - 2026-01-08
+
+### Changed
+- No changes
+
+## [1.24.0] - 2026-01-08
+
+### Changed
+- No changes
+
+## [1.23.0] - 2026-01-06
+
+### Changed
+- No changes
+
+## [1.22.1] - 2026-01-06
+
+### Changed
+- No changes
+
+## [1.22.0] - 2026-01-05
+
+### Changed
+- No changes
+
+## [1.21.1] - 2026-01-05
+
+### Changed
+- No changes
+
+## [1.21.0] - 2025-12-30
+
+### Changed
+- No changes
+
+## [1.20.1] - 2025-12-25
+
+### Changed
+- No changes
+
+## [1.20.0] - 2025-12-19
+
+### Changed
+- No changes
+
+## [1.19.0] - 2025-12-19
+
+### Changed
+- No changes
+
+## [1.18.2] - 2025-12-17
+
+### Changed
+- No changes
+
+## [1.18.1] - 2025-12-16
+
+### Changed
+- No changes
+
+## [1.18.0] - 2025-12-16
+
+### Changed
+- No changes
+
+## [1.17.0] - 2025-12-15
+
+### Changed
+- No changes
+
+## [1.16.0] - 2025-12-15
+
+### Changed
+- No changes
+
+## [1.15.1] - 2025-12-14
+
+### Changed
+- No changes
+
+## [1.15.0] - 2025-12-13
+
+### Changed
+- No changes
+
+## [1.14.0] - 2025-12-13
+
+### Changed
+- No changes
+
+## [1.13.0] - 2025-12-09
+
+### Changed
+- No changes
+
+## [1.12.0] - 2025-12-05
+
+### Changed
+- No changes
+
+## [1.11.2] - 2025-12-02
+
+### Added
+- `ConfigStr` type alias for configuration string format documentation
+
+## [1.11.1] - 2025-12-01
+
+### Changed
+- No changes
+
+## [1.11.0] - 2025-12-01
+
+### Changed
+- No changes
+
+## [1.10.0] - 2025-12-01
+
+### Added
+- `import_object` function for dynamic object importing from import paths (useful for plugin systems)
+
+## [1.9.0] - 2025-11-26
+
+### Changed
+- No changes
+
+## [1.8.0] - 2025-10-24
+
+### Changed
+- No changes
+
+## [1.7.0] - 2025-10-21
+
+### Changed
+- No changes
+
+## [1.6.3] - 2025-10-13
+
+### Changed
+- No changes
+
+## [1.6.2] - 2025-10-10
+
+### Changed
+- No changes
+
+## [1.6.1] - 2025-10-10
+
+### Changed
+- No changes
+
+## [1.6.0] - 2025-10-10
+
+### Changed
+- No changes
+
+## [1.5.0] - 2025-10-10
+
+### Changed
+- No changes
+
+## [1.4.0] - 2025-10-09
+
+### Changed
+- No changes
+
+## [1.3.0] - 2025-10-05
+
+### Changed
+- No changes
+
+## [1.2.0] - 2025-09-25
+
+### Changed
+- No changes
+
+## [1.1.1] - 2025-09-11
+
+### Changed
+- No changes
+
+## [1.1.0] - 2025-09-11
+
+### Changed
+- No changes
+
+## [1.0.1] - 2025-09-11
+
+### Changed
+- No changes - version bump for consistency with other packages
+
+## [1.0.0] - 2025-09-09
+
+### Added
+- Comprehensive README.md with usage examples and API documentation
+- Enhanced pyproject.toml with proper metadata, classifiers, and project URLs
+- CHANGELOG.md for tracking version changes
+
+### Changed
+- Improved package documentation and metadata
+
+## [0.1.0] - 2025-01-09
+
+### Added
+- Initial release of kiarina-utils-common
+- `parse_config_string` function for parsing configuration strings
+- Support for nested keys using dot notation
+- Support for array indices in configuration strings
+- Automatic type conversion (bool, int, float, str)
+- Flag support (keys without values)
+- Customizable separators for different parsing needs
+- Comprehensive test suite with pytest
+- Type hints and py.typed marker for full typing support
+
+### Features
+- Parse configuration strings like `"cache.enabled:true,db.port:5432"`
+- Support for nested structures: `{"cache": {"enabled": True}, "db": {"port": 5432}}`
+- Array index support: `"items.0:first,items.1:second"` → `{"items": ["first", "second"]}`
+- Flag functionality: `"debug,verbose"` → `{"debug": None, "verbose": None}`
+- Custom separators: configurable item, key-value, and nested separators
+- Automatic type detection and conversion for common data types

kiarina_utils_common-1.35.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: kiarina-utils-common
+Version: 1.35.0
+Summary: Common utility functions for the kiarina namespace packages
+Project-URL: Homepage, https://github.com/kiarina/kiarina-python
+Project-URL: Repository, https://github.com/kiarina/kiarina-python
+Project-URL: Issues, https://github.com/kiarina/kiarina-python/issues
+Project-URL: Changelog, https://github.com/kiarina/kiarina-python/blob/main/packages/kiarina-utils-common/CHANGELOG.md
+Project-URL: Documentation, https://github.com/kiarina/kiarina-python/tree/main/packages/kiarina-utils-common#readme
+Author-email: kiarina <kiarinadawa@gmail.com>
+Maintainer-email: kiarina <kiarinadawa@gmail.com>
+License-Expression: MIT
+Keywords: common,config,parser,utilities
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# kiarina-utils-common
+
+[![PyPI version](https://badge.fury.io/py/kiarina-utils-common.svg)](https://badge.fury.io/py/kiarina-utils-common)
+[![Python](https://img.shields.io/pypi/pyversions/kiarina-utils-common.svg)](https://pypi.org/project/kiarina-utils-common/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Common utility functions for the kiarina namespace packages.
+
+## Installation
+
+```bash
+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.
+
+```python
+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.
+
+```python
+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"]}
+
+# 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:
+
+```python
+config = parse_config_string("database.host:localhost,database.port:5432")
+# Result: {"database": {"host": "localhost", "port": 5432}}
+```
+
+#### Array Indices
+
+Use numeric keys for array structures:
+
+```python
+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:**
+
+```python
+# 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=".")`
+
+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: `"."`
+
+**Returns:**
+- `dict[str, Any]`: Parsed configuration dictionary
+
+**Examples:**
+
+```python
+# 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}
+
+# 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](../../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](../kiarina-utils-file/): File operation utilities
+- [kiarina-llm](../kiarina-llm/): LLM-related utilities

kiarina_utils_common-1.35.0/README.md

@@ -0,0 +1,170 @@
+# kiarina-utils-common
+
+[![PyPI version](https://badge.fury.io/py/kiarina-utils-common.svg)](https://badge.fury.io/py/kiarina-utils-common)
+[![Python](https://img.shields.io/pypi/pyversions/kiarina-utils-common.svg)](https://pypi.org/project/kiarina-utils-common/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Common utility functions for the kiarina namespace packages.
+
+## Installation
+
+```bash
+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.
+
+```python
+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.
+
+```python
+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"]}
+
+# 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:
+
+```python
+config = parse_config_string("database.host:localhost,database.port:5432")
+# Result: {"database": {"host": "localhost", "port": 5432}}
+```
+
+#### Array Indices
+
+Use numeric keys for array structures:
+
+```python
+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:**
+
+```python
+# 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=".")`
+
+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: `"."`
+
+**Returns:**
+- `dict[str, Any]`: Parsed configuration dictionary
+
+**Examples:**
+
+```python
+# 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}
+
+# 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](../../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](../kiarina-utils-file/): File operation utilities
+- [kiarina-llm](../kiarina-llm/): LLM-related utilities