1from typing import TypeVar
 2
 3class Animal:
 4    def speak(self) -> str:
 5        return "..."
 6
 7class Dog(Animal):
 8    def speak(self) -> str:
 9        return "Woof!"
10
11class Cat(Animal):
12    def speak(self) -> str:
13        return "Meow!"
14
15# T 必須是 Animal 或其子類別
16T = TypeVar("T", bound=Animal)
17
18def make_speak(animal: T) -> str:
19    return animal.speak()  # 型別檢查器知道 animal 有 speak() 方法
20
21# 正確使用
22make_speak(Dog())  # OK
23make_speak(Cat())  # OK
24
25# 錯誤使用
26make_speak("not an animal")  # 型別錯誤

1from typing import TypeVar
2
3# 方式一：bound - T 可以是 Animal 或任何子類別
4T_bound = TypeVar("T_bound", bound=Animal)
5
6# 方式二：限制型別 - T 只能是 Dog 或 Cat，不能是其他 Animal 子類別
7T_constrained = TypeVar("T_constrained", Dog, Cat)

 1class Animal:
 2    pass
 3
 4class Dog(Animal):
 5    pass
 6
 7# 問題：List[Dog] 是 List[Animal] 的子型別嗎？
 8def process_animals(animals: list[Animal]) -> None:
 9    animals.append(Animal())  # 如果傳入 list[Dog]，這會破壞型別安全
10
11dogs: list[Dog] = [Dog(), Dog()]
12process_animals(dogs)  # 如果允許，dogs 裡面會有 Animal！

 1from typing import TypeVar, Generic, Iterator
 2
 3T_co = TypeVar("T_co", covariant=True)
 4
 5class ReadOnlyBox(Generic[T_co]):
 6    """只能讀取，不能修改"""
 7    def __init__(self, value: T_co) -> None:
 8        self._value = value
 9
10    def get(self) -> T_co:
11        return self._value
12
13# ReadOnlyBox[Dog] 是 ReadOnlyBox[Animal] 的子型別
14def show_animal(box: ReadOnlyBox[Animal]) -> None:
15    print(box.get())
16
17dog_box: ReadOnlyBox[Dog] = ReadOnlyBox(Dog())
18show_animal(dog_box)  # OK - Dog 是 Animal

 1from typing import TypeVar, Generic
 2
 3T_contra = TypeVar("T_contra", contravariant=True)
 4
 5class Handler(Generic[T_contra]):
 6    """處理器：只接收值"""
 7    def handle(self, value: T_contra) -> None:
 8        print(f"Handling: {value}")
 9
10# Handler[Animal] 是 Handler[Dog] 的子型別！（反直覺）
11def setup_dog_handler(handler: Handler[Dog]) -> None:
12    handler.handle(Dog())
13
14animal_handler: Handler[Animal] = Handler()
15setup_dog_handler(animal_handler)  # OK - 能處理 Animal 就能處理 Dog

 1from typing import Callable
 2
 3# Callable 的參數是逆變的，返回值是協變的
 4# Callable[[Animal], Dog] 是 Callable[[Dog], Animal] 的子型別
 5
 6def process(func: Callable[[Dog], Animal]) -> None:
 7    result = func(Dog())
 8    print(result)
 9
10def any_animal_to_dog(animal: Animal) -> Dog:
11    return Dog()
12
13process(any_animal_to_dog)  # OK

 1from typing import TypeVar, Generic, Optional
 2
 3T = TypeVar("T")
 4
 5class Stack(Generic[T]):
 6    """型別安全的堆疊"""
 7
 8    def __init__(self) -> None:
 9        self._items: list[T] = []
