Config

docstring_format_checker.config

Summary

Configuration handling for the docstring format checker.

GlobalConfig dataclass

Summary

Global configuration for docstring checking behavior.

Source code in src/docstring_format_checker/config.py

@dataclass
class GlobalConfig:
    """
    !!! note "Summary"
        Global configuration for docstring checking behavior.
    """

    allow_undefined_sections: bool = False
    require_docstrings: bool = True
    check_private: bool = False
    validate_param_types: bool = True

__init__

__init__(
    allow_undefined_sections: bool = False,
    require_docstrings: bool = True,
    check_private: bool = False,
    validate_param_types: bool = True,
) -> None

allow_undefined_sections class-attribute instance-attribute

allow_undefined_sections: bool = False

require_docstrings class-attribute instance-attribute

require_docstrings: bool = True

check_private class-attribute instance-attribute

check_private: bool = False

validate_param_types class-attribute instance-attribute

validate_param_types: bool = True

SectionConfig dataclass

Summary

Configuration for a docstring section.

Source code in src/docstring_format_checker/config.py

@dataclass
class SectionConfig:
    """
    !!! note "Summary"
        Configuration for a docstring section.
    """

    order: int
    name: str
    type: Literal["free_text", "list_name", "list_type", "list_name_and_type"]
    admonition: Union[bool, str] = False
    prefix: str = ""  # Support any prefix string
    required: bool = False
    message: str = ""  # Optional message for validation errors

    def __post_init__(self) -> None:
        """
        !!! note "Summary"
            Validate configuration after initialization.
        """
        self._validate_types()
        self._validate_admonition_prefix_combination()

    def _validate_types(self) -> None:
        """
        !!! note "Summary"
            Validate the 'type' field.
        """
        if self.type not in VALID_TYPES:
            raise InvalidTypeValuesError(f"Invalid section type: {self.type}. Valid types: {VALID_TYPES}")

    def _validate_admonition_prefix_combination(self) -> None:
        """
        !!! note "Summary"
            Validate admonition and prefix combination rules.
        """

        if isinstance(self.admonition, bool):
            # Rule: admonition cannot be True (only False or string)
            if self.admonition is True:
                raise ValueError(f"Section '{self.name}': admonition cannot be True, must be False or a string")

            # Rule: if admonition is False, prefix cannot be provided
            if self.admonition is False and self.prefix:
                raise ValueError(f"Section '{self.name}': when admonition=False, prefix cannot be provided")

        elif isinstance(self.admonition, str):
            # Rule: if admonition is a string, prefix must be provided
            if not self.prefix:
                raise ValueError(f"Section '{self.name}': when admonition is a string, prefix must be provided")

        else:
            raise ValueError(
                f"Section '{self.name}': admonition must be a boolean or string, got {type(self.admonition)}"
            )

__init__

__init__(
    order: int,
    name: str,
    type: Literal[
        "free_text",
        "list_name",
        "list_type",
        "list_name_and_type",
    ],
    admonition: Union[bool, str] = False,
    prefix: str = "",
    required: bool = False,
    message: str = "",
) -> None

order instance-attribute

order: int

name instance-attribute

name: str

type instance-attribute

type: Literal[
    "free_text",
    "list_name",
    "list_type",
    "list_name_and_type",
]

admonition class-attribute instance-attribute

admonition: Union[bool, str] = False

prefix class-attribute instance-attribute

prefix: str = ''

required class-attribute instance-attribute

required: bool = False

message class-attribute instance-attribute

message: str = ''

__post_init__

__post_init__() -> None

Summary

Validate configuration after initialization.

Source code in src/docstring_format_checker/config.py

def __post_init__(self) -> None:
    """
    !!! note "Summary"
        Validate configuration after initialization.
    """
    self._validate_types()
    self._validate_admonition_prefix_combination()

Config dataclass

Summary

Complete configuration containing global settings and section definitions.

Source code in src/docstring_format_checker/config.py

@dataclass
class Config:
    """
    !!! note "Summary"
        Complete configuration containing global settings and section definitions.
    """

    global_config: GlobalConfig
    sections: list[SectionConfig]

__init__

__init__(
    global_config: GlobalConfig,
    sections: list[SectionConfig],
) -> None

global_config instance-attribute

global_config: GlobalConfig

sections instance-attribute

sections: list[SectionConfig]

DEFAULT_CONFIG module-attribute

DEFAULT_CONFIG: Config = Config(
    global_config=GlobalConfig(), sections=DEFAULT_SECTIONS
)

load_config

load_config(
    config_path: Optional[Union[str, Path]] = None,
) -> Config

Summary

Load configuration from a TOML file or return default configuration.

Parameters:

Name	Type	Description	Default
config_path	Optional[Union[str, Path]]	Path to the TOML configuration file. If None, looks for pyproject.toml in current directory. Default: None.	None

Raises:

Type	Description
FileNotFoundError	If the specified config file doesn't exist.
InvalidConfigError	If the configuration is invalid.

Returns:

Type	Description
Config	Configuration object containing global settings and section definitions.

Source code in src/docstring_format_checker/config.py

def load_config(config_path: Optional[Union[str, Path]] = None) -> Config:
    """
    !!! note "Summary"
        Load configuration from a TOML file or return default configuration.

    Params:
        config_path (Optional[Union[str, Path]]):
            Path to the TOML configuration file.
            If `None`, looks for `pyproject.toml` in current directory.
            Default: `None`.

    Raises:
        (FileNotFoundError):
            If the specified config file doesn't exist.
        (InvalidConfigError):
            If the configuration is invalid.

    Returns:
        (Config):
            Configuration object containing global settings and section definitions.
    """
    # Resolve config file path
    resolved_path = _resolve_config_path(config_path)
    if resolved_path is None:
        return DEFAULT_CONFIG

    # Parse TOML configuration
    config_data = _parse_toml_file(resolved_path)

    # Extract tool configuration
    tool_config = _extract_tool_config(config_data)
    if tool_config is None:
        return DEFAULT_CONFIG

    # Parse configuration components
    global_config = _parse_global_config(tool_config)
    sections_config = _parse_sections_config(tool_config)

    return Config(global_config=global_config, sections=sections_config)

find_config_file

find_config_file(
    start_path: Optional[Path] = None,
) -> Optional[Path]

Summary

Find configuration file by searching up the directory tree.

Parameters:

Name	Type	Description	Default
start_path	Optional[Path]	Directory to start searching from. If None, resolves to current directory. Default: None.	None

Returns:

Type	Description
Optional[Path]	Path to the configuration file if found, None otherwise.

Source code in src/docstring_format_checker/config.py

def find_config_file(start_path: Optional[Path] = None) -> Optional[Path]:
    """
    !!! note "Summary"
        Find configuration file by searching up the directory tree.

    Params:
        start_path (Optional[Path]):
            Directory to start searching from.
            If `None`, resolves to current directory.
            Default: `None`.

    Returns:
        (Optional[Path]):
            Path to the configuration file if found, None otherwise.
    """
    if start_path is None:
        start_path = Path.cwd()

    current_path: Path = start_path.resolve()

    while current_path != current_path.parent:
        pyproject_path: Path = current_path.joinpath("pyproject.toml")
        if pyproject_path.exists():
            # Check if it contains dfc configuration
            try:
                with open(pyproject_path, "rb") as f:
                    config_data: dict[str, Any] = tomllib.load(f)
                    if "tool" in config_data and (
                        "dfc" in config_data["tool"] or "docstring-format-checker" in config_data["tool"]
                    ):
                        return pyproject_path
            except Exception:
                pass

        current_path = current_path.parent

    return None