tukuy

Subpackages

Submodules

tukuy.base module

class tukuy.base.BaseTransformer(name: str, options: TransformOptions | None = None)

Bases: Generic[T, U], ABC

Description:: Abstract base class for all transformers. Provides common functionality and defines the interface that all transformers must implement.

Version: v1 Status: Production Last Updated: 2024-03-24

Type Parameters:: T: The input type that this transformer accepts U: The output type that this transformer produces

__init__(name: str, options: Optional[TransformOptions] = None): Initialize the transformer with a name and optional configuration.

validate(value: T) -> bool: Validate if the input value is acceptable for this transformer.

transform(value: T, context: Optional[TransformContext] = None) -> TransformResult[U]: Transform the input value according to the transformer’s rules.

_transform(value: T, context: Optional[TransformContext] = None) -> U: Internal transformation method that subclasses must implement.

Example:

class NumberSquareTransformer(BaseTransformer[int, int]):
    def validate(self, value: int) -> bool:
        return isinstance(value, int)

    def _transform(self, value: int, context: Optional[TransformContext] = None) -> int:
        return value * value

transformer = NumberSquareTransformer("square")
result = transformer.transform(5)
assert result.value == 25

__init__(name: str, options: TransformOptions | None = None)

Initialize the transformer.

Parameters:

name – Unique identifier for this transformer
options – Configuration options for this transformer

transform(value: T, context: Dict[str, Any] | None = None, **kwargs) → TransformResult[U]

Public method to transform a value with error handling.

Parameters:

value – The value to transform
context – Optional context data for the transformation
**kwargs – Additional keyword arguments for the transformation

Returns:

TransformResult containing either the transformed value or an error

abstractmethod validate(value: T) → bool

Validate the input value.

Parameters:: value – The value to validate
Returns:: True if valid, False otherwise
Return type:: bool

class tukuy.base.ChainableTransformer(name: str, next_transformer: BaseTransformer | None = None, options: TransformOptions | None = None)

Bases: BaseTransformer[T, U]

Description:: A transformer that can be chained with other transformers. Allows for creating pipelines of transformations where the output of one transformer becomes the input to the next.

Version: v1 Status: Production Last Updated: 2024-03-24

Type Parameters:: T: The input type that this transformer accepts U: The output type that this transformer produces

__init__(name: str, next_transformer: Optional[BaseTransformer] = None, options: Optional[TransformOptions] = None): Initialize the transformer with a name, optional next transformer, and configuration.

chain(next_transformer: BaseTransformer) -> ChainableTransformer: Chain this transformer with another transformer.

transform(value: T, context: Optional[TransformContext] = None) -> TransformResult: Transform the value and pass it through the chain.

Example:

# Create a pipeline that converts text to lowercase then strips whitespace
lowercase = LowercaseTransformer("lowercase")
strip = StripTransformer("strip")

# Chain the transformers
pipeline = lowercase.chain(strip)

# Transform text through the pipeline
result = pipeline.transform("  Hello World  ")
assert result.value == "hello world"

chain(next_transformer: BaseTransformer) → ChainableTransformer

Chain this transformer with another transformer.

Parameters:: next_transformer – The next transformer in the chain
Returns:: self for method chaining

transform(value: T, context: Dict[str, Any] | None = None, **kwargs) → TransformResult

Transform the value and pass it through the chain.

Parameters:

value – The value to transform
context – Optional context data for the transformation
**kwargs – Additional keyword arguments for the transformation

Returns:

TransformResult containing either the final transformed value or an error

class tukuy.base.CompositeTransformer(name: str, transformers: List[BaseTransformer], options: TransformOptions | None = None)

Bases: BaseTransformer[T, U]

Description:: A transformer that combines multiple transformers into a single unit. Useful for creating complex transformations from simpler ones by composing multiple transformers together.

Version: v1 Status: Production Last Updated: 2024-03-24

Type Parameters:: T: The input type that this transformer accepts U: The output type that this transformer produces

__init__(name: str, transformers: List[BaseTransformer], options: Optional[TransformOptions] = None): Initialize the transformer with a name, list of transformers, and optional configuration.

validate(value: Any) -> bool: Validate input through all contained transformers.

_transform(value: Any, context: Optional[TransformContext] = None) -> Any: Apply all transformations in sequence.

Example:

# Create individual transformers
lowercase = LowercaseTransformer("lowercase")
strip = StripTransformer("strip")
slugify = SlugifyTransformer("slugify")

# Combine them into a composite transformer
text_processor = CompositeTransformer(
    "text_processor",
    transformers=[lowercase, strip, slugify]
)

# Process text through all transformers
result = text_processor.transform("  Hello World!  ")
assert result.value == "hello-world"

validate(value: Any) → bool: Validate input through all contained transformers.

class tukuy.base.CoreToolsTransformer

Bases: BaseTransformer[Any, Any]

Description:: Coordinates the application of multiple transformations using existing transformers. This transformer takes a value and a list of transform operations, creates the appropriate transformers, and chains them together to produce the final result.

Version: v1 Status: Production Last Updated: 2024-03-24

Supported Operations:

regex:: pattern (str): Regular expression pattern to match template (Optional[str]): Optional template for formatting matches
replace:: find (str): Text to find replace (str): Text to replace with
average:: Calculates the average of a list of numbers

Returns:

The transformed value after applying all operations

Return type:

Any

Raises:

ValidationError – If an unknown transform function is specified or if input validation fails
TransformationError – If any transformation operation fails

Example:

transformer = CoreToolsTransformer()

# Apply multiple transformations
transforms = [
    {
        'function': 'regex',
        'pattern': r'(\d+)',
        'template': 'Number: {1}'
    },
    {
        'function': 'replace',
        'find': 'Number',
        'replace': 'Value'
    }
]

result = transformer.transform("Age: 25", transforms)
assert result.value == "Value: 25"

# Calculate average
numbers = [1, 2, 3, 4, 5]
transforms = [{'function': 'average'}]
result = transformer.transform(numbers, transforms)
assert result.value == 3.0

validate(value: Any) → bool

Validate the input value.

Parameters:: value – The value to validate
Returns:: True if valid, False otherwise
Return type:: bool

class tukuy.base.RegexTransformer(name: str, pattern: str, template: str | None = None)

Bases: ChainableTransformer[str, str]

Description:: A transformer that applies a regular expression pattern to text and optionally formats the result using a template.

Version: v1 Status: Production Last Updated: 2024-03-24

Parameters:

name (str) – Unique identifier for this transformer
pattern (str) – Regular expression pattern to match against the input text
template (Optional[str]) – Optional template for formatting the matched groups. Use {1}, {2}, etc. to reference captured groups.

Returns:

The transformed text after applying the regex pattern and template

Return type:

str

Raises:

ValidationError – If the input value is not a string
TransformationError – If the regex pattern is invalid

Example:

# Extract and format a date
transformer = RegexTransformer(
    "date_format",
    pattern=r"(\d{4})-(\d{2})-(\d{2})",
    template="{2}/{3}/{1}"  # MM/DD/YYYY
)

result = transformer.transform("Date: 2024-03-24")
assert result.value == "03/24/2024"

# Simple pattern matching without template
finder = RegexTransformer(
    "find_email",
    pattern=r"[\w\.-]+@[\w\.-]+\.\w+"
)

result = finder.transform("Contact: user@example.com")
assert result.value == "user@example.com"

validate(value: str) → bool

Validate the input value.

Parameters:: value – The value to validate
Returns:: True if valid, False otherwise
Return type:: bool

class tukuy.base.ReplaceTransformer(name: str, old: str, new: str)

Bases: ChainableTransformer[str, str]

Description:: A transformer that replaces all occurrences of a specified text with new text.

Version: v1 Status: Production Last Updated: 2024-03-24

Parameters:

name (str) – Unique identifier for this transformer
old (str) – The text to find and replace
new (str) – The text to replace with

Returns:

The text with all occurrences of old replaced with new

Return type:

str

Raises:

ValidationError – If the input value is not a string

Example:

# Replace specific text
transformer = ReplaceTransformer(
    "fix_typo",
    old="teh",
    new="the"
)

result = transformer.transform("teh quick brown fox")
assert result.value == "the quick brown fox"

# Chain with other transformers
capitalize = UppercaseTransformer("uppercase")
pipeline = transformer.chain(capitalize)

result = pipeline.transform("teh quick brown fox")
assert result.value == "THE QUICK BROWN FOX"

validate(value: str) → bool

Validate the input value.

Parameters:: value – The value to validate
Returns:: True if valid, False otherwise
Return type:: bool

tukuy.exceptions module

exception tukuy.exceptions.ConfigurationError(message: str, value: Any = None)

Bases: TransformerError

Raised when transformer configuration is invalid.

exception tukuy.exceptions.ExtractorError(message: str, value: Any = None)

Bases: TransformerError

Raised when data extraction fails.

exception tukuy.exceptions.ParseError(message: str, value: Any = None)

Bases: TransformerError

Raised when parsing operations fail.

exception tukuy.exceptions.PatternError(message: str, value: Any = None)

Bases: TransformerError

Raised when a pattern is invalid or malformed.

exception tukuy.exceptions.TransformationError(message: str, value: Any = None, transformer_name: str | None = None)

Bases: TransformerError

Raised when a transformation operation fails.

exception tukuy.exceptions.TransformerError(message: str, value: Any = None)

Bases: Exception

Base exception class for all transformer-related errors.

exception tukuy.exceptions.ValidationError(message: str, value: Any = None)

Bases: TransformerError

Raised when input validation fails.

tukuy.types module

tukuy.types