hakorune/docs/development/roadmap/phases/phase-10.7/python-descriptor-mapping.md

Python Descriptor Protocol → Nyash Property System マッピング

🎯 概要

2025-09-18のProperty System革命により、Python transpilationが飛躍的に向上。Pythonのdescriptor protocolを完全にNyashのProperty System（stored/computed/once/birth_once）にマッピングする設計。

🧬 Pythonプロパティ分類とNyashマッピング

1. 通常フィールド → stored

class PyClass:
    def __init__(self):
        self.name = "example"  # 通常の属性

box PyClass {
    name: StringBox  // stored: 通常のフィールドストレージ
    
    birth() {
        me.name = "example"
    }
}

2. @property → computed

class PyClass:
    @property
    def full_name(self):
        return f"{self.first} {self.last}"

box PyClass {
    first: StringBox
    last: StringBox
    full_name: StringBox { me.first + " " + me.last }  // computed: 毎回計算
}

3. @functools.cached_property → once

import functools

class PyClass:
    @functools.cached_property  
    def expensive_data(self):
        return expensive_computation()

box PyClass {
    once expensive_data: DataBox { expensive_computation() }  // once: 遅延評価＋キャッシュ
}

4. カスタムdescriptor → 判定ロジック

class CustomDescriptor:
    def __get__(self, obj, objtype=None):
        # カスタムロジック
        pass
    
    def __set__(self, obj, value):
        # セットロジック  
        pass

class PyClass:
    custom_prop = CustomDescriptor()

判定ロジック（PythonCompilerBox内）:

box DescriptorAnalyzer {
    analyze_descriptor(descriptor_ast) {
        if descriptor_ast.has_get_only() {
            if descriptor_ast.is_pure_computation() {
                return "computed"  // 副作用なし計算
            } else {
                return "once"      // 副作用あり＝キャッシュ推奨
            }
        }
        
        if descriptor_ast.has_get_and_set() {
            return "stored"        // getterとsetterあり＝通常フィールド
        }
        
        return "unsupported"       // 複雑すぎ→Phase 2以降
    }
}

🎯 自動判定アルゴリズム

Phase 1: 基本パターン認識

def classify_python_property(ast_node):
    # 1. デコレータ解析
    if has_decorator(ast_node, "@property"):
        if is_simple_computation(ast_node.body):
            return "computed"
        else:
            return "once"  # 複雑→キャッシュ推奨
    
    # 2. cached_property検出
    if has_decorator(ast_node, "@functools.cached_property"):
        return "once"
    
    # 3. 通常の__init__内代入
    if is_init_assignment(ast_node):
        return "stored"
    
    # 4. descriptor検出（Phase 2以降）
    if has_custom_descriptor(ast_node):
        return analyze_descriptor_complexity(ast_node)

Phase 2: 高度な判定（将来）

• 副作用解析: I/O、外部状態変更の検出
• コスト解析: 計算量推定による once vs computed 判定
• 依存解析: 他のプロパティとの依存関係

🌟 poison-on-throw統合

Python例外 → Nyash例外処理

class PyClass:
    @functools.cached_property
    def risky_operation(self):
        if random.random() < 0.1:
            raise ValueError("Failed!")
        return expensive_result()

box PyClass {
    once risky_operation: ResultBox { 
        if random_float() < 0.1 {
            throw ValueError("Failed!")
        }
        return expensive_result()
    } catch(ex) {
        poison(me.risky_operation, ex)  // poison-on-throw適用
        throw ex
    }
}

📊 実装フェーズ

Phase 10.7a: 基本認識（1週間）

• @property, @cached_property, 通常フィールドの自動分類
• 単純なcomputedプロパティ生成

Phase 10.7b: 拡張判定（2週間）

• カスタムdescriptor解析
• 副作用検出ロジック
• poison-on-throw統合

Phase 10.7c: 最適化（1週間）

• 依存解析による once vs computed 最適選択
• LLVM最適化との連携

🧪 テストケース

成功パターン

# シンプルcomputed
@property
def area(self): return self.width * self.height  # → computed

# キャッシュ必要
@functools.cached_property  
def heavy_calc(self): return sum(range(1000000))  # → once

# 通常フィールド
def __init__(self): self.name = "test"  # → stored

限界ケース（Phase 2以降）

# 複雑なdescriptor（未対応）
class ComplexDescriptor:
    def __get__(self, obj, objtype=None):
        # 複雑な条件分岐、外部API呼び出し等
        pass

🚀 期待される効果

1. 開発体験: PythonプロパティがNyashで自然に表現
2. 性能向上: LLVMによるproperty最適化（10-50x高速化）
3. 型安全性: NyashのBox型システムによる実行時安全性
4. 保守性: 生成されたNyashコードの可読性・編集可能性

このマッピング設計により、PythonからNyashへの自然で高性能なtranspilationが実現できます！