10
11    def push(self, item: T) -> None:
12        self._items.append(item)
13
14    def pop(self) -> Optional[T]:
15        if self._items:
16            return self._items.pop()
17        return None
18
19    def peek(self) -> Optional[T]:
20        if self._items:
21            return self._items[-1]
22        return None
23
24# 使用
25int_stack: Stack[int] = Stack()
26int_stack.push(1)
27int_stack.push(2)
28int_stack.push("three")  # 型別錯誤！
29
30str_stack: Stack[str] = Stack()
31str_stack.push("hello")

 1from typing import TypeVar, Generic
 2
 3K = TypeVar("K")
 4V = TypeVar("V")
 5
 6class Pair(Generic[K, V]):
 7    """鍵值對"""
 8
 9    def __init__(self, key: K, value: V) -> None:
10        self.key = key
11        self.value = value
12
13    def swap(self) -> "Pair[V, K]":
14        return Pair(self.value, self.key)
15
16# 使用
17pair: Pair[str, int] = Pair("age", 25)
18swapped: Pair[int, str] = pair.swap()

 1from typing import TypeVar, Generic
 2
 3T = TypeVar("T")
 4
 5class Container(Generic[T]):
 6    def __init__(self, value: T) -> None:
 7        self.value = value
 8
 9# 方式一：保持泛型
10class Box(Container[T]):
11    def unwrap(self) -> T:
12        return self.value
13
14# 方式二：具體化型別
15class StringBox(Container[str]):
16    def upper(self) -> str:
17        return self.value.upper()

 1from typing import Protocol
 2
 3class Drawable(Protocol):
 4    def draw(self) -> str:
 5        ...
 6
 7# 這個類別沒有繼承 Drawable，但符合 Protocol
 8class Circle:
 9    def draw(self) -> str:
10        return "○"
11
12class Square:
13    def draw(self) -> str:
14        return "□"
15
16def render(shape: Drawable) -> None:
17    print(shape.draw())
18
19render(Circle())  # OK - Circle 有 draw() 方法
20render(Square())  # OK - Square 有 draw() 方法

 1from abc import ABC, abstractmethod
 2from typing import Protocol, runtime_checkable
 3
 4# ABC 方式
 5class DrawableABC(ABC):
 6    @abstractmethod
 7    def draw(self) -> str:
 8        ...
 9
10class CircleABC(DrawableABC):  # 必須繼承
11    def draw(self) -> str:
12        return "○"
13
14# Protocol 方式
15@runtime_checkable
16class DrawableProtocol(Protocol):
17    def draw(self) -> str:
18        ...
19
20class CircleProtocol:  # 不需要繼承
21    def draw(self) -> str:
22        return "○"
23
24# 執行期檢查
25print(isinstance(CircleProtocol(), DrawableProtocol))  # True

 1# 使用 Protocol 的情況：
 2
 3# 1. 處理第三方類別
 4class JSONSerializable(Protocol):
 5    def to_json(self) -> str:
 6        ...
 7
 8# 第三方類別可能已經有 to_json()，不需要修改它們
 9
10# 2. 定義回調介面
11class EventHandler(Protocol):
12    def on_event(self, event: dict) -> None:
13        ...
14
15# 任何有 on_event 方法的類別或函式都可以使用
16
17# 3. 鬆散耦合
18class Closeable(Protocol):
19    def close(self) -> None:
20        ...
21
22def cleanup(resource: Closeable) -> None:
23    resource.close()
24
25# 檔案、連接、任何有 close() 的東西都可以用

 1from typing import Protocol
 2
 3class Named(Protocol):
 4    name: str  # 只需要有這個屬性
 5
 6class Person:
 7    def __init__(self, name: str) -> None:
 8        self.name = name
 9
10class Company:
11    name: str = "Acme Corp"
12
13def greet(entity: Named) -> str:
14    return f"Hello, {entity.name}!"
15
16greet(Person("Alice"))  # OK
17greet(Company())        # OK

 1from typing import TypeVar, Generic, Protocol, Optional
 2from abc import abstractmethod
 3
 4# 定義實體必須有 id 屬性
 5class HasId(Protocol):
 6    id: int
 7
 8# 泛型 Repository 介面
 9T = TypeVar("T", bound=HasId)
10
11class Repository(Generic[T]):
12    """資料存取層的抽象介面"""
13
14    @abstractmethod
15    def get(self, id: int) -> Optional[T]:
16        """根據 ID 取得實體"""
17        ...
18
19    @abstractmethod
20    def save(self, entity: T) -> T:
21        """儲存實體"""
22        ...
23
24    @abstractmethod
25    def delete(self, id: int) -> bool:
26        """刪除實體"""
27        ...
28
29    @abstractmethod
30    def find_all(self) -> list[T]:
31        """取得所有實體"""
32        ...
33
34# 具體實現
35class User:
36    def __init__(self, id: int, name: str) -> None:
37        self.id = id
38        self.name = name
39
40class InMemoryUserRepository(Repository[User]):
41    """記憶體中的 User Repository"""
42
43    def __init__(self) -> None:
44        self._storage: dict[int, User] = {}
45        self._next_id = 1
46
47    def get(self, id: int) -> Optional[User]:
48        return self._storage.get(id)
49
50    def save(self, entity: User) -> User:
51        if entity.id == 0:
52            entity.id = self._next_id
53            self._next_id += 1
54        self._storage[entity.id] = entity
55        return entity
56
57    def delete(self, id: int) -> bool:
58        if id in self._storage:
59            del self._storage[id]
60            return True
61        return False
62
63    def find_all(self) -> list[User]:
64        return list(self._storage.values())
65
66# 使用
67def process_user(repo: Repository[User], user_id: int) -> None:
68    user = repo.get(user_id)
69    if user:
70        print(f"Found user: {user.name}")
71
72# 型別安全：不能把 UserRepository 傳給需要 Repository[Product] 的函式

1# 錯誤
2T = TypeVar()  # TypeError
3
4# 正確
5T = TypeVar("T")

 1T = TypeVar("T")
 2
 3class Box(Generic[T]):
 4    # 錯誤：方法內重新定義 T
 5    def transform(self, func: Callable[[T], T]) -> T:
 6        T2 = TypeVar("T2")  # 這是不同的 TypeVar！
 7        ...
 8
 9    # 正確：直接使用類別的 T
10    def transform(self, func: Callable[[T], T]) -> T:
11        return func(self.value)

1T_co = TypeVar("T_co", covariant=True)
2
3class MutableBox(Generic[T_co]):  # 錯誤！
4    def __init__(self, value: T_co) -> None:
5        self._value = value
6
7    def set(self, value: T_co) -> None:  # 協變型別不能用在參數位置
8        self._value = value

 1from dataclasses import dataclass, field
 2from pathlib import Path
 3from typing import Optional, List
 4
 5@dataclass
 6class ValidationIssue:
 7    """Single validation issue"""
 8    level: str  # "error" | "warning" | "info"
 9    message: str
10    line: Optional[int] = None
11    suggestion: Optional[str] = None
12
13@dataclass
14class ValidationResult:
15    """Validation result for a single hook"""
16    hook_path: str
17    issues: List[ValidationIssue] = field(default_factory=list)
18    is_compliant: bool = True
19
20    def __post_init__(self):
21        """Calculate is_compliant status"""
22        self.is_compliant = not any(
23            issue.level == "error" for issue in self.issues
24        )
25
26class HookValidator:
27    """Hook compliance validator - specific to Path type"""
28
29    def validate_hook(self, hook_path: str) -> ValidationResult:
30        """Validate a single hook file"""
31        hook_path = self._resolve_path(hook_path)
32
33        if not hook_path.exists():
34            return ValidationResult(
35                hook_path=str(hook_path),
36                issues=[ValidationIssue(
37                    level="error",
38                    message=f"Hook file not found: {hook_path}"
39                )]
40            )
41
42        # ... more validation logic ...
43        return ValidationResult(hook_path=str(hook_path))
44
45    def _resolve_path(self, path: str) -> Path:
46        """Resolve path to absolute path"""
47        p = Path(path)
48        return p if p.is_absolute() else Path.cwd() / p

 1from typing import Protocol, TypeVar, Generic
 2from dataclasses import dataclass, field
 3from abc import abstractmethod
 4
 5# Define a type variable for the input type
 6T = TypeVar("T")
 7
 8# Type variable with contravariance for Protocol
 9T_contra = TypeVar("T_contra", contravariant=True)
