sg-metacore 0.1.0a0

A sophisticated type system enhancement library for metaprogramming and runtime behavior modification

metacore

⚠️ EARLY ALPHA WARNING: This library is in early development and the API may change significantly between versions. Use at your own risk in production environments.

A sophisticated type system enhancement library for Python metaprogramming and runtime behavior modification.

Overview

metacore bridges the gap between static type hints and runtime behavior by making types first-class citizens in the runtime environment. It provides powerful tools for:

• Immutable constant namespaces with automatic type coercion
• Extensible type annotation processing via registry pattern
• Enhanced exception handling with formatted tracebacks
• Runtime type validation and conversion

Features

ConstantNamespace

Create immutable constant namespaces with automatic type coercion at class definition time:

from metacore.meta.classes.constants import ConstantNamespace
import pathlib

class MyConstants(ConstantNamespace):
    # Regular attributes (not annotated) are not constants
    A = 1

    # Annotated attributes become immutable constants
    B: int = 2
    C: int = 3.4  # Coerced to 3

    # Advanced type coercion
    path: pathlib.Path = "documents/test.txt"  # Coerced to Path object
    numbers: list[int] = [1, 1.5, 3]  # Coerced to [1, 1, 3]

# Access constants
print(MyConstants.B)  # 2
print(MyConstants.path)  # PosixPath('documents/test.txt')

# Modification is prevented
MyConstants.C = 10  # Raises ConstantsModificationError

# Dict-like interface
MyConstants.items()  # [('B', 2), ('C', 3), ...]
MyConstants.keys()   # ('B', 'C', 'path', 'numbers')
MyConstants.get('B', default=0)  # 2

Type Annotation Processing

Extensible registry-based type processing system:

from metacore.meta.typing_utilities.annotations_processors.processors import (
    annotation_registry,
    ValidationLevel
)

registry = annotation_registry()

# Convert values to match type annotations
result = registry.convert_to_annotation(list[int], ("42", 4.2))  # Returns [42, 4]

# Register custom type handlers
@registry.register_processor(MyCustomType)
def process_custom_type(value, annotation):
    # Custom conversion logic
    return MyCustomType(value)

Enhanced Exceptions

All library exceptions inherit from TracedException for better debugging:

from metacore.abstract.exceptions.traced_exceptions import TracedException

class MyError(TracedException):
    """Custom exception with formatted traceback"""
    pass

Installation

pip install metacore

Requirements

• Python 3.12 or higher

Development Status

This library is in active alpha development. The current focus is on refactoring the annotation processing system into a modular architecture. Breaking changes may occur between minor versions.

Roadmap

tbd

Contributing

This is an early-stage project. Contributions, bug reports, and feedback are welcome but please be aware of the alpha status.

License

MIT License - see LICENSE file for details.

Author

Sébastien Gachoud

---

Note: Some code and tests were developed with assistance from Claude AI.