Configuration Management

def injectDefaultOptionsFromUserSpecifiedTomlFilePath(
    ctx: click.Context,
    param: click.Parameter,
    value: str | None,
) -> str | None:
    """
    Inject default options from user-specified .toml file path.
    
    Loads configuration from a custom TOML file and injects the settings
    into the click context as default values for command-line options.
    
    Parameters:
    - ctx: Click context for command-line processing
    - param: Click parameter (placeholder, not used)
    - value: Full path to the TOML configuration file
    
    Returns:
    str | None: The full path of the TOML file, or None if not provided
    """

def parseToml(paths: Sequence[str] | None) -> dict[str, Any]:
    """
    Parse the pyproject.toml located in the common parent of paths.
    
    Finds and parses pyproject.toml configuration in the common parent
    directory of the provided paths, extracting pydoclint configuration.
    
    Parameters:
    - paths: Sequence of file/directory paths to determine common parent
    
    Returns:
    dict[str, Any]: Parsed configuration dictionary
    """

def parseOneTomlFile(tomlFilename: Path) -> dict[str, Any]:
    """
    Parse a single TOML configuration file.
    
    Reads and parses a TOML file, extracting pydoclint-specific configuration
    from the [tool.pydoclint] section.
    
    Parameters:
    - tomlFilename: Path to TOML file to parse
    
    Returns:
    dict[str, Any]: Configuration dictionary with pydoclint settings
    
    Raises:
    FileNotFoundError: If TOML file doesn't exist
    tomllib.TOMLDecodeError: If TOML file is malformed
    """

def updateCtxDefaultMap(ctx: click.Context, config: dict[str, Any]) -> None:
    """
    Update click context default map with configuration values.
    
    Merges configuration values into the click context's default map,
    allowing TOML configuration to serve as defaults for command-line options.
    
    Parameters:
    - ctx: Click context to update
    - config: Configuration dictionary to merge
    """

def getCommonParentOfFiles(paths: Sequence[str]) -> Path:
    """
    Get common parent directory of multiple file paths.
    
    Determines the deepest common parent directory containing all
    specified paths, used for locating configuration files.
    
    Parameters:
    - paths: Sequence of file/directory paths
    
    Returns:
    Path: Common parent directory path
    """

def locateConfigFile(
    startPath: Path,
    configFilename: str = "pyproject.toml"
) -> Path | None:
    """
    Locate configuration file by searching up directory tree.
    
    Searches from startPath upward through parent directories to find
    the specified configuration file.
    
    Parameters:
    - startPath: Directory to start searching from
    - configFilename: Name of configuration file to locate
    
    Returns:
    Path | None: Path to configuration file if found, None otherwise
    """

[tool.pydoclint]
style = "numpy"
exclude = '\.git|\.tox|tests/'
arg-type-hints-in-signature = true
arg-type-hints-in-docstring = true
check-arg-order = true
skip-checking-short-docstrings = true
skip-checking-raises = false
allow-init-docstring = false
check-return-types = true
check-yield-types = true
ignore-underscore-args = true
ignore-private-args = false
check-class-attributes = true
should-document-private-class-attributes = false
treat-property-methods-as-class-attributes = false
require-return-section-when-returning-nothing = false
require-yield-section-when-yielding-nothing = false
only-attrs-with-ClassVar-are-treated-as-class-attrs = false
should-document-star-arguments = true
should-declare-assert-error-if-assert-statement-exists = false
check-style-mismatch = false
check-arg-defaults = false

# Use custom configuration file
pydoclint --config=custom-pydoclint.toml src/

# Configuration file: custom-pydoclint.toml
[tool.pydoclint]
style = "google"
exclude = "tests/|migrations/|__pycache__/"
check-class-attributes = true
check-return-types = true
show-filenames-in-every-violation-message = true

from pathlib import Path
from pydoclint.parse_config import parseOneTomlFile, parseToml

# Load specific configuration file
config_path = Path("pyproject.toml")
config = parseOneTomlFile(config_path)

# Auto-discover configuration from paths
paths = ["src/module1.py", "src/module2.py"]
config = parseToml(paths)

# Use configuration
style = config.get("style", "numpy")
exclude_pattern = config.get("exclude", r"\.git|\.tox")
check_returns = config.get("check-return-types", True)

# pyproject.toml has style = "google"
# Command line overrides with --style=numpy
pydoclint --style=numpy src/  # Uses numpy style

# TOML configuration is used for unspecified options
# pyproject.toml has check-return-types = true
pydoclint --style=numpy src/  # Uses numpy style AND check-return-types = true

# Production-ready configuration
[tool.pydoclint]
style = "google"
exclude = '''
    \.git|
    \.venv|
    \.tox|
    __pycache__|
    \.pytest_cache|
    build/|
    dist/|
    docs/_build/|
    tests/fixtures/|
    migrations/
'''
arg-type-hints-in-signature = true
arg-type-hints-in-docstring = true
check-arg-order = true
check-return-types = true
check-yield-types = true
check-class-attributes = true
ignore-underscore-args = true
skip-checking-short-docstrings = true
require-return-section-when-returning-nothing = false
should-document-star-arguments = true

# Strict configuration for new projects
[tool.pydoclint]
style = "numpy"
check-return-types = true
check-yield-types = true  
check-class-attributes = true
check-style-mismatch = true
require-return-section-when-returning-nothing = true
require-yield-section-when-yielding-nothing = true
should-document-star-arguments = true
should-declare-assert-error-if-assert-statement-exists = true
ignore-underscore-args = false
ignore-private-args = false
skip-checking-short-docstrings = false

# Legacy codebase configuration with baseline
[tool.pydoclint]
style = "sphinx"
exclude = "legacy/|deprecated/"
skip-checking-short-docstrings = true
skip-checking-raises = true
allow-init-docstring = true
ignore-underscore-args = true
ignore-private-args = true
baseline = "pydoclint-baseline.txt"
auto-regenerate-baseline = true