Profiles

Pre-configured check profiles for different use cases

Check Profiles

pycmdcheck includes built-in profiles that bundle check configurations for common use cases. Profiles make it easy to apply consistent settings without specifying individual options.

Using Profiles

Command Line

Use the --profile option to apply a profile:

# Use the strict profile
pycmdcheck --profile strict

# Use the relaxed profile for initial adoption
pycmdcheck --profile relaxed

# Use CI-optimized settings
pycmdcheck --profile ci

List Available Profiles

Use --list-profiles to see all available profiles:

pycmdcheck --list-profiles

pyproject.toml

Set a default profile in your pyproject.toml:

[tool.pycmdcheck]
profile = "relaxed"

CLI --profile overrides the config file setting.

Built-in Profiles

strict

Use case: Maximum strictness, catching all potential issues.

Profile(
    name="strict",
    description="Fail on any issue including notes",
    error_on="note",
)

The strict profile:

• Runs all checks without skipping any
• Fails on any issue, including NOTE severity
• Ideal for mature packages that should meet all best practices

relaxed

Use case: Initial adoption or packages that don’t need all recommendations.

Profile(
    name="relaxed",
    description="Skip informational checks (NOTE severity)",
    skip_ids=["CQ002", "CQ003", "DC002", "DP002"],
    error_on="error",
)

The relaxed profile:

• Skips NOTE severity checks:
  • CQ002 (HasTypeHints) - py.typed marker
  • CQ003 (NoTODOsInCode) - TODO/FIXME comments
  • DC002 (HasDocsDirectory) - docs/ directory
  • DP002 (HasLockfile) - lockfile presence
• Only fails on ERROR severity issues
• Good for getting started with pycmdcheck

ci

Use case: CI/CD pipelines where speed matters.

Profile(
    name="ci",
    description="Optimized for CI pipelines",
    skip_ids=["SC003"],
    error_on="warning",
)

The ci profile:

• Skips slow checks like vulnerability scanning (SC003)
• Fails on WARNING or ERROR severity
• Optimized for fast CI feedback

release

Use case: Pre-release validation focusing on critical checks.

Profile(
    name="release",
    description="Focus on release-critical checks",
    only_groups=["structure", "metadata", "release", "security"],
    error_on="warning",
)

The release profile:

• Only runs checks in critical groups:
  • structure - README, LICENSE, pyproject.toml
  • metadata - name, version, description, requires-python
  • release - changelog, valid version
  • security - security-related checks
• Fails on WARNING or ERROR severity
• Focused validation before publishing

Profile Precedence

When a profile is combined with other settings, the precedence is:

1. CLI options (highest priority)
2. pyproject.toml settings
3. Profile defaults (lowest priority)

This means you can use a profile as a base and override specific settings:

[tool.pycmdcheck]
profile = "relaxed"
skip = ["ST001"]  # Also skip README check

# Use relaxed but fail on warnings too
pycmdcheck --profile relaxed --error-on warning

Custom Profiles

Currently, pycmdcheck only supports the built-in profiles. Custom profile support via plugins is planned for a future release.

For now, you can achieve similar results using pyproject.toml configuration:

[tool.pycmdcheck]
skip = ["CQ002", "CQ003"]
skip_groups = ["tests"]
error_on = "warning"

API Usage

Profiles can also be used programmatically:

from pycmdcheck.profiles import get_profile, list_profiles, apply_profile
from pycmdcheck.config import Config

# Get a specific profile
profile = get_profile("strict")
print(profile.name)  # "strict"
print(profile.error_on)  # "note"

# List all profiles
for p in list_profiles():
    print(f"{p.name}: {p.description}")

# Apply profile to config
config = Config(skip_ids=["ST001"])  # Keep this override
new_config = apply_profile(config, profile)

The apply_profile() function merges profile settings with existing config, where explicit config values take precedence over profile defaults.