Switch from docopt to click

[jsf9k]

🗣 Description

This pull request switches from docopt to click for our CLI argument-parsing needs.

💭 Motivation and context

I noticed that installing docopt generates warnings because it still uses a setup.py file versus a pyproject.toml file. Investigating further, I found that docopt hasn't seen any updates since 2014. I figured now would be a good time to start looking at alternatives.

The main two alternatives right now are click and typer. The former is a bit more verbose, whereas the latter is a bit more opinionated but also more Pythonic. typer uses click under the hood and leverages type hints to do some work for you. Both can generate tab completion for various shells.

See also #175 for the typer implementation. We can choose which one we like better.

🧪 Testing

All automated tests pass.

✅ Pre-approval checklist

• This PR has an informative and human-readable title.
• Changes are limited to a single goal - eschew scope creep!
• All relevant type-of-change labels have been added.
• I have read the CONTRIBUTING document.
• These code changes follow cisagov code standards.
• Tests have been added and/or modified to cover the changes in this PR.
• All new and existing tests pass.
• Bump major, minor, patch, pre-release, and/or build versions as appropriate via the bump_version script if this repository is versioned and the changes in this PR warrant a version bump.
• Create a pre-release (necessary if and only if the pre-release version was bumped).

✅ Pre-merge checklist

• Finalize version.

✅ Post-merge checklist

• Create a release (necessary if and only if the version was bumped).

[jsf9k]

I personally like this implementation better. You have to repeat yourself a little because click doesn't pick up the CLI argument types from the type hints, but I think the intent is clearer.

[dav3r]

I think both typer and click seem fine for our needs. I asked Google about it and here's what it came back with:

Pick Typer if: You want a modern developer experience with excellent autocompletion and less boilerplate. It is ideal if you are already using FastAPI, as it shares the same design philosophy.

Pick Click if: You need a proven, stable tool with maximum control and minimal dependencies. It is often preferred for very large, complex CLI structures where explicit control over every parameter is necessary.

Hybrid Approach: Because Typer is built on Click, you can use Typer for your main interface but drop down into Click for advanced features that Typer might not yet support.

That being said, I have no major preference here and will gladly go with whichever one our team feels more strongly about.

Additional info from Google:

[jsf9k]

Any thoughts, @felddy and @mcdonnnj? I'm leaning toward this implementation and @dav3r is OK with either.

[felddy]

Nice conversion. I like this over #175. I agree that it is more Pythonic.

[Copilot]

Pull request overview

This PR migrates the project CLI from docopt/schema to click, updating the entrypoints and tests accordingly.

Changes:

• Replaced docopt-based parsing/validation with a click command (setup_logging_and_divide) and parameter validation callbacks.
• Updated tests to use click.testing.CliRunner and adjusted expectations for Click-style exit codes/output.
• Updated packaging metadata: dependencies, console script target, and pre-commit mypy deps.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/test_example.py	Switches CLI tests to invoke the Click command via CliRunner and updates assertions.
src/example/example.py	Replaces docopt CLI with Click command/options/arguments and adds Rich logging handler + callbacks.
src/example/_version.py	Bumps project version for the prerelease.
src/example/main.py	Updates module entrypoint to run the Click command.
src/example/init.py	Updates exported API names to match renamed functions/command.
pyproject.toml	Swaps dependencies and changes the console script entrypoint to the Click command.
.pre-commit-config.yaml	Removes mypy stub dependency associated with docopt.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[dav3r]

🎉

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[rm-sbin-sh]

See comments. Looks good.

[mcdonnnj]

So I have a more general issue after reviewing this PR and looking up more about Click. I know that it is a popular options, however I am not a fan of the forced decorator approach and how functions get wrapped to start. The use of either the .callback() attribute or using invoke() make reusability of functions difficult. You are forced to either use the above methods or create CLI command wrapper functions that in turn access the real functionality.

I much prefer the ability to use dataclasses or dataclass-like objects (Pydantic models/dataclasses for example) to define command behavior using Python type hints. There are a number of options out there so I'm not trying to sell a particular one, but as an example I migrated the library to cappa in the improvement/switch_to_cappa_from_docopt branch just for an example of what that would look like. There are other options in a similar vein such as Clypi and tyro.

[jsf9k]

as an example I migrated the library to cappa in the improvement/switch_to_cappa_from_docopt branch just for an example of what that would look like. There are other options in a similar vein such as Clypi and tyro.

Those libraries are nicer but appear to mostly depend on the work of a single developer. One advantage of click is that it's widely used and hence less likely to become unsupported on us.

That said, I think @cisagov/vm-dev should come to a consensus and we should go with whatever is decided.

[dav3r]

as an example I migrated the library to cappa in the improvement/switch_to_cappa_from_docopt branch just for an example of what that would look like. There are other options in a similar vein such as Clypi and tyro.

Those libraries are nicer but appear to mostly depend on the work of a single developer. One advantage of click is that it's widely used and hence less likely to become unsupported on us.

That said, I think @cisagov/vm-dev should come to a consensus and we should go with whatever is decided.

I agree with @jsf9k that a widely-used library like click with a lot of contributors outweighs the benefits of those other libraries pointed out by @mcdonnnj. In the future, if one of those other libraries gains momentum and more dev support, we could switch again. Until then, I'm on team click.

[felddy]

I think click is the way to go. It's got a healthy base of contributors, and seems to have good momentum. The maintainers are communicative and seem to be disciplined. I appreciate that they're planning in the open:

• Click future direction pallets/click#3147

I would like to see some of the typing features the other libraries support, and hope they appear in the future.