10
11@dataclass
12class ValidationResult(Generic[T]):
13    """
14    Generic validation result
15
16    Type parameter T represents the validated value type.
17    This allows type-safe access to the validated value.
18    """
19    value: T
20    is_valid: bool = True
21    errors: list[str] = field(default_factory=list)
22    warnings: list[str] = field(default_factory=list)
23
24    def add_error(self, message: str) -> "ValidationResult[T]":
25        """Add an error and mark as invalid"""
26        self.errors.append(message)
27        self.is_valid = False
28        return self
29
30    def add_warning(self, message: str) -> "ValidationResult[T]":
31        """Add a warning (does not affect validity)"""
32        self.warnings.append(message)
33        return self
34
35class Validator(Protocol[T_contra]):
36    """
37    Generic validator protocol
38
39    Any class that implements validate(value: T) -> ValidationResult[T]
40    is considered a Validator[T].
41
42    Using contravariant type variable because validators consume values.
43    A Validator[Animal] can validate Dog (subtype), so it's contravariant.
44    """
45
46    def validate(self, value: T_contra) -> ValidationResult:
47        """Validate the given value and return the result"""
48        ...

 1from pathlib import Path
 2import re
 3
 4class NotEmptyValidator:
 5    """Validate that a string is not empty"""
 6
 7    def validate(self, value: str) -> ValidationResult[str]:
 8        result = ValidationResult(value=value)
 9        if not value or not value.strip():
10            result.add_error("Value cannot be empty")
11        return result
12
13class PathExistsValidator:
14    """Validate that a path exists"""
15
16    def __init__(self, must_be_file: bool = False, must_be_dir: bool = False):
17        self.must_be_file = must_be_file
18        self.must_be_dir = must_be_dir
19
20    def validate(self, value: Path) -> ValidationResult[Path]:
21        result = ValidationResult(value=value)
22
23        if not value.exists():
24            result.add_error(f"Path does not exist: {value}")
25        elif self.must_be_file and not value.is_file():
26            result.add_error(f"Path is not a file: {value}")
27        elif self.must_be_dir and not value.is_dir():
28            result.add_error(f"Path is not a directory: {value}")
29
30        return result
31
32class PatternValidator:
33    """Validate that a string matches a regex pattern"""
34
35    def __init__(self, pattern: str, error_message: str | None = None):
36        self.pattern = re.compile(pattern)
37        self.error_message = error_message or f"Value must match pattern: {pattern}"
38
39    def validate(self, value: str) -> ValidationResult[str]:
40        result = ValidationResult(value=value)
41        if not self.pattern.match(value):
42            result.add_error(self.error_message)
43        return result
44
45class RangeValidator:
46    """Validate that a number is within a range"""
47
48    def __init__(
49        self,
50        min_value: float | None = None,
51        max_value: float | None = None
52    ):
53        self.min_value = min_value
54        self.max_value = max_value
55
56    def validate(self, value: float | int) -> ValidationResult[float | int]:
57        result = ValidationResult(value=value)
58
59        if self.min_value is not None and value < self.min_value:
60            result.add_error(f"Value {value} is below minimum {self.min_value}")
61        if self.max_value is not None and value > self.max_value:
62            result.add_error(f"Value {value} is above maximum {self.max_value}")
63
64        return result

 1from typing import Sequence
 2
 3class AndValidator(Generic[T]):
 4    """
 5    Combine multiple validators with AND logic
 6
 7    All validators must pass for the result to be valid.
 8    """
 9
