Add Validate Click Option With Callback as a Python TIL

python/validate-click-option-with-callback.md

@@ -0,0 +1,64 @@
+# Validate Click Option With Callback
+
+I have a [click](https://click.palletsprojects.com/en/stable/) subcommand in my
+[`py-vmt` project](https://github.com/jbranchaud/py-vmt) that includes an
+`option` specified with the `--at` flag. This is what it originally looked like:
+
+```python
+# define `start` subcommand
+@cli.command()
+@click.argument("project-name")
+@click.option("--at", help='Relative time in past to start the time, e.g. "2 hours ago", "33 minutes ago"')
+@pass_cli
+def start(cli_ctx: CliContext, project_name: str, at: str | None) -> None:
+    # ...
+```
+
+The value of `at` needs to be in the past. I need a way validate that it is or
+otherwise bail early with a useful error message. The optional
+[`callback`](https://click.palletsprojects.com/en/stable/advanced/#callbacks-for-validation)
+to `@click.option` plus `click.BadParameter` are a good way to handle that.
+
+First, I define a callback handler that does the validation. I even take it a
+step further and have it return the transformed value (`datetime`) that the
+subcommand logic will need.
+
+```python
+def validate_past_time(_ctx, _param, value: str | None) -> datetime:
+    now = datetime.now(timezone.utc)
+
+    if value == None:
+        return now
+
+    start_at = time_helpers.parse_to_datetime(value)
+
+    if start_time == None or start_at > now:
+        raise click.BadParameter("must be a relative time in the past")
+
+    return start_at
+```
+
+I ignore the first two arguments because I only need to work with `value`. Value
+might be something like `"33 minutes ago"` and I attempt to transform that with
+`dateparser` into a `datetime` instance. If it can't be parsed or it isn't in
+the past, then I raise `click.BadParameter` which presents the user with useful
+usage details.
+
+This callback can then be incorporated into the subcommand like so:
+
+```python
+# define `start` subcommand
+@cli.command()
+@click.argument("project-name")
+@click.option(
+    "--at",
+    help='Relative time in past to start the time, e.g. "2 hours ago", "33 minutes ago"',
+    callback=validate_past_time
+)
+@pass_cli
+def start(cli_ctx: CliContext, project_name: str, at: datetime) -> None:
+    # ...
+```
+
+Now I can expect the incoming `at` option to be a `datetime` which helps
+simplify several lines of logic in the `start` implementation.