mobject-klixz 0.1.0

A dynamic python base object.

MObject: A Python Base Object for Nested Property Management and Type-Safe Object Handling

Overview

MObject is an abstract base class designed to provide a robust framework for handling nested properties, translating keys, and managing types efficiently in Python projects. It offers utilities for working with complex object hierarchies, nested key mappings, and type-safe property assignment while supporting serialization to dictionaries. In addition, the base provides features for calculator interfaces.

Naming Convention for Properties

MObject uses a specific naming convention for property annotations to aid in type handling and key translation:

• _k: Indicates a configuration key.
• _i: Indicates an input properties.
• _r: Indicates a result property.

This convention makes it easier to manage and validate properties dynamically while maintaining clear code semantics.

Key Features

• Nested Property Management: Access and modify nested object properties dynamically using dot-notation.
• Type-Safe Property Handling: Automatically validate and set properties based on their type annotations.
• Key Translation: Translate camel-case keys to snake_case for internal use and vice versa for external representation.
• Serialization: Convert objects to dictionaries, supporting complex types like lists, dictionaries, NumPy arrays, and Enums.
• Flexible Initialization: Configure initialization using build orders and custom mappings.
• Enum Management: Seamlessly handle Enums with support for string and integer values.
• Logging Support: Provides a logging interface to track issues and warnings.

Installation

Clone this repository and ensure you have Python 3.11 or later installed. Then, install the required dependencies:

pip install -r requirements.txt

Usage

Defining a Subclass

Create a subclass of MObject to leverage its functionality. Annotate properties using Python's type hints for automatic type inference and validation.

from typing import List, Dict
from enum import Enum

class Status(Enum):
    ACTIVE = 1
    INACTIVE = 0

class MyObject(MObject):
    _name_k: str
    _age_i: int
    _attributes_r: Dict[str, float]
    _status_k: Status

    def __init__(self, **kwargs):
        super().__init__(**kwargs)

Creating an Instance

You can create an instance of your subclass using camelcase keyword arguments:

obj = MyObject(Name="Example", Age=25, Attributes={"height": 5.9}, Status=Status.ACTIVE)

Accessing and Setting Nested Properties

Retrieve and modify nested properties dynamically:

# Get a nested property
nested_value = obj.get_nested_property(["attributes", "height"])

# Set a nested property
obj.set_nested_property(["attributes", "weight"], 70.5)

Serializing to a Dictionary

Convert the object to a dictionary representation:

obj_dict = obj.to_dict()
print(obj_dict)

Translating Keys

MObject automatically translates camel-case keys to snake_case for internal use and vice versa:

# Input keys (external)
print(obj.InputKeys)

# Result keys (external)
print(obj.ResultKeys)

Enum Handling

Set enum values dynamically:

status = MyObject.set_enum("active", Status)
print(status)  # Output: Status.ACTIVE

API Reference

Methods

get_nested_property(obj, props, serializable=False)

Recursively retrieves a nested property from an object.

set_nested_property(obj, props, val, translate=False)

Recursively sets a nested property on an object.

set_enum(val, enum)

Converts a string, integer, or Enum instance into a valid Enum instance.

set(cls, val)

Creates an instance of the class from a dictionary or another instance of the same class.

collect_annotations(cls)

Collects type annotations from the class and its base classes.

to_dict()

Serializes the object into a dictionary, supporting various data types.

Properties

InputKeys

List of translated input keys.

ResultKeys

List of translated result keys.

ClassName

Returns the name of the class.

Logging

The framework uses Python's logging module. You can configure the logger named mobject to control the log level and output format:

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger('mobject')

Examples

Example 1: Simple Object

class SimpleObject(MObject):
    value_k: int
    description_i: str

obj = SimpleObject(value=42, description="A simple example.")
print(obj.to_dict())

Example 2: Nested Properties

class NestedObject(MObject):
    metadata_k: Dict[str, Any]

nested = NestedObject(metadata={"info": {"author": "John Doe", "version": 1.0}})
print(nested.get_nested_property(["metadata", "info", "author"]))  # Output: John Doe

Contributing

Contributions are welcome! Please submit issues or pull requests to enhance the functionality or fix bugs.

License

This project is licensed under the MIT License.

Acknowledgments

Special thanks to the Python community for the powerful tools and libraries that make this possible.