10    def __init__(self, validators: Sequence[Validator[T]]):
11        self.validators = validators
12
13    def validate(self, value: T) -> ValidationResult[T]:
14        result = ValidationResult(value=value)
15
16        for validator in self.validators:
17            sub_result = validator.validate(value)
18            result.errors.extend(sub_result.errors)
19            result.warnings.extend(sub_result.warnings)
20
21        result.is_valid = len(result.errors) == 0
22        return result
23
24class OrValidator(Generic[T]):
25    """
26    Combine multiple validators with OR logic
27
28    At least one validator must pass for the result to be valid.
29    """
30
31    def __init__(self, validators: Sequence[Validator[T]]):
32        self.validators = validators
33
34    def validate(self, value: T) -> ValidationResult[T]:
35        result = ValidationResult(value=value)
36        all_errors: list[str] = []
37
38        for validator in self.validators:
39            sub_result = validator.validate(value)
40            if sub_result.is_valid:
41                # At least one passed, return success
42                result.warnings.extend(sub_result.warnings)
43                return result
44            all_errors.extend(sub_result.errors)
45
46        # All failed
47        result.add_error(
48            f"None of the validators passed. Errors: {'; '.join(all_errors)}"
49        )
50        return result
51
52class NotValidator(Generic[T]):
53    """
54    Negate a validator
55
56    The result is valid if the inner validator fails.
57    """
58
59    def __init__(self, validator: Validator[T], error_message: str | None = None):
60        self.validator = validator
61        self.error_message = error_message or "Validation should have failed"
62
63    def validate(self, value: T) -> ValidationResult[T]:
64        result = ValidationResult(value=value)
65        sub_result = self.validator.validate(value)
66
67        if sub_result.is_valid:
68            result.add_error(self.error_message)
69        # If inner failed, outer succeeds
70        return result

 1from typing import Callable
 2
 3class ValidatorBuilder(Generic[T]):
 4    """
 5    Fluent builder for composing validators
 6
 7    Provides a chainable API for building complex validators.
 8    """
 9
