Command-line interface

Command-line interface#

The check-dev-files checks are also exposed through a short Typer-based policy command. Running policy without a subcommand runs every check at once, exactly like the check-dev-files pre-commit hook. The subcommands group the checks by domain, so you can run just a subset.

You do not need to install anything: with uv, uvx fetches and runs the command on the fly. For example, to see which subcommands are available:

uvx --from git+https://github.com/ComPWA/policy policy --help

Tip

uvx caches the Git checkout, so add --refresh directly after uvx to pull the latest commit from the default branch.

If you run the command often, you can install it as a persistent tool with uv tool install (or pipx install) and call policy directly, updating it with uv tool upgrade --reinstall compwa-policy. When the pwa command is installed alongside this package, the same command is also available as pwa policy ... through a pwa.commands entry point.

Hook arguments#

The check-dev-files hook (and the policy command without a subcommand) only accepts the options that are shared across the whole repository, such as --repo-name. These can be added to the args key in your .pre-commit-config.yaml file. Options scoped to a single area (for example, --no-pypi) are exposed on the matching subcommand and are configured through its [tool.compwa.policy.<group>] table. See Configuration for details.

The full command tree and its options are:

policy Usage: policy [OPTIONS] COMMAND [ARGS]... Standardize and synchronize the developer setup of a ComPWA repository. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--python--no-pythonSpecify whether    │ │this repository    │ │contains Python    │ │code (default:     │ │automatic          │ │detection).        │ │--dev-python-versi…<3.6|3.7|3.8|3.9|Specify the Python │ │3.10|3.11|3.12|3.version for your   │ │13|3.14>developer          │ │environment.       │ │[default: (3.13)]  │ │--package-manager<none|uv|conda|piSpecify which      │ │xi+uv|pixi|venv>package manager to │ │use for the        │ │project.           │ │[default: (uv)]    │ │--repo-name<str>Name of the        │ │repository. This   │ │can usually be     │ │found in the URL of│ │the repository on  │ │GitHub or GitLab.  │ │--repo-organization<str>Name of the        │ │organization under │ │which the          │ │repository lives.  │ │[default: (ComPWA)]│ │--repo-title<str>Title or full name │ │of the repository. │ │If not provided,   │ │this falls back to │ │the repo-name.     │ │--no-ruffDo not enforce Ruff│ │as a linter.       │ │--pytest-single-th…Run pytest without │ │the `-n` argument. │ │--doc-apt-packages<str>Comma- or          │ │space-separated    │ │list of APT        │ │packages that are  │ │required to build  │ │documentation.     │ │--install-completi…Install completion │ │for the current    │ │shell.             │ │--show-completionShow completion for│ │the current shell, │ │to copy it or      │ │customize the      │ │installation.      │ │--helpShow this message  │ │and exit.          │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ───────────────────────────────────────────────────────────────────╮ │python   Standardize Python tooling: pyproject, Ruff, Black, mypy,        │ │pyright, ty, pytest, pyupgrade.                                  │ │github   Standardize GitHub config: workflows, labels, Dependabot, Release│ │Drafter, lock upgrades.                                          │ │env      Standardize the developer environment: uv, Conda, Pixi, direnv.  │ │nb       Standardize Jupyter notebook config: Jupyter, nbstripout, Binder.│ │format   Standardize formatters and linters: Prettier, TOML, cSpell,      │ │EditorConfig, pre-commit.                                        │ │repo     Standardize miscellaneous repo files: citation, commitlint, VS   │ │Code, GitPod, Poe, Read the Docs.                                │ │migrate  Migrate hook args into a pyproject.toml policy table and relocate│ │nb hooks.                                                        │ │bootstrapDetect repository tooling, configure policy, and add its         │ │pre-commit hook.                                                 │ ╰──────────────────────────────────────────────────────────────────────────────╯
python Usage: policy python [OPTIONS] Standardize Python tooling: pyproject, Ruff, Black, mypy, pyright, ty, pytest, pyupgrade. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--python--no-pythonSpecify whether  │ │this repository  │ │contains Python  │ │code (default:   │ │automatic        │ │detection).      │ │--dev-python-ver…<3.6|3.7|3.8|3.9Specify the      │ │|3.10|3.11|3.12|Python version   │ │3.13|3.14>for your         │ │developer        │ │environment.     │ │[default: (3.13)]│ │--excluded-pytho…<str>Comma- or        │ │space-separated  │ │list of Python   │ │versions you do  │ │NOT want to      │ │support.         │ │--type-checker<mypy|pyright|tySpecify which    │ │>type checker to  │ │use for the      │ │project.         │ │--no-ruffDo not enforce   │ │Ruff as a linter.│ │--imports-on-topSort notebook    │ │imports on the   │ │top.             │ │--branch-coverage--no-branch-cov…Enable branch    │ │coverage in the  │ │Coverage.py      │ │pytest           │ │configuration.   │ │--pytest-single-…Run pytest       │ │without the `-n` │ │argument.        │ │--allow-vscode-c…Recommend the    │ │ryanluker.vscode…│ │extension and    │ │keep its         │ │settings, instead│ │of marking it as │ │an unwanted VS   │ │Code extension.  │ │--helpShow this message│ │and exit.        │ ╰──────────────────────────────────────────────────────────────────────────────╯
github Usage: policy github [OPTIONS] Standardize GitHub config: workflows, labels, Dependabot, Release Drafter,  lock upgrades. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--python--no-pythonSpecify whether    │ │this repository    │ │contains Python    │ │code (default:     │ │automatic          │ │detection).        │ │--dev-python-versi…<3.6|3.7|3.8|3.9|Specify the Python │ │3.10|3.11|3.12|3.version for your   │ │13|3.14>developer          │ │environment.       │ │[default: (3.13)]  │ │--allow-labelsDo not perform the │ │check on           │ │labels.toml.       │ │--no-github-actionsDo not add standard│ │GitHub Actions     │ │workflows that are │ │used across ComPWA │ │repositories. This │ │can be useful if   │ │you already have   │ │your own CI        │ │workflows that do  │ │the same as the    │ │workflows enforced │ │by the             │ │check-dev-files    │ │hook.              │ │--allow-deprecated…Allow deprecated CI│ │workflows, such as │ │ci-docs.yml.       │ │--github-pagesHost documentation │ │on GitHub Pages.   │ │--keep-pr-lintingDo not overwrite   │ │the PR linting     │ │workflow.          │ │--macos-python-ver…<str>Run the test job in│ │MacOS on a specific│ │Python version. Use│ │'disable' to not   │ │run the tests on   │ │MacOS.             │ │[default: (3.10)]  │ │--no-cdDo not add any     │ │GitHub workflows   │ │for continuous     │ │deployment.        │ │--no-milestonesThis repository    │ │does not use       │ │milestones and     │ │therefore no close │ │workflow.          │ │--no-pypiDo not publish     │ │package to PyPI.   │ │--no-version-branc…Do not push to     │ │matching           │ │major/minor version│ │branches upon      │ │tagging.           │ │--ci-skipped-tests<str>Avoid running CI   │ │test on the        │ │following Python   │ │versions.          │ │--doc-apt-packages<str>Comma- or          │ │space-separated    │ │list of APT        │ │packages that are  │ │required to build  │ │documentation.     │ │--environment-vari…<str>Comma- or          │ │space-separated    │ │list of environment│ │variables, e.g.    │ │PYTHONHASHSEED=0,S…│ │--pytest-single-th…Run pytest without │ │the `-n` argument. │ │--keep-workflow<str>Names of the GitHub│ │Actions workflows  │ │that should not be │ │updated or removed,│ │including the .yml │ │extension.         │ │--upgrade-frequency<monthly|quarterlAdd a workflow to  │ │y|semiannually>upgrade lock files,│ │like uv.lock,      │ │.pre-commit-config…│ │and pip            │ │.constraints/      │ │files. The argument│ │is the frequency of│ │the cron job.      │ │[default:          │ │(quarterly)]       │ │--repo-name<str>Name of the        │ │repository. This   │ │can usually be     │ │found in the URL of│ │the repository on  │ │GitHub or GitLab.  │ │--repo-organization<str>Name of the        │ │organization under │ │which the          │ │repository lives.  │ │[default: (ComPWA)]│ │--repo-title<str>Title or full name │ │of the repository. │ │If not provided,   │ │this falls back to │ │the repo-name.     │ │--helpShow this message  │ │and exit.          │ ╰──────────────────────────────────────────────────────────────────────────────╯
env Usage: policy env [OPTIONS] Standardize the developer environment: uv, Conda, Pixi, direnv. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--python--no-pythonSpecify whether   │ │this repository   │ │contains Python   │ │code (default:    │ │automatic         │ │detection).       │ │--dev-python-versi…<3.6|3.7|3.8|3.9|3Specify the Python│ │.10|3.11|3.12|3.13version for your  │ │|3.14>developer         │ │environment.      │ │[default: (3.13)] │ │--package-manager<none|uv|conda|pixSpecify which     │ │i+uv|pixi|venv>package manager to│ │use for the       │ │project.          │ │[default: (uv)]   │ │--environment-vari…<str>Comma- or         │ │space-separated   │ │list of           │ │environment       │ │variables, e.g.   │ │PYTHONHASHSEED=0,…│ │--keep-contributin…Do not update or  │ │remove the        │ │CONTRIBUTING.md   │ │file.             │ │--repo-name<str>Name of the       │ │repository. This  │ │can usually be    │ │found in the URL  │ │of the repository │ │on GitHub or      │ │GitLab.           │ │--repo-organization<str>Name of the       │ │organization under│ │which the         │ │repository lives. │ │[default:         │ │(ComPWA)]         │ │--helpShow this message │ │and exit.         │ ╰──────────────────────────────────────────────────────────────────────────────╯
nb Usage: policy nb [OPTIONS] Standardize Jupyter notebook config: Jupyter, nbstripout, Binder. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--package-manager<none|uv|conda|pixi+uvSpecify which package │ │|pixi|venv>manager to use for the│ │project.              │ │[default: (uv)]       │ │--dev-python-version<3.6|3.7|3.8|3.9|3.10|Specify the Python    │ │3.11|3.12|3.13|3.14>version for your      │ │developer environment.│ │[default: (3.13)]     │ │--no-binderDo not update the     │ │Binder configuration. │ │--no-ruffDo not enforce Ruff as│ │a linter.             │ │--allowed-cell-metada…<str>Comma-separated list  │ │of allowed metadata in│ │Jupyter notebook      │ │cells, e.g.           │ │editable,slideshow.   │ │--doc-apt-packages<str>Comma- or             │ │space-separated list  │ │of APT packages that  │ │are required to build │ │documentation.        │ │--exclude-dependency<str>Notebook dependency   │ │that policy must not  │ │install.              │ │--helpShow this message and │ │exit.                 │ ╰──────────────────────────────────────────────────────────────────────────────╯
format Usage: policy format [OPTIONS] Standardize formatters and linters: Prettier, TOML, cSpell, EditorConfig,  pre-commit. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--no-cspell-updateDo not enforce    │ │same cSpell       │ │configuration as  │ │other ComPWA      │ │repositories. This│ │can be useful if  │ │you have a more   │ │advanced          │ │configuration,    │ │like using        │ │different         │ │dictionaries for  │ │different file    │ │types.            │ │--tombi-errors-on…--no-tombi-error…Make the Tombi    │ │lint hook fail    │ │when it emits     │ │warnings.         │ │--toml-formatter<taplo|tombi>Choose the TOML   │ │formatter         │ │[default: (tombi)]│ │--helpShow this message │ │and exit.         │ ╰──────────────────────────────────────────────────────────────────────────────╯
repo Usage: policy repo [OPTIONS] Standardize miscellaneous repo files: citation, commitlint, VS Code, GitPod,  Poe, Read the Docs. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--python--no-pythonSpecify whether    │ │this repository    │ │contains Python    │ │code (default:     │ │automatic          │ │detection).        │ │--package-manager<none|uv|conda|piSpecify which      │ │xi+uv|pixi|venv>package manager to │ │use for the        │ │project.           │ │[default: (uv)]    │ │--dev-python-versi…<3.6|3.7|3.8|3.9|Specify the Python │ │3.10|3.11|3.12|3.version for your   │ │13|3.14>developer          │ │environment.       │ │[default: (3.13)]  │ │--gitpodCreate a GitPod    │ │config file.       │ │--keep-issue-templ…Do not remove the  │ │.github/ISSUE_TEMP…│ │directory.         │ │--helpShow this message  │ │and exit.          │ ╰──────────────────────────────────────────────────────────────────────────────╯
migrate Usage: policy migrate [OPTIONS] [config_file] Migrate hook args into a pyproject.toml policy table and relocate nb hooks. ╭─ Arguments ──────────────────────────────────────────────────────────────────╮ │config_file<path>Path to the .pre-commit-config.yaml file to      │ │migrate.                                         │ │[default: .pre-commit-config.yaml]               │ ╰──────────────────────────────────────────────────────────────────────────────╯ ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--dry-runOnly report the migration; do not modify any files.│ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯
bootstrap Usage: policy bootstrap [OPTIONS] Detect repository tooling, configure policy, and add its pre-commit hook. ╭─ Options ────────────────────────────────────────────────────────────────────╮ │--helpShow this message and exit.│ ╰──────────────────────────────────────────────────────────────────────────────╯

Bootstrapping an existing repository#

Run policy bootstrap in an existing repository to detect whether it contains Python code, which package manager it uses, and which type checkers are already configured. The command records those choices in pyproject.toml under [tool.compwa.policy] and adds the check-dev-files hook to .pre-commit-config.yaml, preserving existing configuration in both files.

uvx --from git+https://github.com/ComPWA/policy policy bootstrap