Implementation:Apache Paimon ConfigOption Python

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

Overview

ConfigOption provides a type-safe, immutable representation of configuration parameters with keys, types, default values, and optional descriptions for Apache Paimon's configuration system.

Description

The ConfigOption class encapsulates all metadata about a single configuration parameter: the configuration key string, the expected value type (clazz), an optional description for documentation, and an optional default value. Once created, a ConfigOption instance is immutable, ensuring configuration definitions remain consistent throughout the application lifecycle.

The class uses Python's Generic type system to maintain type safety, with the type parameter T representing the configuration value type. This enables type-checked access to configuration values and allows static analysis tools to verify correct usage. The description is represented by a Description dataclass built through a DescriptionBuilder, supporting structured documentation.

ConfigOption provides query methods like has_default_value() and default_value() for inspecting default values, key() and get_clazz() for accessing metadata, and with_description() for creating new ConfigOption instances with updated descriptions. The class implements __eq__() and __hash__() based on key and default value, enabling use in sets and dictionaries. ConfigOptions are typically created through the ConfigOptions builder API rather than direct instantiation, following the builder pattern for clean, fluent configuration definition.

Usage

Use ConfigOption when defining configuration parameters for Paimon components, creating type-safe configuration schemas, or building configuration validation and documentation systems.

Code Reference

Source Location

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

Signature

@dataclass(frozen=True)
class Description:
    """Configuration option description."""
    text: str

    @staticmethod
    def builder() -> 'DescriptionBuilder':
        pass

class DescriptionBuilder:
    """Builder for Description objects."""

    def __init__(self):
        pass

    def text(self, text: str) -> 'DescriptionBuilder':
        pass

    def build(self) -> Description:
        pass

T = TypeVar('T')

class ConfigOption(Generic[T]):
    """
    A ConfigOption describes a configuration parameter. It encapsulates the configuration
    key, deprecated older versions of the key, and an optional default value for the configuration
    parameter.
    """

    EMPTY_DESCRIPTION = Description(text="")

    def __init__(self,
                 key: str,
                 clazz: Type,
                 description: Optional[Description] = None,
                 default_value: Any = None):
        pass

    def key(self) -> str:
        pass

    def get_clazz(self) -> Type:
        pass

    def description(self) -> Description:
        pass

    def has_default_value(self) -> bool:
        pass

    def default_value(self) -> Any:
        pass

    def with_description(self, description: Union[str, Description]) -> 'ConfigOption':
        pass

Import

from pypaimon.common.options.config_option import ConfigOption, Description, DescriptionBuilder

I/O Contract

Inputs

Name	Type	Required	Description
key	str	Yes	Configuration key name
clazz	Type	Yes	Expected value type
description	Description	No	Configuration description for documentation
default_value	Any	No	Default value (None if no default)

Outputs

Name	Type	Description
config_option	ConfigOption	Immutable configuration option instance
key	str	Configuration key
has_default	bool	Whether a default value is defined
default	Any	Default value or None

Usage Examples

from pypaimon.common.options.config_option import ConfigOption, Description

# Create a config option directly (usually done through ConfigOptions)
option = ConfigOption(
    key="table.write.buffer-size",
    clazz=str,
    description=Description(text="Buffer size for write operations"),
    default_value="256mb"
)

# Access option metadata
print(option.key())  # "table.write.buffer-size"
print(option.get_clazz())  # <class 'str'>
print(option.description().text)  # "Buffer size for write operations"
print(option.has_default_value())  # True
print(option.default_value())  # "256mb"

# Create option without default value
no_default_option = ConfigOption(
    key="table.path",
    clazz=str,
    description=Description(text="Table storage path"),
    default_value=None
)
print(no_default_option.has_default_value())  # False
print(no_default_option.default_value())  # None

# Add description to existing option
described = option.with_description("Enhanced description for buffer size")
print(described.description().text)  # "Enhanced description for buffer size"
print(described.key())  # Still "table.write.buffer-size"

# Build description with builder
desc = Description.builder() \
    .text("Number of parallel compaction threads") \
    .build()

compaction_option = ConfigOption(
    key="compaction.threads",
    clazz=int,
    description=desc,
    default_value=4
)

# Equality based on key and default
option1 = ConfigOption(key="test.key", clazz=str, default_value="value1")
option2 = ConfigOption(key="test.key", clazz=str, default_value="value1")
option3 = ConfigOption(key="test.key", clazz=str, default_value="value2")

print(option1 == option2)  # True (same key and default)
print(option1 == option3)  # False (different default)

# Use in dictionary
config_options = {
    option1: "configured_value",
    compaction_option: 8
}

# String representation
print(str(option))
# "key: 'table.write.buffer-size'; default_value: 256mb"

# Type-safe configuration definition
from typing import Generic, TypeVar

T = TypeVar('T')

def create_typed_option(key: str, default: T) -> ConfigOption[T]:
    return ConfigOption(
        key=key,
        clazz=type(default),
        description=ConfigOption.EMPTY_DESCRIPTION,
        default_value=default
    )

int_option: ConfigOption[int] = create_typed_option("max.retries", 3)
str_option: ConfigOption[str] = create_typed_option("catalog.name", "default")

Related Pages

• Principle:Apache_Paimon_Utility_Infrastructure