10    def __init__(self):
11        self._validators: list[Validator[T]] = []
12
13    def add(self, validator: Validator[T]) -> "ValidatorBuilder[T]":
14        """Add a validator to the chain"""
15        self._validators.append(validator)
16        return self
17
18    def add_if(
19        self,
20        condition: bool,
21        validator: Validator[T]
22    ) -> "ValidatorBuilder[T]":
23        """Conditionally add a validator"""
24        if condition:
25            self._validators.append(validator)
26        return self
27
28    def build(self) -> Validator[T]:
29        """Build the final AND-combined validator"""
30        if len(self._validators) == 1:
31            return self._validators[0]
32        return AndValidator(self._validators)
33
34    def build_or(self) -> Validator[T]:
35        """Build with OR logic instead of AND"""
36        if len(self._validators) == 1:
37            return self._validators[0]
38        return OrValidator(self._validators)
39
40def validator_for(type_hint: type[T]) -> ValidatorBuilder[T]:
41    """
42    Create a type-safe validator builder
43
44    Usage:
45        validator = (
46            validator_for(str)
47            .add(NotEmptyValidator())
48            .add(PatternValidator(r"^[a-z]+$"))
49            .build()
50        )
51    """
52    return ValidatorBuilder[T]()

  1#!/usr/bin/env python3
  2"""
  3Generic Validator System
  4
  5A type-safe, composable validation framework using Generic and TypeVar.
  6"""
  7
  8from __future__ import annotations
  9from abc import abstractmethod
 10from dataclasses import dataclass, field
 11from pathlib import Path
 12from typing import (
 13    Callable,
 14    Generic,
 15    Protocol,
 16    Sequence,
 17    TypeVar,
 18    runtime_checkable,
 19)
 20import re
 21
 22# ===== Type Variables =====
 23
 24T = TypeVar("T")
 25T_contra = TypeVar("T_contra", contravariant=True)
 26
 27# ===== Core Types =====
 28
 29@dataclass
 30class ValidationResult(Generic[T]):
 31    """
 32    Generic validation result
 33
 34    Attributes:
 35        value: The validated value (preserves type information)
 36        is_valid: Whether validation passed
 37        errors: List of error messages (cause validation failure)
 38        warnings: List of warning messages (informational only)
 39    """
 40    value: T
 41    is_valid: bool = True
 42    errors: list[str] = field(default_factory=list)
 43    warnings: list[str] = field(default_factory=list)
 44
 45    def add_error(self, message: str) -> ValidationResult[T]:
 46        """Add an error and mark as invalid"""
 47        self.errors.append(message)
 48        self.is_valid = False
 49        return self
 50
 51    def add_warning(self, message: str) -> ValidationResult[T]:
 52        """Add a warning (does not affect validity)"""
 53        self.warnings.append(message)
 54        return self
 55
 56    def __bool__(self) -> bool:
 57        """Allow using result in boolean context"""
 58        return self.is_valid
 59
 60@runtime_checkable
 61class Validator(Protocol[T_contra]):
 62    """
 63    Generic validator protocol
 64
 65    Any class implementing validate(value) -> ValidationResult
 66    satisfies this protocol.
 67    """
 68
 69    def validate(self, value: T_contra) -> ValidationResult:
 70        """Validate the given value"""
 71        ...
 72
 73# ===== Basic Validators =====
 74
 75class NotEmptyValidator:
 76    """Validate that a string is not empty"""
 77
 78    def validate(self, value: str) -> ValidationResult[str]:
 79        result = ValidationResult(value=value)
 80        if not value or not value.strip():
 81            result.add_error("Value cannot be empty")
 82        return result
 83
 84class PathExistsValidator:
 85    """Validate that a path exists"""
 86
 87    def __init__(
 88        self,
 89        must_be_file: bool = False,
 90        must_be_dir: bool = False
 91    ):
 92        self.must_be_file = must_be_file
 93        self.must_be_dir = must_be_dir
 94
 95    def validate(self, value: Path) -> ValidationResult[Path]:
 96        result = ValidationResult(value=value)
 97
 98        if not value.exists():
 99            result.add_error(f"Path does not exist: {value}")
