Implementation:Apache Paimon OptionsUtils Python

Knowledge Sources	Apache_Paimon
Domains	Configuration, Type Conversion
Last Updated	2026-02-08 00:00 GMT

Overview

OptionsUtils provides utility methods for converting configuration values between different types including primitives, durations, memory sizes, and enums with intelligent string parsing.

Description

The OptionsUtils class centralizes type conversion logic for configuration values, handling the complexity of converting between string representations (as typically stored in configuration files) and strongly-typed Python objects. It supports conversions to common types (str, bool, int, float), specialized Paimon types (MemorySize, timedelta), and user-defined Enum types.

The convert_value() method serves as the main entry point, dispatching to specialized conversion methods based on the target type. It handles None values gracefully and checks if a value already matches the target type before attempting conversion. For Enum conversions, it supports both case-insensitive value matching and name-based lookup, providing flexible string-to-enum mapping.

String parsing is particularly robust: boolean conversion recognizes multiple formats ('true', '1', 'yes', 'on' for True; 'false', '0', 'no', 'off' for False), numeric conversions handle both string and numeric inputs, MemorySize parsing supports human-readable formats like "256mb", and duration parsing uses parse_duration() to handle various time formats. The utility methods throw informative ValueError exceptions when conversions fail, enabling proper error handling in configuration loading.

Usage

Use OptionsUtils when implementing configuration loaders that need to convert string values to typed objects, validating user-provided configuration values, or building configuration systems with automatic type coercion.

Code Reference

Source Location

• Repository: Apache_Paimon
• File: paimon-python/pypaimon/common/options/options_utils.py

Signature

class OptionsUtils:
    """Utility methods for options conversion and validation."""

    @staticmethod
    def convert_value(value: Any, target_type: Type) -> Any:
        pass

    @staticmethod
    def convert_to_string(value: Any) -> str:
        pass

    @staticmethod
    def convert_to_boolean(value: Any) -> bool:
        pass

    @staticmethod
    def convert_to_int(value: Any) -> int:
        pass

    @staticmethod
    def convert_to_long(value: Any) -> int:
        pass

    @staticmethod
    def convert_to_double(value: Any) -> float:
        pass

    @staticmethod
    def convert_to_memory_size(value: Any) -> MemorySize:
        pass

    @staticmethod
    def convert_to_duration(value: Any) -> timedelta:
        pass

    @staticmethod
    def convert_to_enum(value: Any, enum_class: Type[Enum]) -> Enum:
        pass

Import

from pypaimon.common.options.options_utils import OptionsUtils

I/O Contract

Inputs

Name	Type	Required	Description
value	Any	Yes	Value to convert
target_type	Type	Yes	Target type for conversion
enum_class	Type[Enum]	Yes	Enum class for enum conversion

Outputs

Name	Type	Description
converted	Any	Value converted to target type

Usage Examples

from pypaimon.common.options.options_utils import OptionsUtils
from pypaimon.common.memory_size import MemorySize
from datetime import timedelta
from enum import Enum

# String conversions
result = OptionsUtils.convert_to_string(123)
print(result)  # "123"

result = OptionsUtils.convert_to_string(True)
print(result)  # "True"

# Boolean conversions (flexible string parsing)
print(OptionsUtils.convert_to_boolean("true"))  # True
print(OptionsUtils.convert_to_boolean("TRUE"))  # True
print(OptionsUtils.convert_to_boolean("1"))  # True
print(OptionsUtils.convert_to_boolean("yes"))  # True
print(OptionsUtils.convert_to_boolean("false"))  # False
print(OptionsUtils.convert_to_boolean("0"))  # False
print(OptionsUtils.convert_to_boolean(1))  # True (numeric)

# Integer conversions
print(OptionsUtils.convert_to_int("42"))  # 42
print(OptionsUtils.convert_to_int("  100  "))  # 100 (whitespace stripped)
print(OptionsUtils.convert_to_int(3.14))  # 3 (truncated)

# Float conversions
print(OptionsUtils.convert_to_double("3.14"))  # 3.14
print(OptionsUtils.convert_to_double(5))  # 5.0

# MemorySize conversions
mem = OptionsUtils.convert_to_memory_size("512mb")
print(mem.get_mebi_bytes())  # 512

mem = OptionsUtils.convert_to_memory_size("2gb")
print(mem.get_gibi_bytes())  # 2

# Duration conversions
duration = OptionsUtils.convert_to_duration("30s")
print(duration.total_seconds())  # 30.0

duration = OptionsUtils.convert_to_duration("5m")
print(duration.total_seconds())  # 300.0

# Enum conversions
class LogLevel(Enum):
    DEBUG = "debug"
    INFO = "info"
    WARNING = "warning"
    ERROR = "error"

# Case-insensitive value matching
level = OptionsUtils.convert_to_enum("INFO", LogLevel)
print(level)  # LogLevel.INFO

level = OptionsUtils.convert_to_enum("debug", LogLevel)
print(level)  # LogLevel.DEBUG

# General conversion with target type
result = OptionsUtils.convert_value("true", bool)
print(result)  # True

result = OptionsUtils.convert_value("256mb", MemorySize)
print(result.get_mebi_bytes())  # 256

result = OptionsUtils.convert_value("warning", LogLevel)
print(result)  # LogLevel.WARNING

# Handle None values
result = OptionsUtils.convert_value(None, str)
print(result)  # None

# Already correct type (no conversion)
mem = MemorySize.of_mebi_bytes(128)
result = OptionsUtils.convert_value(mem, MemorySize)
assert result is mem  # Same object returned

# Error handling
try:
    OptionsUtils.convert_to_boolean("maybe")
except ValueError as e:
    print(f"Conversion error: {e}")

try:
    OptionsUtils.convert_to_int("not a number")
except ValueError as e:
    print(f"Conversion error: {e}")

class Color(Enum):
    RED = "red"
    BLUE = "blue"

try:
    OptionsUtils.convert_to_enum("green", Color)
except ValueError as e:
    print(f"Invalid enum value: {e}")

# Use in configuration system
def load_config(raw_config: dict, expected_types: dict):
    typed_config = {}
    for key, raw_value in raw_config.items():
        target_type = expected_types.get(key, str)
        typed_config[key] = OptionsUtils.convert_value(raw_value, target_type)
    return typed_config

raw = {
    "enabled": "true",
    "timeout": "30s",
    "buffer_size": "256mb",
    "max_retries": "5"
}

types = {
    "enabled": bool,
    "timeout": timedelta,
    "buffer_size": MemorySize,
    "max_retries": int
}

config = load_config(raw, types)
print(config["enabled"])  # True (bool)
print(config["max_retries"])  # 5 (int)

Related Pages

• Principle:Apache_Paimon_Utility_Infrastructure