Skip to content
Sarj Code Standards

prefer-grouped-settings

Group settings fields that share a Python namespace prefix into a nested settings object.

SARJ532 Rule source Tests Catalog JSON

Why

Repeated namespace prefixes flatten one component's configuration across the parent settings API. A focused settings object gives that component an explicit boundary.

Fix

Move the related fields into a focused nested settings object, normally constructed with Field(default_factory=...). Preserve existing environment aliases, prefixes, validation, defaults and source precedence, and verify real environment loading before changing the settings API.

Examples

Before — flagged Related settings expose a repeated component namespace
app/settings.py
from pydantic_settings import BaseSettings




class Settings(BaseSettings):
    embedder_url: str
    embedder_token: str
After — preferred The component owns its settings and environment prefix
app/settings.py
from pydantic import Field
from pydantic_settings import BaseSettings, SettingsConfigDict




class EmbedderSettings(BaseSettings):
    model_config = SettingsConfigDict(env_prefix="EMBEDDER_")
    url: str
    token: str




class Settings(BaseSettings):
    embedder: EmbedderSettings = Field(default_factory=EmbedderSettings)