100        elif self.must_be_file and not value.is_file():
101            result.add_error(f"Path is not a file: {value}")
102        elif self.must_be_dir and not value.is_dir():
103            result.add_error(f"Path is not a directory: {value}")
104
105        return result
106
107class PatternValidator:
108    """Validate string matches a regex pattern"""
109
110    def __init__(self, pattern: str, error_message: str | None = None):
111        self.pattern = re.compile(pattern)
112        self.error_message = error_message or f"Must match pattern: {pattern}"
113
114    def validate(self, value: str) -> ValidationResult[str]:
115        result = ValidationResult(value=value)
116        if not self.pattern.match(value):
117            result.add_error(self.error_message)
118        return result
119
120class RangeValidator:
121    """Validate number is within range"""
122
123    def __init__(
124        self,
125        min_value: float | None = None,
126        max_value: float | None = None
127    ):
128        self.min_value = min_value
129        self.max_value = max_value
130
131    def validate(self, value: float | int) -> ValidationResult[float | int]:
132        result = ValidationResult(value=value)
133        if self.min_value is not None and value < self.min_value:
134            result.add_error(f"Value {value} < minimum {self.min_value}")
135        if self.max_value is not None and value > self.max_value:
136            result.add_error(f"Value {value} > maximum {self.max_value}")
137        return result
138
139class LengthValidator:
140    """Validate string length"""
141
142    def __init__(
143        self,
144        min_length: int | None = None,
145        max_length: int | None = None
146    ):
147        self.min_length = min_length
148        self.max_length = max_length
149
150    def validate(self, value: str) -> ValidationResult[str]:
151        result = ValidationResult(value=value)
152        length = len(value)
153
154        if self.min_length is not None and length < self.min_length:
155            result.add_error(f"Length {length} < minimum {self.min_length}")
156        if self.max_length is not None and length > self.max_length:
157            result.add_error(f"Length {length} > maximum {self.max_length}")
158
159        return result
160
161class TypeValidator(Generic[T]):
162    """Validate value is of expected type"""
163
164    def __init__(self, expected_type: type[T], type_name: str | None = None):
165        self.expected_type = expected_type
166        self.type_name = type_name or expected_type.__name__
167
168    def validate(self, value: object) -> ValidationResult[T]:
169        if isinstance(value, self.expected_type):
170            return ValidationResult(value=value)  # type: ignore
171        else:
172            result = ValidationResult(value=value)  # type: ignore
173            result.add_error(
174                f"Expected {self.type_name}, got {type(value).__name__}"
175            )
176            return result
177
178# ===== Composite Validators =====
179
180class AndValidator(Generic[T]):
181    """Combine validators with AND logic (all must pass)"""
182
183    def __init__(self, validators: Sequence[Validator[T]]):
184        self.validators = list(validators)
185
186    def validate(self, value: T) -> ValidationResult[T]:
187        result = ValidationResult(value=value)
188
189        for validator in self.validators:
190            sub_result = validator.validate(value)
191            result.errors.extend(sub_result.errors)
192            result.warnings.extend(sub_result.warnings)
193
194        result.is_valid = len(result.errors) == 0
195        return result
196
197class OrValidator(Generic[T]):
198    """Combine validators with OR logic (at least one must pass)"""
199
200    def __init__(self, validators: Sequence[Validator[T]]):
201        self.validators = list(validators)
202
203    def validate(self, value: T) -> ValidationResult[T]:
204        result = ValidationResult(value=value)
205        all_errors: list[str] = []
206
207        for validator in self.validators:
208            sub_result = validator.validate(value)
209            if sub_result.is_valid:
210                result.warnings.extend(sub_result.warnings)
211                return result
212            all_errors.extend(sub_result.errors)
213
214        result.add_error(f"No validator passed: {'; '.join(all_errors)}")
215        return result
216
217class NotValidator(Generic[T]):
218    """Negate a validator (passes if inner validator fails)"""
219
220    def __init__(self, validator: Validator[T], error_message: str | None = None):
221        self.validator = validator
222        self.error_message = error_message or "Validation should have failed"
223
224    def validate(self, value: T) -> ValidationResult[T]:
225        result = ValidationResult(value=value)
226        sub_result = self.validator.validate(value)
227
228        if sub_result.is_valid:
229            result.add_error(self.error_message)
230
231        return result
232
233# ===== Builder =====
234
235class ValidatorBuilder(Generic[T]):
236    """Fluent builder for composing validators"""
237
238    def __init__(self):
239        self._validators: list[Validator[T]] = []
240
241    def add(self, validator: Validator[T]) -> ValidatorBuilder[T]:
242        """Add a validator"""
243        self._validators.append(validator)
244        return self
245
246    def add_if(
247        self,
248        condition: bool,
249        validator: Validator[T]
250    ) -> ValidatorBuilder[T]:
251        """Conditionally add a validator"""
252        if condition:
253            self._validators.append(validator)
254        return self
255
256    def build(self) -> Validator[T]:
257        """Build AND-combined validator"""
258        if len(self._validators) == 0:
259            raise ValueError("No validators added")
260        if len(self._validators) == 1:
261            return self._validators[0]
262        return AndValidator(self._validators)
263
264    def build_or(self) -> Validator[T]:
265        """Build OR-combined validator"""
266        if len(self._validators) == 0:
267            raise ValueError("No validators added")
268        if len(self._validators) == 1:
269            return self._validators[0]
270        return OrValidator(self._validators)
271
272def validator_for(type_hint: type[T]) -> ValidatorBuilder[T]:
273    """Create a type-safe validator builder"""
274    return ValidatorBuilder[T]()
275
276# ===== List Validator =====
277
278class ListValidator(Generic[T]):
279    """Validate each element in a list"""
280
281    def __init__(
282        self,
283        element_validator: Validator[T],
284        min_length: int | None = None,
285        max_length: int | None = None
286    ):
287        self.element_validator = element_validator
288        self.min_length = min_length
289        self.max_length = max_length
290
291    def validate(self, value: list[T]) -> ValidationResult[list[T]]:
292        result = ValidationResult(value=value)
293
294        # Check list length
295        if self.min_length is not None and len(value) < self.min_length:
296            result.add_error(f"List length {len(value)} < minimum {self.min_length}")
297        if self.max_length is not None and len(value) > self.max_length:
298            result.add_error(f"List length {len(value)} > maximum {self.max_length}")
299
300        # Validate each element
301        for i, item in enumerate(value):
302            sub_result = self.element_validator.validate(item)
303            for error in sub_result.errors:
304                result.add_error(f"[{i}] {error}")
305            for warning in sub_result.warnings:
306                result.add_warning(f"[{i}] {warning}")
307
308        return result
309
310# ===== Demo =====
311
312if __name__ == "__main__":
313    print("=== Generic Validator Demo ===\n")
314
315    # Example 1: Basic validators
316    print("1. Basic Validators")
317    print("-" * 40)
318
319    not_empty = NotEmptyValidator()
320    print(f"  NotEmpty(''): {not_empty.validate('')}")
321    print(f"  NotEmpty('hello'): {not_empty.validate('hello')}")
322
323    # Example 2: Path validator
324    print("\n2. Path Validator")
325    print("-" * 40)
326
327    path_validator = PathExistsValidator(must_be_file=True)
328    result = path_validator.validate(Path("/etc/hosts"))
329    print(f"  /etc/hosts: valid={result.is_valid}")
330
331    result = path_validator.validate(Path("/nonexistent"))
332    print(f"  /nonexistent: valid={result.is_valid}, errors={result.errors}")
333
334    # Example 3: Composed validators
335    print("\n3. Composed Validators (AND)")
336    print("-" * 40)
337
338    username_validator = AndValidator[str]([
339        NotEmptyValidator(),
340        LengthValidator(min_length=3, max_length=20),
341        PatternValidator(r"^[a-z][a-z0-9_]*$", "Must be lowercase alphanumeric"),
342    ])
343
344    test_usernames = ["", "ab", "valid_user", "Invalid", "a" * 25]
345    for username in test_usernames:
346        result = username_validator.validate(username)
347        status = "PASS" if result.is_valid else "FAIL"
348        print(f"  '{username}': {status}")
349        if not result.is_valid:
350            for error in result.errors:
351                print(f"    - {error}")
352
353    # Example 4: Builder pattern
354    print("\n4. Builder Pattern")
355    print("-" * 40)
356
357    email_validator = (
358        validator_for(str)
359        .add(NotEmptyValidator())
360        .add(PatternValidator(
361            r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$",
362            "Invalid email format"
363        ))
364        .build()
365    )
366
367    test_emails = ["", "invalid", "test@example.com"]
368    for email in test_emails:
369        result = email_validator.validate(email)
370        status = "PASS" if result.is_valid else "FAIL"
371        print(f"  '{email}': {status}")
372
373    # Example 5: List validator
374    print("\n5. List Validator")
375    print("-" * 40)
376
377    tags_validator = ListValidator(
378        element_validator=AndValidator[str]([
379            NotEmptyValidator(),
380            LengthValidator(max_length=20),
381        ]),
382        min_length=1,
383        max_length=5
384    )
385
386    test_tags = [
387        ["python", "typing"],
388        [],
389        ["valid", "", "also-valid"],
390    ]
391
392    for tags in test_tags:
393        result = tags_validator.validate(tags)
394        status = "PASS" if result.is_valid else "FAIL"
395        print(f"  {tags}: {status}")
396        if not result.is_valid:
397            for error in result.errors:
398                print(f"    - {error}")
399
400    print("\n=== Demo Complete ===")