Coverage for src/taipanstack/config/version_config.py: 100%
43 statements
« prev ^ index » next coverage.py v7.15.1, created at 2026-10-13 20:52 +0000
1"""
2Version-Specific Configuration Recommendations.
4This module provides configuration templates optimized for different
5Python versions, helping users get the best performance while
6maintaining stability.
8Following TaipanStack pillars: Security, Stability, Simplicity,
9Scalability, Compatibility.
10"""
12import logging
13from dataclasses import dataclass
15from taipanstack.core.compat import (
16 PY312,
17 PY313,
18 PY314,
19 VersionTier,
20 get_features,
21)
22from taipanstack.core.optimizations import get_recommended_thread_pool_size
24__all__ = [
25 "VersionRecommendations",
26 "get_version_recommendations",
27]
29logger = logging.getLogger(__name__)
32# =============================================================================
33# Version Recommendations
34# =============================================================================
37@dataclass(frozen=True, slots=True)
38class VersionRecommendations:
39 """Configuration recommendations for a Python version.
41 These recommendations help users configure their TaipanStack-based
42 applications for optimal performance on their Python version.
43 """
45 version_tier: VersionTier
46 min_version: str
47 max_version: str | None
49 # Threading recommendations
50 recommended_thread_pool_size: int
51 supports_true_parallelism: bool
53 # Memory recommendations
54 recommended_gc_mode: str
55 use_mimalloc: bool
57 # Code style recommendations
58 use_type_params: bool # PEP 695 type parameter syntax
59 use_exception_groups: bool # PEP 654 exception groups
60 use_match_statements: bool # PEP 634 structural matching
61 use_override_decorator: bool # PEP 698 @override
62 use_deprecated_decorator: bool # PEP 702 @deprecated
64 # Performance recommendations
65 jit_available: bool
66 recommended_optimization_level: int
68 # Notes for user
69 notes: tuple[str, ...]
71 def to_dict(self) -> dict[str, object]:
72 """Convert to dictionary for serialization."""
73 return {
74 "version_tier": self.version_tier.value,
75 "version_range": f"{self.min_version} - {self.max_version or 'latest'}",
76 "threading": {
77 "pool_size": self.recommended_thread_pool_size,
78 "true_parallelism": self.supports_true_parallelism,
79 },
80 "memory": {
81 "gc_mode": self.recommended_gc_mode,
82 "mimalloc": self.use_mimalloc,
83 },
84 "code_style": {
85 "type_params": self.use_type_params,
86 "exception_groups": self.use_exception_groups,
87 "match_statements": self.use_match_statements,
88 "override_decorator": self.use_override_decorator,
89 "deprecated_decorator": self.use_deprecated_decorator,
90 },
91 "performance": {
92 "jit_available": self.jit_available,
93 "optimization_level": self.recommended_optimization_level,
94 },
95 "notes": list(self.notes),
96 }
99# =============================================================================
100# Recommendation Generators
101# =============================================================================
104def _get_311_recommendations() -> VersionRecommendations:
105 """Get recommendations for Python 3.11."""
106 return VersionRecommendations(
107 version_tier=VersionTier.STABLE,
108 min_version="3.11.0",
109 max_version="3.11.x",
110 recommended_thread_pool_size=get_recommended_thread_pool_size(),
111 supports_true_parallelism=False,
112 recommended_gc_mode="default",
113 use_mimalloc=False,
114 use_type_params=False,
115 use_exception_groups=True,
116 use_match_statements=True,
117 use_override_decorator=False,
118 use_deprecated_decorator=False,
119 jit_available=False,
120 recommended_optimization_level=1,
121 notes=(
122 "Stable baseline with 25% speedup from specialized bytecode",
123 "Use exception groups (PEP 654) for better error handling",
124 "Self type available for type hints",
125 ),
126 )
129def _get_312_recommendations() -> VersionRecommendations:
130 """Get recommendations for Python 3.12."""
131 return VersionRecommendations(
132 version_tier=VersionTier.ENHANCED,
133 min_version="3.12.0",
134 max_version="3.12.x",
135 recommended_thread_pool_size=get_recommended_thread_pool_size(),
136 supports_true_parallelism=False,
137 recommended_gc_mode="default",
138 use_mimalloc=False,
139 use_type_params=True,
140 use_exception_groups=True,
141 use_match_statements=True,
142 use_override_decorator=True,
143 use_deprecated_decorator=False,
144 jit_available=False,
145 recommended_optimization_level=1,
146 notes=(
147 "Use type parameter syntax (PEP 695) for cleaner generics",
148 "Use @override decorator (PEP 698) for method overrides",
149 "Improved f-string parsing and error messages",
150 ),
151 )
154def _get_313_recommendations() -> VersionRecommendations:
155 """Get recommendations for Python 3.13."""
156 features = get_features()
157 return VersionRecommendations(
158 version_tier=VersionTier.MODERN,
159 min_version="3.13.0",
160 max_version="3.13.x",
161 recommended_thread_pool_size=get_recommended_thread_pool_size(),
162 supports_true_parallelism=features.has_free_threading,
163 recommended_gc_mode="tuned" if features.has_mimalloc else "default",
164 use_mimalloc=features.has_mimalloc,
165 use_type_params=True,
166 use_exception_groups=True,
167 use_match_statements=True,
168 use_override_decorator=True,
169 use_deprecated_decorator=True,
170 jit_available=features.has_jit,
171 recommended_optimization_level=2 if features.experimental_enabled else 1,
172 notes=(
173 "Use @deprecated decorator (PEP 702) for deprecation warnings",
174 "JIT compiler available (experimental) with STACK_ENABLE_EXPERIMENTAL=1",
175 "Free-threading available on special builds (no GIL)",
176 "mimalloc allocator provides better memory performance",
177 ),
178 )
181def _get_314_recommendations() -> VersionRecommendations:
182 """Get recommendations for Python 3.14."""
183 features = get_features()
184 return VersionRecommendations(
185 version_tier=VersionTier.CUTTING_EDGE,
186 min_version="3.14.0",
187 max_version=None,
188 recommended_thread_pool_size=get_recommended_thread_pool_size(),
189 supports_true_parallelism=features.has_free_threading,
190 recommended_gc_mode="incremental",
191 use_mimalloc=True,
192 use_type_params=True,
193 use_exception_groups=True,
194 use_match_statements=True,
195 use_override_decorator=True,
196 use_deprecated_decorator=True,
197 jit_available=features.has_jit,
198 recommended_optimization_level=2 if features.experimental_enabled else 1,
199 notes=(
200 "Tail-call interpreter provides 9-15% speedup",
201 "Deferred annotations (PEP 649) for faster startup",
202 "Stable free-threading support available",
203 "JIT compiler significantly improved from 3.13",
204 "Incremental GC reduces pause times",
205 ),
206 )
209def get_version_recommendations() -> VersionRecommendations:
210 """Get configuration recommendations for the current Python version.
212 Returns:
213 VersionRecommendations with optimal settings.
215 """
216 if PY314:
217 return _get_314_recommendations()
218 if PY313:
219 return _get_313_recommendations()
220 if PY312:
221 return _get_312_recommendations()
222 return _get_311_recommendations()