taipanstack 0.1.0__py3-none-any.whl

taipanstack/config/models.py

@@ -0,0 +1,316 @@
+"""
+Configuration models with Pydantic validation.
+
+This module provides type-safe configuration models that validate
+all inputs at runtime, preventing errors and AI hallucinations.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+from typing import Literal
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    field_validator,
+    model_validator,
+)
+
+# Constants to avoid magic values (PLR2004)
+PYTHON_MAJOR_VERSION = 3
+MIN_PYTHON_MINOR_VERSION = 10
+
+
+class SecurityConfig(BaseModel):
+    """Security-related configuration options.
+
+    Attributes:
+        level: Security strictness level.
+        enable_bandit: Enable Bandit SAST scanner.
+        enable_safety: Enable Safety dependency checker.
+        enable_semgrep: Enable Semgrep analysis.
+        enable_detect_secrets: Enable secret detection.
+        bandit_severity: Minimum severity level for Bandit.
+
+    """
+
+    level: Literal["standard", "strict", "paranoid"] = Field(
+        default="strict",
+        description="Security strictness level",
+    )
+    enable_bandit: bool = Field(default=True, description="Enable Bandit SAST")
+    enable_safety: bool = Field(default=True, description="Enable Safety SCA")
+    enable_semgrep: bool = Field(default=True, description="Enable Semgrep")
+    enable_detect_secrets: bool = Field(
+        default=True, description="Enable secret detection"
+    )
+    bandit_severity: Literal["low", "medium", "high"] = Field(
+        default="low",
+        description="Minimum Bandit severity",
+    )
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class DependencyConfig(BaseModel):
+    """Dependency management configuration.
+
+    Attributes:
+        install_runtime_deps: Install pydantic, orjson, uvloop.
+        install_dev_deps: Install development dependencies.
+        dev_dependencies: List of dev dependencies to install.
+        runtime_dependencies: List of runtime dependencies to install.
+
+    """
+
+    install_runtime_deps: bool = Field(
+        default=False,
+        description="Install runtime dependencies (pydantic, orjson, uvloop)",
+    )
+    install_dev_deps: bool = Field(
+        default=True,
+        description="Install development dependencies",
+    )
+    dev_dependencies: list[str] = Field(
+        default_factory=lambda: [
+            "ruff",
+            "mypy",
+            "bandit",
+            "safety",
+            "pre-commit",
+            "pytest",
+            "pytest-cov",
+            "py-spy",
+            "semgrep",
+        ],
+        description="Development dependencies to install",
+    )
+    runtime_dependencies: list[str] = Field(
+        default_factory=lambda: ["pydantic>=2.0", "orjson"],
+        description="Runtime dependencies to install",
+    )
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class LoggingConfig(BaseModel):
+    """Logging configuration options.
+
+    Attributes:
+        level: Log level.
+        format: Log format type.
+        enable_structured: Use structured logging (JSON).
+
+    """
+
+    level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = Field(
+        default="INFO",
+        description="Logging level",
+    )
+    format: Literal["simple", "detailed", "json"] = Field(
+        default="detailed",
+        description="Log output format",
+    )
+    enable_structured: bool = Field(
+        default=False,
+        description="Enable JSON structured logging",
+    )
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class StackConfig(BaseModel):
+    """Main Stack configuration with full validation.
+
+    This is the primary configuration model that validates all Stack
+    settings at runtime, preventing configuration errors and catching
+    AI hallucinations early.
+
+    Attributes:
+        project_name: Name of the project (alphanumeric, _, -).
+        python_version: Target Python version (e.g., "3.12").
+        project_dir: Directory to initialize project in.
+        dry_run: Simulate execution without changes.
+        force: Overwrite existing files without backup.
+        verbose: Enable verbose logging.
+        security: Security configuration.
+        dependencies: Dependency configuration.
+        logging: Logging configuration.
+
+    Example:
+        >>> config = StackConfig(
+        ...     project_name="my_project",
+        ...     python_version="3.12",
+        ... )
+        >>> config.project_name
+        'my_project'
+
+    """
+
+    project_name: str = Field(
+        default="my_project",
+        min_length=1,
+        max_length=100,
+        description="Project name (alphanumeric, underscore, hyphen only)",
+    )
+    python_version: str = Field(
+        default_factory=lambda: f"{sys.version_info.major}.{sys.version_info.minor}",
+        description="Target Python version",
+    )
+    project_dir: Path = Field(
+        default_factory=Path.cwd,
+        description="Project directory",
+    )
+    dry_run: bool = Field(
+        default=False,
+        description="Simulate execution without making changes",
+    )
+    force: bool = Field(
+        default=False,
+        description="Overwrite existing files without backup",
+    )
+    verbose: bool = Field(
+        default=False,
+        description="Enable verbose output",
+    )
+    security: SecurityConfig = Field(
+        default_factory=SecurityConfig,
+        description="Security configuration",
+    )
+    dependencies: DependencyConfig = Field(
+        default_factory=DependencyConfig,
+        description="Dependency configuration",
+    )
+    logging: LoggingConfig = Field(
+        default_factory=LoggingConfig,
+        description="Logging configuration",
+    )
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        validate_default=True,
+    )
+
+    @field_validator("project_name")
+    @classmethod
+    def validate_project_name(cls, value: str) -> str:
+        """Validate that project name is safe.
+
+        Args:
+            value: The project name to validate.
+
+        Returns:
+            The validated project name.
+
+        Raises:
+            ValueError: If project name contains invalid characters.
+
+        """
+        pattern = r"^[a-zA-Z][a-zA-Z0-9_-]*$"
+        if not re.match(pattern, value):
+            msg = (
+                f"Project name '{value}' is invalid. "
+                "Must start with a letter and contain only alphanumeric, "
+                "underscore, or hyphen characters."
+            )
+            raise ValueError(msg)
+        return value
+
+    @field_validator("python_version")
+    @classmethod
+    def validate_python_version(cls, value: str) -> str:
+        """Validate Python version format.
+
+        Args:
+            value: The Python version string.
+
+        Returns:
+            The validated Python version.
+
+        Raises:
+            ValueError: If version format is invalid.
+
+        """
+        pattern = r"^\d+\.\d+$"
+        if not re.match(pattern, value):
+            msg = (
+                f"Python version '{value}' is invalid. Use format 'X.Y' (e.g., '3.12')."
+            )
+            raise ValueError(msg)
+
+        major, minor = map(int, value.split("."))
+        is_old_python = major < PYTHON_MAJOR_VERSION or (
+            major == PYTHON_MAJOR_VERSION and minor < MIN_PYTHON_MINOR_VERSION
+        )
+        if is_old_python:
+            msg = (
+                f"Python version {value} is not supported. "
+                f"Minimum is {PYTHON_MAJOR_VERSION}.{MIN_PYTHON_MINOR_VERSION}."
+            )
+            raise ValueError(msg)
+
+        return value
+
+    @field_validator("project_dir")
+    @classmethod
+    def validate_project_dir(cls, value: Path) -> Path:
+        """Validate project directory is safe.
+
+        Args:
+            value: The project directory path.
+
+        Returns:
+            The validated and resolved path.
+
+        Raises:
+            ValueError: If path is unsafe or contains traversal.
+
+        """
+        resolved = value.resolve()
+
+        # Check for path traversal attempts
+        if ".." in str(value):
+            msg = f"Path traversal detected in project_dir: {value}"
+            raise ValueError(msg)
+
+        return resolved
+
+    @model_validator(mode="after")
+    def validate_config_consistency(self) -> StackConfig:
+        """Validate configuration consistency.
+
+        Returns:
+            The validated configuration.
+
+        Raises:
+            ValueError: If configuration is inconsistent.
+
+        """
+        # If paranoid security, ensure all security tools are enabled
+        all_tools_enabled = all(
+            [
+                self.security.enable_bandit,
+                self.security.enable_safety,
+                self.security.enable_semgrep,
+                self.security.enable_detect_secrets,
+            ]
+        )
+        if self.security.level == "paranoid" and not all_tools_enabled:
+            msg = "Paranoid security level requires all security tools enabled."
+            raise ValueError(msg)
+
+        return self
+
+    def to_target_version(self) -> str:
+        """Get Python version in Ruff target format.
+
+        Returns:
+            Version string like 'py312'.
+
+        """
+        return f"py{self.python_version.replace('.', '')}"

taipanstack/config/version_config.py

@@ -0,0 +1,227 @@
+"""
+Version-Specific Configuration Recommendations.
+
+This module provides configuration templates optimized for different
+Python versions, helping users get the best performance while
+maintaining stability.
+
+Following Stack pillars: Security, Stability, Simplicity, Scalability, Compatibility.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from taipanstack.core.compat import (
+    PY312,
+    PY313,
+    PY314,
+    VersionTier,
+    get_features,
+)
+from taipanstack.core.optimizations import get_recommended_thread_pool_size
+
+if TYPE_CHECKING:
+    pass
+
+__all__ = [
+    "VersionRecommendations",
+    "get_version_recommendations",
+]
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# Version Recommendations
+# =============================================================================
+
+
+@dataclass(frozen=True, slots=True)
+class VersionRecommendations:
+    """Configuration recommendations for a Python version.
+
+    These recommendations help users configure their Stack-based
+    applications for optimal performance on their Python version.
+    """
+
+    version_tier: VersionTier
+    min_version: str
+    max_version: str | None
+
+    # Threading recommendations
+    recommended_thread_pool_size: int
+    supports_true_parallelism: bool
+
+    # Memory recommendations
+    recommended_gc_mode: str
+    use_mimalloc: bool
+
+    # Code style recommendations
+    use_type_params: bool  # PEP 695 type parameter syntax
+    use_exception_groups: bool  # PEP 654 exception groups
+    use_match_statements: bool  # PEP 634 structural matching
+    use_override_decorator: bool  # PEP 698 @override
+    use_deprecated_decorator: bool  # PEP 702 @deprecated
+
+    # Performance recommendations
+    jit_available: bool
+    recommended_optimization_level: int
+
+    # Notes for user
+    notes: tuple[str, ...]
+
+    def to_dict(self) -> dict[str, object]:
+        """Convert to dictionary for serialization."""
+        return {
+            "version_tier": self.version_tier.value,
+            "version_range": f"{self.min_version} - {self.max_version or 'latest'}",
+            "threading": {
+                "pool_size": self.recommended_thread_pool_size,
+                "true_parallelism": self.supports_true_parallelism,
+            },
+            "memory": {
+                "gc_mode": self.recommended_gc_mode,
+                "mimalloc": self.use_mimalloc,
+            },
+            "code_style": {
+                "type_params": self.use_type_params,
+                "exception_groups": self.use_exception_groups,
+                "match_statements": self.use_match_statements,
+                "override_decorator": self.use_override_decorator,
+                "deprecated_decorator": self.use_deprecated_decorator,
+            },
+            "performance": {
+                "jit_available": self.jit_available,
+                "optimization_level": self.recommended_optimization_level,
+            },
+            "notes": list(self.notes),
+        }
+
+
+# =============================================================================
+# Recommendation Generators
+# =============================================================================
+
+
+def _get_311_recommendations() -> VersionRecommendations:
+    """Get recommendations for Python 3.11."""
+    return VersionRecommendations(
+        version_tier=VersionTier.STABLE,
+        min_version="3.11.0",
+        max_version="3.11.x",
+        recommended_thread_pool_size=get_recommended_thread_pool_size(),
+        supports_true_parallelism=False,
+        recommended_gc_mode="default",
+        use_mimalloc=False,
+        use_type_params=False,
+        use_exception_groups=True,
+        use_match_statements=True,
+        use_override_decorator=False,
+        use_deprecated_decorator=False,
+        jit_available=False,
+        recommended_optimization_level=1,
+        notes=(
+            "Stable baseline with 25% speedup from specialized bytecode",
+            "Use exception groups (PEP 654) for better error handling",
+            "Self type available for type hints",
+        ),
+    )
+
+
+def _get_312_recommendations() -> VersionRecommendations:
+    """Get recommendations for Python 3.12."""
+    return VersionRecommendations(
+        version_tier=VersionTier.ENHANCED,
+        min_version="3.12.0",
+        max_version="3.12.x",
+        recommended_thread_pool_size=get_recommended_thread_pool_size(),
+        supports_true_parallelism=False,
+        recommended_gc_mode="default",
+        use_mimalloc=False,
+        use_type_params=True,
+        use_exception_groups=True,
+        use_match_statements=True,
+        use_override_decorator=True,
+        use_deprecated_decorator=False,
+        jit_available=False,
+        recommended_optimization_level=1,
+        notes=(
+            "Use type parameter syntax (PEP 695) for cleaner generics",
+            "Use @override decorator (PEP 698) for method overrides",
+            "Improved f-string parsing and error messages",
+        ),
+    )
+
+
+def _get_313_recommendations() -> VersionRecommendations:
+    """Get recommendations for Python 3.13."""
+    features = get_features()
+    return VersionRecommendations(
+        version_tier=VersionTier.MODERN,
+        min_version="3.13.0",
+        max_version="3.13.x",
+        recommended_thread_pool_size=get_recommended_thread_pool_size(),
+        supports_true_parallelism=features.has_free_threading,
+        recommended_gc_mode="tuned" if features.has_mimalloc else "default",
+        use_mimalloc=features.has_mimalloc,
+        use_type_params=True,
+        use_exception_groups=True,
+        use_match_statements=True,
+        use_override_decorator=True,
+        use_deprecated_decorator=True,
+        jit_available=features.has_jit,
+        recommended_optimization_level=2 if features.experimental_enabled else 1,
+        notes=(
+            "Use @deprecated decorator (PEP 702) for deprecation warnings",
+            "JIT compiler available (experimental) with STACK_ENABLE_EXPERIMENTAL=1",
+            "Free-threading available on special builds (no GIL)",
+            "mimalloc allocator provides better memory performance",
+        ),
+    )
+
+
+def _get_314_recommendations() -> VersionRecommendations:
+    """Get recommendations for Python 3.14."""
+    features = get_features()
+    return VersionRecommendations(
+        version_tier=VersionTier.CUTTING_EDGE,
+        min_version="3.14.0",
+        max_version=None,
+        recommended_thread_pool_size=get_recommended_thread_pool_size(),
+        supports_true_parallelism=features.has_free_threading,
+        recommended_gc_mode="incremental",
+        use_mimalloc=True,
+        use_type_params=True,
+        use_exception_groups=True,
+        use_match_statements=True,
+        use_override_decorator=True,
+        use_deprecated_decorator=True,
+        jit_available=features.has_jit,
+        recommended_optimization_level=2 if features.experimental_enabled else 1,
+        notes=(
+            "Tail-call interpreter provides 9-15% speedup",
+            "Deferred annotations (PEP 649) for faster startup",
+            "Stable free-threading support available",
+            "JIT compiler significantly improved from 3.13",
+            "Incremental GC reduces pause times",
+        ),
+    )
+
+
+def get_version_recommendations() -> VersionRecommendations:
+    """Get configuration recommendations for the current Python version.
+
+    Returns:
+        VersionRecommendations with optimal settings.
+
+    """
+    if PY314:
+        return _get_314_recommendations()
+    if PY313:
+        return _get_313_recommendations()
+    if PY312:
+        return _get_312_recommendations()
+    return _get_311_recommendations()

taipanstack/core/__init__.py

@@ -0,0 +1,47 @@
+"""Stack Core Module.
+
+Provides core functionality including Result types, version compatibility,
+and optimization utilities.
+"""
+
+from taipanstack.core.compat import (
+    PY311,
+    PY312,
+    PY313,
+    PY314,
+    PY_VERSION,
+    PythonFeatures,
+    VersionTier,
+    get_features,
+    get_python_info,
+    is_experimental_enabled,
+)
+from taipanstack.core.optimizations import (
+    OptimizationProfile,
+    OptimizationResult,
+    apply_optimizations,
+    get_optimization_profile,
+    get_recommended_thread_pool_size,
+)
+from taipanstack.core.result import Err, Ok, Result
+
+__all__ = [
+    "PY311",
+    "PY312",
+    "PY313",
+    "PY314",
+    "PY_VERSION",
+    "Err",
+    "Ok",
+    "OptimizationProfile",
+    "OptimizationResult",
+    "PythonFeatures",
+    "Result",
+    "VersionTier",
+    "apply_optimizations",
+    "get_features",
+    "get_optimization_profile",
+    "get_python_info",
+    "get_recommended_thread_pool_size",
+    "is_experimental_enabled",
+]