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