Config — Models & Generators

TaipanStack's configuration layer provides Pydantic v2 models, project scaffolding generators, and Python version-aware recommendations.

---

StackConfig Model

Configuration models with Pydantic validation.

This module provides type-safe configuration models that validate all inputs at runtime, preventing errors and AI hallucinations.

SecurityConfig

Bases: BaseModel

Security-related configuration options.

ATTRIBUTE	DESCRIPTION
level	Security strictness level. TYPE: Literal['standard', 'strict', 'paranoid']
enable_bandit	Enable Bandit SAST scanner. TYPE: bool
enable_safety	Enable Safety dependency checker. TYPE: bool
enable_semgrep	Enable Semgrep analysis. TYPE: bool
enable_detect_secrets	Enable secret detection. TYPE: bool
bandit_severity	Minimum severity level for Bandit. TYPE: Literal['low', 'medium', 'high']

DependencyConfig

Bases: BaseModel

Dependency management configuration.

ATTRIBUTE	DESCRIPTION
install_runtime_deps	Install pydantic, orjson, uvloop. TYPE: bool
install_dev_deps	Install development dependencies. TYPE: bool
dev_dependencies	List of dev dependencies to install. TYPE: list[str]
runtime_dependencies	List of runtime dependencies to install. TYPE: list[str]

LoggingConfig

Bases: BaseModel

Logging configuration options.

ATTRIBUTE	DESCRIPTION
level	Log level. TYPE: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL']
format	Log format type. TYPE: Literal['simple', 'detailed', 'json']
enable_structured	Use structured logging (JSON). TYPE: bool

StackConfig

Bases: 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.

ATTRIBUTE	DESCRIPTION
project_name	Name of the project (alphanumeric, _, -). TYPE: str
python_version	Target Python version (e.g., "3.12"). TYPE: str
project_dir	Directory to initialize project in. TYPE: Path
dry_run	Simulate execution without changes. TYPE: bool
force	Overwrite existing files without backup. TYPE: bool
verbose	Enable verbose logging. TYPE: bool
security	Security configuration. TYPE: SecurityConfig
dependencies	Dependency configuration. TYPE: DependencyConfig
logging	Logging configuration. TYPE: LoggingConfig

Example

config = StackConfig( ... project_name="my_project", ... python_version="3.12", ... ) config.project_name 'my_project'

validate_project_name classmethod

validate_project_name(value: str) -> str

Validate that project name is safe.

PARAMETER	DESCRIPTION
value	The project name to validate. TYPE: str

RETURNS	DESCRIPTION
str	The validated project name.

RAISES	DESCRIPTION
ValueError	If project name contains invalid characters.

validate_python_version classmethod

validate_python_version(value: str) -> str

Validate Python version format.

PARAMETER	DESCRIPTION
value	The Python version string. TYPE: str

RETURNS	DESCRIPTION
str	The validated Python version.

RAISES	DESCRIPTION
ValueError	If version format is invalid.

validate_project_dir classmethod

validate_project_dir(value: Path) -> Path

Validate project directory is safe.

PARAMETER	DESCRIPTION
value	The project directory path. TYPE: Path

RETURNS	DESCRIPTION
Path	The validated and resolved path.

RAISES	DESCRIPTION
ValueError	If path is unsafe or contains traversal.

validate_config_consistency

validate_config_consistency() -> StackConfig

Validate configuration consistency.

RETURNS	DESCRIPTION
StackConfig	The validated configuration.

RAISES	DESCRIPTION
ValueError	If configuration is inconsistent.

to_target_version

to_target_version() -> str

Get Python version in Ruff target format.

RETURNS	DESCRIPTION
str	Version string like 'py312'.

---

Version Config

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.

VersionRecommendations dataclass

VersionRecommendations(
    version_tier: VersionTier,
    min_version: str,
    max_version: str | None,
    recommended_thread_pool_size: int,
    supports_true_parallelism: bool,
    recommended_gc_mode: str,
    use_mimalloc: bool,
    use_type_params: bool,
    use_exception_groups: bool,
    use_match_statements: bool,
    use_override_decorator: bool,
    use_deprecated_decorator: bool,
    jit_available: bool,
    recommended_optimization_level: int,
    notes: tuple[str, ...],
)

Configuration recommendations for a Python version.

These recommendations help users configure their Stack-based applications for optimal performance on their Python version.

to_dict

to_dict() -> dict[str, object]

Convert to dictionary for serialization.

get_version_recommendations

get_version_recommendations() -> VersionRecommendations

Get configuration recommendations for the current Python version.

RETURNS	DESCRIPTION
VersionRecommendations	VersionRecommendations with optimal settings.

---

Generators

Configuration file generators.

This module generates configuration files (pyproject.toml, pre-commit, etc.) with proper validation and templating.

generate_pyproject_config

generate_pyproject_config(config: StackConfig) -> str

Generate Ruff, Mypy, and Pytest configuration for pyproject.toml.

PARAMETER	DESCRIPTION
config	The Stack configuration. TYPE: StackConfig

RETURNS	DESCRIPTION
str	Configuration string to append to pyproject.toml.

generate_pre_commit_config

generate_pre_commit_config(config: StackConfig) -> str

Generate .pre-commit-config.yaml content.

PARAMETER	DESCRIPTION
config	The Stack configuration. TYPE: StackConfig

RETURNS	DESCRIPTION
str	Pre-commit configuration YAML string.

generate_dependabot_config

generate_dependabot_config() -> str

Generate .github/dependabot.yml content.

RETURNS	DESCRIPTION
str	Dependabot configuration YAML string.

generate_security_policy

generate_security_policy() -> str

Generate SECURITY.md content.

RETURNS	DESCRIPTION
str	Security policy markdown string.

generate_editorconfig

generate_editorconfig() -> str

Generate .editorconfig content.

RETURNS	DESCRIPTION
str	EditorConfig content string.

write_config_file

write_config_file(
    path: Path, content: str, config: StackConfig
) -> bool

Write configuration file with backup support.

PARAMETER	DESCRIPTION
path	Path to write the file. TYPE: Path
content	Content to write. TYPE: str
config	Stack configuration. TYPE: StackConfig

RETURNS	DESCRIPTION
bool	True if file was written, False if in dry-run mode.