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