From d61103e28f04c99ceeef443e6612ab370cdd6436 Mon Sep 17 00:00:00 2001 From: Jaron Rosenau Date: Wed, 11 Mar 2026 16:18:48 -0700 Subject: [PATCH 1/3] rename extension from .rst to .md --- docs/{click-concepts.rst => click-concepts.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{click-concepts.rst => click-concepts.md} (100%) diff --git a/docs/click-concepts.rst b/docs/click-concepts.md similarity index 100% rename from docs/click-concepts.rst rename to docs/click-concepts.md From b9a652b5c4f14e9b67e83584db54860cf3299a4e Mon Sep 17 00:00:00 2001 From: Jaron Rosenau Date: Wed, 11 Mar 2026 17:13:28 -0700 Subject: [PATCH 2/3] refactor from rest to myst --- docs/click-concepts.md | 67 +++++++++++++++++++++--------------------- 1 file changed, 34 insertions(+), 33 deletions(-) diff --git a/docs/click-concepts.md b/docs/click-concepts.md index 79a7a3841c..93eb9a7c93 100644 --- a/docs/click-concepts.md +++ b/docs/click-concepts.md @@ -1,16 +1,17 @@ -Click Concepts -================ +# Click Concepts This section covers concepts about Click's design. -.. contents:: - :depth: 1 - :local: +```{contents} +--- +depth: 1 +local: true +--- +``` -.. _callback-evaluation-order: +(callback-evaluation-order)= -Callback Evaluation Order -------------------------- +## Callback Evaluation Order Click works a bit differently than some other command line parsers in that it attempts to reconcile the order of arguments as defined by the @@ -27,41 +28,41 @@ value as it happens, whereas a callback in Click is invoked after the value has been fully converted. Generally, the order of invocation is driven by the order in which the user -provides the arguments to the script; if there is an option called ``--foo`` -and an option called ``--bar`` and the user calls it as ``--bar ---foo``, then the callback for ``bar`` will fire before the one for ``foo``. +provides the arguments to the script; if there is an option called `--foo` +and an option called `--bar` and the user calls it as `--bar --foo`, then +the callback for `bar` will fire before the one for `foo`. There are three exceptions to this rule which are important to know: Eagerness: - An option can be set to be "eager". All eager parameters are - evaluated before all non-eager parameters, but again in the order as - they were provided on the command line by the user. +> An option can be set to be "eager". All eager parameters are +> evaluated before all non-eager parameters, but again in the order as +> they were provided on the command line by the user. - This is important for parameters that execute and exit like ``--help`` - and ``--version``. Both are eager parameters, but whatever parameter - comes first on the command line will win and exit the program. +> This is important for parameters that execute and exit like `--help` +> and `--version`. Both are eager parameters, but whatever parameter +> comes first on the command line will win and exit the program. Repeated parameters: - If an option or argument is split up on the command line into multiple - places because it is repeated -- for instance, ``--exclude foo --include - baz --exclude bar`` -- the callback will fire based on the position of - the first option. In this case, the callback will fire for - ``exclude`` and it will be passed both options (``foo`` and - ``bar``), then the callback for ``include`` will fire with ``baz`` - only. +> If an option or argument is split up on the command line into multiple +> places because it is repeated -- for instance, `--exclude foo --include +> baz --exclude bar` -- the callback will fire based on the position of +> the first option. In this case, the callback will fire for +> `exclude` and it will be passed both options (`foo` and +> `bar`), then the callback for `include` will fire with `baz` +> only. - Note that even if a parameter does not allow multiple versions, Click - will still accept the position of the first, but it will ignore every - value except the last. The reason for this is to allow composability - through shell aliases that set defaults. +> Note that even if a parameter does not allow multiple versions, Click +> will still accept the position of the first, but it will ignore every +> value except the last. The reason for this is to allow composability +> through shell aliases that set defaults. Missing parameters: - If a parameter is not defined on the command line, the callback will - still fire. This is different from how it works in optparse where - undefined values do not fire the callback. Missing parameters fire - their callbacks at the very end which makes it possible for them to - default to values from a parameter that came before. +> If a parameter is not defined on the command line, the callback will +> still fire. This is different from how it works in optparse where +> undefined values do not fire the callback. Missing parameters fire +> their callbacks at the very end which makes it possible for them to +> default to values from a parameter that came before. Most of the time you do not need to be concerned about any of this, but it is important to know how it works for some advanced cases. From 2be9c4c44b178449a70a37e6af18985dadfacedc Mon Sep 17 00:00:00 2001 From: "pre-commit-ci-lite[bot]" <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> Date: Thu, 12 Mar 2026 00:16:59 +0000 Subject: [PATCH 3/3] [pre-commit.ci lite] apply automatic fixes --- docs/click-concepts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/click-concepts.md b/docs/click-concepts.md index 93eb9a7c93..3e91ab4a5d 100644 --- a/docs/click-concepts.md +++ b/docs/click-concepts.md @@ -29,7 +29,7 @@ value has been fully converted. Generally, the order of invocation is driven by the order in which the user provides the arguments to the script; if there is an option called `--foo` -and an option called `--bar` and the user calls it as `--bar --foo`, then +and an option called `--bar` and the user calls it as `--bar --foo`, then the callback for `bar` will fire before the one for `foo`. There are three exceptions to this rule which are important to know: